|
| 1 | +--- |
| 2 | +canonical: https://grafana.com/docs/agent/latest/flow/tasks/migrate/from-otelcol/ |
| 3 | +description: Learn how to migrate from OpenTelemetry Collector to Grafana Agent Flow |
| 4 | +menuTitle: Migrate from OpenTelemetry Collector |
| 5 | +title: Migrate from OpenTelemetry Collector to Grafana Agent Flow |
| 6 | +weight: 310 |
| 7 | +--- |
| 8 | + |
| 9 | +# Migrate from OpenTelemetry Collector to {{% param "PRODUCT_NAME" %}} |
| 10 | + |
| 11 | +The built-in {{< param "PRODUCT_ROOT_NAME" >}} convert command can migrate your [OpenTelemetry Collector][] configuration to a {{< param "PRODUCT_NAME" >}} configuration. |
| 12 | + |
| 13 | +This topic describes how to: |
| 14 | + |
| 15 | +* Convert an OpenTelemetry Collector configuration to a {{< param "PRODUCT_NAME" >}} configuration. |
| 16 | +* Run an OpenTelemetry Collector configuration natively using {{< param "PRODUCT_NAME" >}}. |
| 17 | + |
| 18 | +## Components used in this topic |
| 19 | + |
| 20 | +* [otelcol.receiver.otlp][] |
| 21 | +* [otelcol.processor.memory_limiter][] |
| 22 | +* [otelcol.exporter.otlp][] |
| 23 | + |
| 24 | +## Before you begin |
| 25 | + |
| 26 | +* You must have an existing OpenTelemetry Collector configuration. |
| 27 | +* You must have a set of OpenTelemetry Collector applications ready to push telemetry data to {{< param "PRODUCT_NAME" >}}. |
| 28 | +* You must be familiar with the concept of [Components][] in {{< param "PRODUCT_NAME" >}}. |
| 29 | + |
| 30 | +## Convert an OpenTelemetry Collector configuration |
| 31 | + |
| 32 | +To fully migrate your configuration from [OpenTelemetry Collector] to {{< param "PRODUCT_NAME" >}}, you must convert your OpenTelemetry Collector configuration into a {{< param "PRODUCT_NAME" >}} configuration. |
| 33 | +This conversion will enable you to take full advantage of the many additional features available in {{< param "PRODUCT_NAME" >}}. |
| 34 | + |
| 35 | +> In this task, you will use the [convert][] CLI command to output a {{< param "PRODUCT_NAME" >}} |
| 36 | +> configuration from a OpenTelemetry Collector configuration. |
| 37 | +
|
| 38 | +1. Open a terminal window and run the following command. |
| 39 | + |
| 40 | + {{< code >}} |
| 41 | + |
| 42 | + ```static-binary |
| 43 | + AGENT_MODE=flow grafana-agent convert --source-format=otelcol --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH> |
| 44 | + ``` |
| 45 | + |
| 46 | + ```flow-binary |
| 47 | + grafana-agent-flow convert --source-format=otelcol --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH> |
| 48 | + ``` |
| 49 | + |
| 50 | + {{< /code >}} |
| 51 | + |
| 52 | + Replace the following: |
| 53 | + |
| 54 | + - _`<INPUT_CONFIG_PATH>`_: The full path to the OpenTelemetry Collector configuration. |
| 55 | + - _`<OUTPUT_CONFIG_PATH>`_: The full path to output the {{< param "PRODUCT_NAME" >}} configuration. |
| 56 | + |
| 57 | +1. [Run][] {{< param "PRODUCT_NAME" >}} using the new {{< param "PRODUCT_NAME" >}} configuration from _`<OUTPUT_CONFIG_PATH>`_: |
| 58 | + |
| 59 | +### Debugging |
| 60 | + |
| 61 | +1. If the `convert` command can't convert an OpenTelemetry Collector configuration, diagnostic information is sent to `stderr`.\ |
| 62 | + You can bypass any non-critical issues and output the {{< param "PRODUCT_NAME" >}} configuration using a best-effort conversion by including the `--bypass-errors` flag. |
| 63 | + |
| 64 | + {{< admonition type="caution" >}} |
| 65 | + If you bypass the errors, the behavior of the converted configuration may not match the original OpenTelemetry Collector configuration. |
| 66 | + Make sure you fully test the converted configuration before using it in a production environment. |
| 67 | + {{< /admonition >}} |
| 68 | + |
| 69 | + {{< code >}} |
| 70 | + |
| 71 | + ```static-binary |
| 72 | + AGENT_MODE=flow grafana-agent convert --source-format=otelcol --bypass-errors --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH> |
| 73 | + ``` |
| 74 | + |
| 75 | + ```flow-binary |
| 76 | + grafana-agent-flow convert --source-format=otelcol --bypass-errors --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH> |
| 77 | + ``` |
| 78 | + |
| 79 | + {{< /code >}} |
| 80 | + |
| 81 | + Replace the following: |
| 82 | + |
| 83 | + - _`<INPUT_CONFIG_PATH>`_: The full path to the OpenTelemetry Collector configuration. |
| 84 | + - _`<OUTPUT_CONFIG_PATH>`_: The full path to output the {{< param "PRODUCT_NAME" >}} configuration. |
| 85 | + |
| 86 | +1. You can also output a diagnostic report by including the `--report` flag. |
| 87 | + |
| 88 | + {{< code >}} |
| 89 | + |
| 90 | + ```static-binary |
| 91 | + AGENT_MODE=flow grafana-agent convert --source-format=otelcol --report=<OUTPUT_REPORT_PATH> --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH> |
| 92 | + ``` |
| 93 | + |
| 94 | + ```flow-binary |
| 95 | + grafana-agent-flow convert --source-format=otelcol --report=<OUTPUT_REPORT_PATH> --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH> |
| 96 | + ``` |
| 97 | + |
| 98 | + {{< /code >}} |
| 99 | + |
| 100 | + Replace the following: |
| 101 | + |
| 102 | + - _`<INPUT_CONFIG_PATH>`_: The full path to the OpenTelemetry Collector configuration. |
| 103 | + - _`<OUTPUT_CONFIG_PATH>`_: The full path to output the {{< param "PRODUCT_NAME" >}} configuration. |
| 104 | + - _`<OUTPUT_REPORT_PATH>`_: The output path for the report. |
| 105 | + |
| 106 | + Using the [example][] OpenTelemetry Collector configuration below, the diagnostic report provides the following information: |
| 107 | + |
| 108 | + ```plaintext |
| 109 | + (Info) Converted receiver/otlp into otelcol.receiver.otlp.default |
| 110 | + (Info) Converted processor/memory_limiter into otelcol.processor.memory_limiter.default |
| 111 | + (Info) Converted exporter/otlp into otelcol.exporter.otlp.default |
| 112 | +
|
| 113 | + A configuration file was generated successfully. |
| 114 | + ``` |
| 115 | +
|
| 116 | +## Run an OpenTelemetry Collector configuration |
| 117 | +
|
| 118 | +If you’re not ready to completely switch to a {{< param "PRODUCT_NAME" >}} configuration, you can run {{< param "PRODUCT_ROOT_NAME" >}} using your existing OpenTelemetry Collector configuration. |
| 119 | +The `--config.format=otelcol` flag tells {{< param "PRODUCT_ROOT_NAME" >}} to convert your OpenTelemetry Collector configuration to a {{< param "PRODUCT_NAME" >}} configuration and load it directly without saving the new configuration. |
| 120 | +This allows you to try {{< param "PRODUCT_NAME" >}} without modifying your existing OpenTelemetry Collector configuration infrastructure. |
| 121 | +
|
| 122 | +> In this task, you will use the [run][] CLI command to run {{< param "PRODUCT_NAME" >}} |
| 123 | +> using an OpenTelemetry Collector configuration. |
| 124 | +
|
| 125 | +[Run][] {{< param "PRODUCT_NAME" >}} and include the command line flag `--config.format=otelcol`. |
| 126 | +Your configuration file must be a valid OpenTelemetry Collector configuration file rather than a {{< param "PRODUCT_NAME" >}} configuration file. |
| 127 | +
|
| 128 | +### Debugging |
| 129 | +
|
| 130 | +1. You can follow the convert CLI command [debugging][] instructions to generate a diagnostic report. |
| 131 | +
|
| 132 | +1. Refer to the {{< param "PRODUCT_NAME" >}} [Debugging][DebuggingUI] for more information about a running {{< param "PRODUCT_NAME" >}}. |
| 133 | +
|
| 134 | +1. If your OpenTelemetry Collector configuration can't be converted and loaded directly into {{< param "PRODUCT_NAME" >}}, diagnostic information is sent to `stderr`. |
| 135 | + 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`. |
| 136 | +
|
| 137 | + {{< admonition type="caution" >}} |
| 138 | + If you bypass the errors, the behavior of the converted configuration may not match the original Prometheus configuration. |
| 139 | + Do not use this flag in a production environment. |
| 140 | + {{< /admonition >}} |
| 141 | +
|
| 142 | +## Example |
| 143 | +
|
| 144 | +This example demonstrates converting an OpenTelemetry Collector configuration file to a {{< param "PRODUCT_NAME" >}} configuration file. |
| 145 | +
|
| 146 | +The following OpenTelemetry Collector configuration file provides the input for the conversion. |
| 147 | +
|
| 148 | +```yaml |
| 149 | +receivers: |
| 150 | + otlp: |
| 151 | + protocols: |
| 152 | + grpc: |
| 153 | + http: |
| 154 | +
|
| 155 | +exporters: |
| 156 | + otlp: |
| 157 | + endpoint: database:4317 |
| 158 | +
|
| 159 | +processors: |
| 160 | + memory_limiter: |
| 161 | + limit_percentage: 90 |
| 162 | + check_interval: 1s |
| 163 | +
|
| 164 | +
|
| 165 | +service: |
| 166 | + pipelines: |
| 167 | + metrics: |
| 168 | + receivers: [otlp] |
| 169 | + processors: [memory_limiter] |
| 170 | + exporters: [otlp] |
| 171 | + logs: |
| 172 | + receivers: [otlp] |
| 173 | + processors: [memory_limiter] |
| 174 | + exporters: [otlp] |
| 175 | + traces: |
| 176 | + receivers: [otlp] |
| 177 | + processors: [memory_limiter] |
| 178 | + exporters: [otlp] |
| 179 | +``` |
| 180 | + |
| 181 | +The convert command takes the YAML file as input and outputs a [River][] file. |
| 182 | + |
| 183 | +{{< code >}} |
| 184 | + |
| 185 | +```static-binary |
| 186 | +AGENT_MODE=flow grafana-agent convert --source-format=otelcol --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH> |
| 187 | +``` |
| 188 | + |
| 189 | +```flow-binary |
| 190 | +grafana-agent-flow convert --source-format=otelcol --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH> |
| 191 | +``` |
| 192 | + |
| 193 | +{{< /code >}} |
| 194 | + |
| 195 | +Replace the following: |
| 196 | + |
| 197 | +- _`<INPUT_CONFIG_PATH>`_: The full path to the OpenTelemetry Collector configuration. |
| 198 | +- _`<OUTPUT_CONFIG_PATH>`_: The full path to output the {{< param "PRODUCT_NAME" >}} configuration. |
| 199 | + |
| 200 | +The new {{< param "PRODUCT_NAME" >}} configuration file looks like this: |
| 201 | + |
| 202 | +```river |
| 203 | +otelcol.receiver.otlp "default" { |
| 204 | + grpc { } |
| 205 | +
|
| 206 | + http { } |
| 207 | +
|
| 208 | + output { |
| 209 | + metrics = [otelcol.processor.memory_limiter.default.input] |
| 210 | + logs = [otelcol.processor.memory_limiter.default.input] |
| 211 | + traces = [otelcol.processor.memory_limiter.default.input] |
| 212 | + } |
| 213 | +} |
| 214 | +
|
| 215 | +otelcol.processor.memory_limiter "default" { |
| 216 | + check_interval = "1s" |
| 217 | + limit_percentage = 90 |
| 218 | +
|
| 219 | + output { |
| 220 | + metrics = [otelcol.exporter.otlp.default.input] |
| 221 | + logs = [otelcol.exporter.otlp.default.input] |
| 222 | + traces = [otelcol.exporter.otlp.default.input] |
| 223 | + } |
| 224 | +} |
| 225 | +
|
| 226 | +otelcol.exporter.otlp "default" { |
| 227 | + client { |
| 228 | + endpoint = "database:4317" |
| 229 | + } |
| 230 | +} |
| 231 | +``` |
| 232 | + |
| 233 | +## Limitations |
| 234 | + |
| 235 | +Configuration conversion is done on a best-effort basis. {{< param "PRODUCT_ROOT_NAME" >}} will issue warnings or errors where the conversion can't be performed. |
| 236 | + |
| 237 | +After the configuration is converted, review the {{< param "PRODUCT_NAME" >}} configuration file created and verify that it's correct before starting to use it in a production environment. |
| 238 | + |
| 239 | +The following list is specific to the convert command and not {{< param "PRODUCT_NAME" >}}: |
| 240 | + |
| 241 | +* Components are supported which directly embed upstream OpenTelemetry Collector features. You can get a general idea of which exist in |
| 242 | + {{< param "PRODUCT_NAME" >}} for conversion by reviewing the `otelcol.*` components in the [Component Reference][]. |
| 243 | + Any additional unsupported features are returned as errors during conversion. |
| 244 | +* Check if you are using any extra command line arguments with OpenTelemetry Collector that aren't present in your configuration file. |
| 245 | +* Metamonitoring metrics exposed by {{< param "PRODUCT_NAME" >}} usually match OpenTelemetry Collector metamonitoring metrics but will use a different name. |
| 246 | + Make sure that you use the new metric names, for example, in your alerts and dashboards queries. |
| 247 | +* The logs produced by {{< param "PRODUCT_NAME" >}} differ from those produced by OpenTelemetry Collector. |
| 248 | +* {{< param "PRODUCT_ROOT_NAME" >}} exposes the {{< param "PRODUCT_NAME" >}} [UI][]. |
| 249 | + |
| 250 | +[OpenTelemetry Collector]: https://opentelemetry.io/docs/collector/configuration/ |
| 251 | +[debugging]: #debugging |
| 252 | +[example]: #example |
| 253 | + |
| 254 | +{{% docs/reference %}} |
| 255 | +[otelcol.receiver.otlp ]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/otelcol.receiver.otlp.md" |
| 256 | +[otelcol.processor.memory_limiter ]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/otelcol.processor.memory_limiter.md" |
| 257 | +[otelcol.exporter.otlp ]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/otelcol.exporter.otlp.md" |
| 258 | +[Components ]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/components.md" |
| 259 | +[Components]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/concepts/components.md" |
| 260 | +[Component Reference ]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/ _index.md" |
| 261 | +[Component Reference]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/reference/components/_index.md" |
| 262 | +[convert ]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/cli/convert.md" |
| 263 | +[convert]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/reference/cli/convert.md" |
| 264 | +[run ]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/cli/run.md" |
| 265 | +[run]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/reference/cli/run.md" |
| 266 | +[Run ]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/get-started/run/" |
| 267 | +[Run]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/get-started/run/" |
| 268 | +[DebuggingUI ]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/tasks/debug.md" |
| 269 | +[DebuggingUI]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/tasks/debug.md" |
| 270 | +[River ]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/config-language/ _index.md" |
| 271 | +[River]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/concepts/config-language/_index.md" |
| 272 | +[UI ]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/tasks/debug#grafana-agent-flow-ui" |
| 273 | +[UI]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/send-data/agent/flow/tasks/debug#grafana-agent-flow-ui" |
| 274 | +{{% /docs/reference %}} |
0 commit comments