--- title: "Migrate from OpenTelemetry Collector to Grafana Agent Flow | Grafana Agent documentation" description: "Learn how to migrate from OpenTelemetry Collector to Grafana Agent Flow" --- # Migrate from OpenTelemetry Collector to Grafana Agent Flow The built-in Grafana Agent convert command can migrate your [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/configuration/) configuration to a Grafana Agent Flow configuration. This topic describes how to: - Convert an OpenTelemetry Collector configuration to a Grafana Agent Flow configuration. - Run an OpenTelemetry Collector configuration natively using Grafana Agent Flow. ## Components used in this topic - [otelcol.receiver.otlp](/docs/agent/v0.43/flow/reference/components/otelcol.receiver.otlp/) - [otelcol.processor.memory\_limiter](/docs/agent/v0.43/flow/reference/components/otelcol.processor.memory_limiter/) - [otelcol.exporter.otlp](/docs/agent/v0.43/flow/reference/components/otelcol.exporter.otlp/) ## Before you begin - You must have an existing OpenTelemetry Collector configuration. - You must have a set of OpenTelemetry Collector applications ready to push telemetry data to Grafana Agent Flow. - You must be familiar with the concept of [Components](/docs/agent/v0.43/flow/concepts/components/) in Grafana Agent Flow. ## Convert an OpenTelemetry Collector configuration To fully migrate your configuration from[OpenTelemetry Collector](https://opentelemetry.io/docs/collector/configuration/) to Grafana Agent Flow, you must convert your OpenTelemetry Collector configuration into a Grafana Agent Flow configuration. This conversion will enable you to take full advantage of the many additional features available in Grafana Agent Flow. > In this task, you will use the [convert](/docs/agent/v0.43/flow/reference/cli/convert/) CLI command to output a Grafana Agent Flow configuration from a OpenTelemetry Collector configuration. 1. Open a terminal window and run the following command. static-binary flow-binary ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy static-binary ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```static-binary AGENT_MODE=flow grafana-agent convert --source-format=otelcol --output= ``` flow-binary ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```flow-binary grafana-agent-flow convert --source-format=otelcol --output= ``` Replace the following: - *``* : The full path to the OpenTelemetry Collector configuration. - *``* : The full path to output the Grafana Agent Flow configuration. 2. [Run](/docs/agent/v0.43/flow/get-started/run/) Grafana Agent Flow using the new Grafana Agent Flow configuration from *``* : ### Debugging 1. If the `convert` command can’t convert an OpenTelemetry Collector configuration, diagnostic information is sent to `stderr`. You can bypass any non-critical issues and output the Grafana Agent Flow configuration using a best-effort conversion by including the `--bypass-errors` flag. > Caution > > If you bypass the errors, the behavior of the converted configuration may not match the original OpenTelemetry Collector configuration. Make sure you fully test the converted configuration before using it in a production environment. static-binary flow-binary ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy static-binary ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```static-binary AGENT_MODE=flow grafana-agent convert --source-format=otelcol --bypass-errors --output= ``` flow-binary ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```flow-binary grafana-agent-flow convert --source-format=otelcol --bypass-errors --output= ``` Replace the following: - *``* : The full path to the OpenTelemetry Collector configuration. - *``* : The full path to output the Grafana Agent Flow configuration. 2. You can also output a diagnostic report by including the `--report` flag. static-binary flow-binary ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy static-binary ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```static-binary AGENT_MODE=flow grafana-agent convert --source-format=otelcol --report= --output= ``` flow-binary ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```flow-binary grafana-agent-flow convert --source-format=otelcol --report= --output= ``` Replace the following: - *``* : The full path to the OpenTelemetry Collector configuration. - *``* : The full path to output the Grafana Agent Flow configuration. - *``* : The output path for the report. Using the [example](#example) OpenTelemetry Collector configuration below, the diagnostic report provides the following information: plaintext ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```plaintext (Info) Converted receiver/otlp into otelcol.receiver.otlp.default (Info) Converted processor/memory_limiter into otelcol.processor.memory_limiter.default (Info) Converted exporter/otlp into otelcol.exporter.otlp.default A configuration file was generated successfully. ``` ## Run an OpenTelemetry Collector configuration If you’re not ready to completely switch to a Grafana Agent Flow configuration, you can run Grafana Agent using your existing OpenTelemetry Collector configuration. The `--config.format=otelcol` flag tells Grafana Agent to convert your OpenTelemetry Collector configuration to a Grafana Agent Flow configuration and load it directly without saving the new configuration. This allows you to try Grafana Agent Flow without modifying your existing OpenTelemetry Collector configuration infrastructure. > In this task, you will use the [run](/docs/agent/v0.43/flow/get-started/run/) CLI command to run Grafana Agent Flow using an OpenTelemetry Collector configuration. [Run](/docs/agent/v0.43/flow/get-started/run/) Grafana Agent Flow and include the command line flag `--config.format=otelcol`. Your configuration file must be a valid OpenTelemetry Collector configuration file rather than a Grafana Agent Flow configuration file. ### Debugging 1. You can follow the convert CLI command [debugging](#debugging) instructions to generate a diagnostic report. 2. Refer to the Grafana Agent Flow [Debugging](/docs/agent/v0.43/flow/tasks/debug/) for more information about a running Grafana Agent Flow. 3. If your OpenTelemetry Collector configuration can’t be converted and loaded directly into Grafana Agent Flow, diagnostic information is sent to `stderr`. You can bypass any non-critical issues and start the Agent by including the `--config.bypass-conversion-errors` flag in addition to `--config.format=otelcol`. > Caution > > If you bypass the errors, the behavior of the converted configuration may not match the original Prometheus configuration. Do not use this flag in a production environment. ## Example This example demonstrates converting an OpenTelemetry Collector configuration file to a Grafana Agent Flow configuration file. The following OpenTelemetry Collector configuration file provides the input for the conversion. YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml receivers: otlp: protocols: grpc: http: exporters: otlp: endpoint: database:4317 processors: memory_limiter: limit_percentage: 90 check_interval: 1s service: pipelines: metrics: receivers: [otlp] processors: [memory_limiter] exporters: [otlp] logs: receivers: [otlp] processors: [memory_limiter] exporters: [otlp] traces: receivers: [otlp] processors: [memory_limiter] exporters: [otlp] ``` The convert command takes the YAML file as input and outputs a [River](/docs/agent/v0.43/flow/concepts/config-language/) file. static-binary flow-binary ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy static-binary ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```static-binary AGENT_MODE=flow grafana-agent convert --source-format=otelcol --output= ``` flow-binary ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```flow-binary grafana-agent-flow convert --source-format=otelcol --output= ``` Replace the following: - *``* : The full path to the OpenTelemetry Collector configuration. - *``* : The full path to output the Grafana Agent Flow configuration. The new Grafana Agent Flow configuration file looks like this: Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```alloy otelcol.receiver.otlp "default" { grpc { } http { } output { metrics = [otelcol.processor.memory_limiter.default.input] logs = [otelcol.processor.memory_limiter.default.input] traces = [otelcol.processor.memory_limiter.default.input] } } otelcol.processor.memory_limiter "default" { check_interval = "1s" limit_percentage = 90 output { metrics = [otelcol.exporter.otlp.default.input] logs = [otelcol.exporter.otlp.default.input] traces = [otelcol.exporter.otlp.default.input] } } otelcol.exporter.otlp "default" { client { endpoint = "database:4317" } } ``` ## Limitations Configuration conversion is done on a best-effort basis. Grafana Agent will issue warnings or errors where the conversion can’t be performed. After the configuration is converted, review the Grafana Agent Flow configuration file created and verify that it’s correct before starting to use it in a production environment. The following list is specific to the convert command and not Grafana Agent Flow: - Components are supported which directly embed upstream OpenTelemetry Collector features. You can get a general idea of which exist in Grafana Agent Flow for conversion by reviewing the `otelcol.*` components in the [Component Reference](/docs/agent/v0.43/flow/reference/components/). Any additional unsupported features are returned as errors during conversion. - Check if you are using any extra command line arguments with OpenTelemetry Collector that aren’t present in your configuration file. - Metamonitoring metrics exposed by Grafana Agent Flow usually match OpenTelemetry Collector metamonitoring metrics but will use a different name. Make sure that you use the new metric names, for example, in your alerts and dashboards queries. - The logs produced by Grafana Agent Flow differ from those produced by OpenTelemetry Collector. - Grafana Agent exposes the Grafana Agent Flow [UI](/docs/agent/v0.43/flow/tasks/debug/#grafana-agent-flow-ui).