---
title: "Migrate from OpenTelemetry Collector to Grafana Alloy | Grafana Alloy documentation"
description: "Learn how to migrate from OpenTelemetry Collector to Grafana Alloy"
---

# Migrate from OpenTelemetry Collector to Alloy

The built-in Grafana Alloy convert command can migrate your [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/configuration/) configuration to a Alloy configuration.

This topic describes how to:

- Convert an OpenTelemetry Collector configuration to a Alloy configuration.
- Run an OpenTelemetry Collector configuration natively using Alloy.

## Components used in this topic

- [`otelcol.receiver.otlp`](../../../reference/components/otelcol/otelcol.receiver.otlp/)
- [`otelcol.processor.memory_limiter`](../../../reference/components/otelcol/otelcol.processor.memory_limiter/)
- [`otelcol.exporter.otlp`](../../../reference/components/otelcol/otelcol.exporter.otlp/)

## Before you begin

- You must have an OpenTelemetry Collector configuration.
- You must have a set of OpenTelemetry Collector applications ready to push telemetry data to Alloy.
- You must be familiar with the concept of [Components](../../../get-started/components/) in Alloy.

## Convert an OpenTelemetry Collector configuration

To fully migrate your configuration from [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/configuration/) to Alloy, you must convert your OpenTelemetry Collector configuration into a Alloy configuration. This conversion allows you to take full advantage of the many additional features available in Alloy.

In this task, you use the [convert](../../../reference/cli/convert/) CLI command to output a Alloy configuration from a OpenTelemetry Collector configuration.

1. Open a terminal window and run the following command.
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   alloy convert --source-format=otelcol --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
   ```
   
   Replace the following:
   
   - *`<INPUT_CONFIG_PATH>`* : The full path to the OpenTelemetry Collector configuration.
   - *`<OUTPUT_CONFIG_PATH>`* : The full path to output the Alloy configuration.
2. [Run](../../../reference/cli/run/) Alloy using the new Alloy configuration from *`<OUTPUT_CONFIG_PATH>`* :

### 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 Alloy 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.
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   alloy convert --source-format=otelcol --bypass-errors --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
   ```
   
   Replace the following:
   
   - *`<INPUT_CONFIG_PATH>`* : The full path to the OpenTelemetry Collector configuration.
   - *`<OUTPUT_CONFIG_PATH>`* : The full path to output the Alloy configuration.
2. You can also output a diagnostic report by including the `--report` flag.
   
   shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy
   
   ```shell
   alloy convert --source-format=otelcol --report=<OUTPUT_REPORT_PATH> --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
   ```
   
   Replace the following:
   
   - *`<INPUT_CONFIG_PATH>`* : The full path to the OpenTelemetry Collector configuration.
   - *`<OUTPUT_CONFIG_PATH>`* : The full path to output the Alloy configuration.
   - *`<OUTPUT_REPORT_PATH>`* : 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 Alloy configuration, you can run Grafana Alloy using your OpenTelemetry Collector configuration. The `--config.format=otelcol` flag tells Grafana Alloy to convert your OpenTelemetry Collector configuration to a Alloy configuration and load it directly without saving the new configuration. This allows you to try Alloy without modifying your OpenTelemetry Collector configuration infrastructure.

In this task, you use the [run](../../../reference/cli/run/) CLI command to run Alloy using an OpenTelemetry Collector configuration.

[Run](../../../reference/cli/run/) Alloy and include the command line flag `--config.format=otelcol`. Your configuration file must be a valid OpenTelemetry Collector configuration file rather than a Alloy configuration file.

### Debug

1. You can follow the convert CLI command [debugging](#debugging) instructions to generate a diagnostic report.
2. Refer to the Alloy [Debugging](../../../troubleshoot/debug/) for more information about a running Alloy.
3. If your OpenTelemetry Collector configuration can’t be converted and loaded directly into Alloy, diagnostic information is sent to `stderr`. You can bypass any non-critical issues and start Alloy 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. Don’t use this flag in a production environment.

## Example

This example demonstrates converting an OpenTelemetry Collector configuration file to a Alloy 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 an Alloy configuration file.

shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```shell
alloy convert --source-format=otelcol --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
```

Replace the following:

- *`<INPUT_CONFIG_PATH>`* : The full path to the OpenTelemetry Collector configuration.
- *`<OUTPUT_CONFIG_PATH>`* : The full path to output the Alloy configuration.

The new Alloy 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 Alloy issues warnings or errors where the conversion can’t be performed.

After the configuration is converted, review the Alloy 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 Alloy:

- Components are supported which directly embed upstream OpenTelemetry Collector features. You can get a general idea of which exist in Alloy for conversion by reviewing the `otelcol.*` components in the [Component Reference](../../../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.
- Meta-monitoring metrics exposed by Alloy usually match OpenTelemetry Collector meta-monitoring metrics but uses a different name. Make sure that you use the new metric names, for example, in your alerts and dashboards queries.
- The logs produced by Alloy differ from those produced by OpenTelemetry Collector.
- The Alloy [UI](../../../troubleshoot/debug/#alloy-ui) uses Alloy naming conventions for components and their configuration blocks and arguments.
- Not all arguments in the `service/telemetry` section are supported.
- Environment variables with a scheme other than `env` aren’t supported. Environment variables with no scheme default to `env`.