From c7a8a8387048d1ac7e245cca2ce4cce934739e28 Mon Sep 17 00:00:00 2001 From: Adnan Rahic Date: Tue, 17 Dec 2024 11:50:45 +0100 Subject: [PATCH 1/2] chore: update readme --- README.md | 186 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 144 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 50677ab89..08a721247 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,151 @@ -# BindPlane Agent + +

+ + + + BindPlane Logo + +

+ + +

+ The BindPlane Agent is observIQ’s distribution of the upstream OpenTelemetry Collector. It’s the first distribution to implement the Open Agent Management Protocol (OpAMP) and is designed to be fully managed with BindPlane Telemetry Pipeline. +

+ + +

+ + Get Started!  👉  + +

+ + + +

+ Website |  + Docs |  + How-to Guides |  + Feature Guides |  + Blog |  + OTel Hub |  + Slack +

+ + + +

+ + Action Status + + + Action Test Status + + + Go Report Card + + + License + +

+ +

+ +

+

+ + Learn how to connect BindPlane Agent to telemetry sources and destinations, and use processors to transform data. + +

+ +## Why BindPlane Agent? + +If you're managing telemetry at scale you'll run in to these problems sooner or later: + +1. **Agent fatigue.** You'll manage endless proprietary agents and OpenTelemetry Collectors that collect and forward telemetry to different observability backends, leading to performance issues. +2. **Endless configuration files.** Even with GitOps practices you'll have to manage hundreds of configuration files for different sources, destinations, and processors written in either proprietary languages or YAML. +3. **High complexity.** OpenTelemetry's complexity and learning curve make it difficult to implement, manage, and re-point telemetry without a centralized management plane like BindPlane Telemetry Pipeline to standardize telemetry ingestion, processing, and shipping, with a unified, OpenTelemetry-native pipeline. + +### An OpenTelemetry Collector you're used to + +The BindPlane Agent is observIQ’s distribution of the upstream [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector). It’s the first distribution to implement the [Open Agent Management Protocol](https://opentelemetry.io/docs/specs/opamp/) (OpAMP) and is designed to be fully managed with [BindPlane Telemetry Pipeline](https://observiq.com/solutions). -
+### Focused on usability -[![Action Status](https://github.com/observIQ/bindplane-otel-collector/workflows/Build/badge.svg)](https://github.com/observIQ/bindplane-otel-collector/actions) -[![Action Test Status](https://github.com/observIQ/bindplane-otel-collector/workflows/Tests/badge.svg)](https://github.com/observIQ/bindplane-otel-collector/actions) -[![Go Report Card](https://goreportcard.com/badge/github.com/observIQ/bindplane-otel-collector)](https://goreportcard.com/report/github.com/observIQ/bindplane-otel-collector) -[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) +Increases the accessibility of OpenTelemetry by providing simplified installation scripts, tested example configurations, and end-to-end documentation making it easy to get started. -
+### All the best parts of OpenTelemetry and more -The BindPlane Agent is observIQ’s distribution of the [OpenTelemetry collector](https://github.com/open-telemetry/opentelemetry-collector). It’s the first distribution to implement the [Open Agent Management Protocol](https://opentelemetry.io/docs/specs/opamp/) (OpAMP) and is designed to be fully managed with [BindPlane OP](https://observiq.com/). To get started, follow our [Quickstart Guide](https://observiq.com/docs/getting-started/quickstart-guide). +Bundled with all core OpenTelemetry receivers, processors, and exporters as well as additional capabilities for monitoring complex or enterprise technologies not yet available in upstream releases -## Benefits +### Always production-ready and fully-supported -### Focused on usability -Increases the accessibility of OpenTelemetry by providing simplified installation scripts, tested example configurations, and end-to-end documentation making it easy to get started +Tested, verified, and supported by observIQ. -### All the best parts of OpenTelemetry and more -Bundled with all core OpenTelemetry receivers, processors, and exporters as well as additional capabilities for monitoring complex or enterprise technologies not yet available in upstream releases - -### Always Production-ready and fully-supported -Tested, verified, and supported by observIQ +## Getting Started + +Follow the [Getting Started](/docs/getting-started.md) guide for more detailed installation instructions, or view the list of [Supported Operating System Versions](https://observiq.com/docs/advanced-setup/installation/install-agent). -## Quick Start +To continue with the quick start, follow along below. -### Installation +### Linux -#### Linux +Install BindPlane Agent using the installation script below. -To install using the installation script, you may run: ```sh -sudo sh -c "$(curl -fsSlL https://github.com/observIQ/bindplane-otel-collector/releases/latest/download/install_unix.sh)" install_unix.sh +sudo sh -c "$(curl -fsSlL https://github.com/observiq/bindplane-agent/releases/latest/download/install_unix.sh)" install_unix.sh ``` -To install directly with the appropriate package manager, see [installing on Linux](/docs/installation-linux.md). +To install directly with the appropriate package manager, and how to configure OpAMP, see [installing on Linux](/docs/installation-linux.md). -#### Windows +### Windows To install the BindPlane Agent on Windows run the Powershell command below to install the MSI with no UI. + ```pwsh -msiexec /i "https://github.com/observIQ/bindplane-otel-collector/releases/latest/download/observiq-otel-collector.msi" /quiet +msiexec /i "https://github.com/observIQ/bindplane-agent/releases/latest/download/observiq-otel-collector.msi" /quiet ``` -Alternately, for an interactive installation [download the latest MSI](https://github.com/observIQ/bindplane-otel-collector/releases/latest). +Alternately, for an interactive installation [download the latest MSI](https://github.com/observIQ/bindplane-agent/releases/latest). After downloading the MSI, simply double click it to open the installation wizard. Follow the instructions to configure and install the agent. -For more installation information see [installing on Windows](/docs/installation-windows.md). +For more installation information, and how to configure OpAMP, see [installing on Windows](/docs/installation-windows.md). -#### macOS +### macOS -To install using the installation script, you may run: +Install BindPlane Agent using the installation script below. ```sh -sudo sh -c "$(curl -fsSlL https://github.com/observIQ/bindplane-otel-collector/releases/latest/download/install_macos.sh)" install_macos.sh +sudo sh -c "$(curl -fsSlL https://github.com/observiq/bindplane-agent/releases/latest/download/install_macos.sh)" install_macos.sh ``` -For more installation information see [installing on macOS](/docs/installation-mac.md). +For more installation information, and how to configure OpAMP, see [installing on macOS](/docs/installation-mac.md). + +## Next Steps -### Next Steps +### BindPlane Agent default `config.yaml` -Now that the agent is installed it is collecting basic metrics about the host machine printing them to the log. If you want to further configure your agent you may do so by editing the config file. To find your config file based on your OS reference the table below: +With the BindPlane Agent installed, it will start collecting basic metrics about the host machine printing them to the log. To further configure your agent edit the `config.yaml` file just like you would an OpenTelemetry Collector. To find your `config.yaml` file based on your operating system, reference the table below: | OS | Default Location | |:--------|:--------------------------------------------------------------| -| Linux | /opt/observiq-otel-collector/config.yaml | -| Windows | C:\Program Files\observIQ OpenTelemetry Collector\config.yaml | -| macOS | /opt/observiq-otel-collector/config.yaml | +| Linux | `/opt/observiq-otel-collector/config.yaml` | +| Windows | `C:\Program Files\observIQ OpenTelemetry Collector\config.yaml` | +| macOS | `/opt/observiq-otel-collector/config.yaml` | For more information on configuration see the [Configuration section](#configuration). +### Manage BindPlane Agent with BindPlane Telemetry Pipeline via OpAMP + +Improving developer experience with OpenTelemetry is observIQ's primary focus. We're building BindPlane Telemetry Pipeline to help deploy and manage OpenTelemetry Collectors at scale, but retain core OpenTelemetry Standards for terminology and configuration, with the added benefit of enabling remote management with OpAMP. + +The BindPlane Agent can be configured as an OpenTelemetry Collector that is managed by the BindPlane Telemetry Pipeline via OpAMP. BindPlane is designed to be OpenTelemetry-first, with OpenTelemetry as its core framework. By providing a centralized management plane, it simplifies the development, implementation, management, and configuration of OpenTelemetry. + +For more information on managing agents via OpAMP see the [Connecting to BindPlane Telemetry Pipeline with OpAMP section](#connecting-to-bindplane-telemetry-pipeline-with-opamp). + ## Configuration -The BindPlane Agent uses OpenTelemetry configuration. +The BindPlane Agent uses OpenTelemetry Collector configuration. For sample configs, see the [config](/config/) directory. For general configuration help, see the [OpenTelemetry docs](https://opentelemetry.io/docs/collector/configuration/). @@ -103,9 +176,9 @@ For supported extensions and their documentation see [extensions](/docs/extensio For supported connectors and their documentation see [connectors](/docs/connectors.md). -## Example +### Example `config.yaml` -Here is an example `config.yaml` setup for hostmetrics on Google Cloud. To make sure your environment is set up with required prerequisites, see our [Google Cloud Exporter Prerequisites](/config/google_cloud_exporter/README.md) page. Further details for this GCP example can be found [here](/config/google_cloud_exporter/hostmetrics). +Here's a sample setup for `hostmetrics` on Google Cloud. To make sure your environment is set up with required prerequisites, see the [Google Cloud Exporter Prerequisites](/config/google_cloud_exporter/README.md) page. Further details for this GCP example can be found [here](/config/google_cloud_exporter/hostmetrics). ```yaml # Receivers collect metrics from a source. The hostmetrics receiver will get @@ -135,10 +208,39 @@ service: exporters: [googlecloud] ``` -# Community +## Connecting to BindPlane Telemetry Pipeline with OpAMP + +BindPlane is designed to be OpenTelemetry-first, with OpenTelemetry as its core framework, to create a unified toolset with data ownership. By providing a centralized management plane, it simplifies the development, implementation, management, and configuration of OpenTelemetry. + +To learn more about configuring OpAMP, see [OpAMP Configuration](/docs/opamp.md), or get started with BindPlane Telemetry Pipeline below. + +### BindPlane Cloud + +BindPlane Cloud is the quickest way to get started with OpenTelemetry-native telemetry pipelines. It offers managed infrastructure along with instant, free access for development projects and proofs of concept. + +Sign-up + +### BindPlane On Prem + +You can also get started with BindPlane On Prem for free by hosting it yourself. + +Download + +## Community + +Have an idea to improve BindPlane Agent? Here's how you can help: + +- Star this repo ⭐️ and follow us on [Twitter](https://x.com/bindplane). +- Upvote issues with 👍 so we know what to prioritize in the road map. +- [Create issues](https://github.com/observIQ/bindplane-agent/issues) when you feel something is missing or wrong. +- Join our [Slack Community](https://www.launchpass.com/bindplane), and ask us any questions there. + +## Contributing + +The BindPlane Agent is an open source project. If you'd like to contribute, take a look at our [contribution guidelines](/CONTRIBUTING.md) and [developer guide](/docs/development.md). -The BindPlane Agent is an open source project. If you'd like to contribute, take a look at our [contribution guidelines](/CONTRIBUTING.md) and [developer guide](/docs/development.md). We look forward to building with you. +All sorts of contributions are **welcome and extremely helpful**. 🙌 -# How can we help? +## How can we help? -If you need any additional help feel free to file a GitHub issue or reach out to us at support@observiq.com. +If you need any additional help feel free to reach out to us at support@observiq.com. From 172e18ac1785dc6f82eade74c035bda50728cbb5 Mon Sep 17 00:00:00 2001 From: Adnan Rahic Date: Tue, 17 Dec 2024 12:08:25 +0100 Subject: [PATCH 2/2] chore: Update naming to BDOT Collector --- README.md | 58 +++++++++++++++++++++++++++---------------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 08a721247..be75b5e10 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@

- The BindPlane Agent is observIQ’s distribution of the upstream OpenTelemetry Collector. It’s the first distribution to implement the Open Agent Management Protocol (OpAMP) and is designed to be fully managed with BindPlane Telemetry Pipeline. + The BindPlane Distro for OpenTelemetry Collector (BDOT Collector) is observIQ’s distribution of the upstream OpenTelemetry Collector. It’s the first distribution to implement the Open Agent Management Protocol (OpAMP) and is designed to be fully managed with BindPlane Telemetry Pipeline.

@@ -34,14 +34,14 @@

- - Action Status + + Action Status - - Action Test Status + + Action Test Status - - Go Report Card + + Go Report Card License @@ -53,11 +53,11 @@

- Learn how to connect BindPlane Agent to telemetry sources and destinations, and use processors to transform data. + Learn how to connect BindPlane Distro for OpenTelemetry Collector to telemetry sources and destinations, and use processors to transform data.

-## Why BindPlane Agent? +## Why BindPlane Distro for OpenTelemetry Collector? If you're managing telemetry at scale you'll run in to these problems sooner or later: @@ -67,7 +67,7 @@ If you're managing telemetry at scale you'll run in to these problems sooner or ### An OpenTelemetry Collector you're used to -The BindPlane Agent is observIQ’s distribution of the upstream [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector). It’s the first distribution to implement the [Open Agent Management Protocol](https://opentelemetry.io/docs/specs/opamp/) (OpAMP) and is designed to be fully managed with [BindPlane Telemetry Pipeline](https://observiq.com/solutions). +The BDOT Collector is observIQ’s distribution of the upstream [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector). It’s the first distribution to implement the [Open Agent Management Protocol](https://opentelemetry.io/docs/specs/opamp/) (OpAMP) and is designed to be fully managed with [BindPlane Telemetry Pipeline](https://observiq.com/solutions). ### Focused on usability @@ -89,43 +89,43 @@ To continue with the quick start, follow along below. ### Linux -Install BindPlane Agent using the installation script below. +Install BDOT Collector using the installation script below. ```sh -sudo sh -c "$(curl -fsSlL https://github.com/observiq/bindplane-agent/releases/latest/download/install_unix.sh)" install_unix.sh +sudo sh -c "$(curl -fsSlL https://github.com/observiq/bindplane-otel-collector/releases/latest/download/install_unix.sh)" install_unix.sh ``` To install directly with the appropriate package manager, and how to configure OpAMP, see [installing on Linux](/docs/installation-linux.md). ### Windows -To install the BindPlane Agent on Windows run the Powershell command below to install the MSI with no UI. +To install the BDOT Collector on Windows run the Powershell command below to install the MSI with no UI. ```pwsh -msiexec /i "https://github.com/observIQ/bindplane-agent/releases/latest/download/observiq-otel-collector.msi" /quiet +msiexec /i "https://github.com/observIQ/bindplane-otel-collector/releases/latest/download/observiq-otel-collector.msi" /quiet ``` -Alternately, for an interactive installation [download the latest MSI](https://github.com/observIQ/bindplane-agent/releases/latest). +Alternately, for an interactive installation [download the latest MSI](https://github.com/observIQ/bindplane-otel-collector/releases/latest). -After downloading the MSI, simply double click it to open the installation wizard. Follow the instructions to configure and install the agent. +After downloading the MSI, simply double click it to open the installation wizard. Follow the instructions to configure and install the BDOT Collector. For more installation information, and how to configure OpAMP, see [installing on Windows](/docs/installation-windows.md). ### macOS -Install BindPlane Agent using the installation script below. +Install BDOT Collector using the installation script below. ```sh -sudo sh -c "$(curl -fsSlL https://github.com/observiq/bindplane-agent/releases/latest/download/install_macos.sh)" install_macos.sh +sudo sh -c "$(curl -fsSlL https://github.com/observiq/bindplane-otel-collector/releases/latest/download/install_macos.sh)" install_macos.sh ``` For more installation information, and how to configure OpAMP, see [installing on macOS](/docs/installation-mac.md). ## Next Steps -### BindPlane Agent default `config.yaml` +### BDOT Collector default `config.yaml` -With the BindPlane Agent installed, it will start collecting basic metrics about the host machine printing them to the log. To further configure your agent edit the `config.yaml` file just like you would an OpenTelemetry Collector. To find your `config.yaml` file based on your operating system, reference the table below: +With the BDOT Collector installed, it will start collecting basic metrics about the host machine printing them to the log. To further configure your collector edit the `config.yaml` file just like you would an OpenTelemetry Collector. To find your `config.yaml` file based on your operating system, reference the table below: | OS | Default Location | |:--------|:--------------------------------------------------------------| @@ -135,24 +135,24 @@ With the BindPlane Agent installed, it will start collecting basic metrics about For more information on configuration see the [Configuration section](#configuration). -### Manage BindPlane Agent with BindPlane Telemetry Pipeline via OpAMP +### Manage BDOT Collector with BindPlane Telemetry Pipeline via OpAMP Improving developer experience with OpenTelemetry is observIQ's primary focus. We're building BindPlane Telemetry Pipeline to help deploy and manage OpenTelemetry Collectors at scale, but retain core OpenTelemetry Standards for terminology and configuration, with the added benefit of enabling remote management with OpAMP. -The BindPlane Agent can be configured as an OpenTelemetry Collector that is managed by the BindPlane Telemetry Pipeline via OpAMP. BindPlane is designed to be OpenTelemetry-first, with OpenTelemetry as its core framework. By providing a centralized management plane, it simplifies the development, implementation, management, and configuration of OpenTelemetry. +The BDOT Collector can be configured as an OpenTelemetry Collector that is managed by the BindPlane Telemetry Pipeline via OpAMP. BindPlane is designed to be OpenTelemetry-first, with OpenTelemetry as its core framework. By providing a centralized management plane, it simplifies the development, implementation, management, and configuration of OpenTelemetry. -For more information on managing agents via OpAMP see the [Connecting to BindPlane Telemetry Pipeline with OpAMP section](#connecting-to-bindplane-telemetry-pipeline-with-opamp). +For more information on managing collectors via OpAMP see the [Connecting to BindPlane Telemetry Pipeline with OpAMP section](#connecting-to-bindplane-telemetry-pipeline-with-opamp). ## Configuration -The BindPlane Agent uses OpenTelemetry Collector configuration. +The BDOT Collector uses OpenTelemetry Collector configuration. For sample configs, see the [config](/config/) directory. For general configuration help, see the [OpenTelemetry docs](https://opentelemetry.io/docs/collector/configuration/). For configuration options of a specific component, take a look at the README found in their respective module roots. For a list of currently supported components see [Included Components](#included-components). -For a list of possible command line arguments to use with the agent, run the agent with the `--help` argument. +For a list of possible command line arguments to use with the BDOT Collector, run the collector with the `--help` argument. ### Included Components @@ -182,7 +182,7 @@ Here's a sample setup for `hostmetrics` on Google Cloud. To make sure your envir ```yaml # Receivers collect metrics from a source. The hostmetrics receiver will get -# CPU load metrics about the machine the agent is running on every minute. +# CPU load metrics about the machine the collector is running on every minute. receivers: hostmetrics: collection_interval: 60s @@ -228,16 +228,16 @@ You can also get started with BindPlane On Prem for free by hosting it yourself. ## Community -Have an idea to improve BindPlane Agent? Here's how you can help: +Have an idea to improve the BindPlane Distro for OpenTelemetry Collector? Here's how you can help: - Star this repo ⭐️ and follow us on [Twitter](https://x.com/bindplane). - Upvote issues with 👍 so we know what to prioritize in the road map. -- [Create issues](https://github.com/observIQ/bindplane-agent/issues) when you feel something is missing or wrong. +- [Create issues](https://github.com/observIQ/bindplane-otel-collector/issues) when you feel something is missing or wrong. - Join our [Slack Community](https://www.launchpass.com/bindplane), and ask us any questions there. ## Contributing -The BindPlane Agent is an open source project. If you'd like to contribute, take a look at our [contribution guidelines](/CONTRIBUTING.md) and [developer guide](/docs/development.md). +The BindPlane Distro for OpenTelemetry Collector is an open source project. If you'd like to contribute, take a look at our [contribution guidelines](/CONTRIBUTING.md) and [developer guide](/docs/development.md). All sorts of contributions are **welcome and extremely helpful**. 🙌