Migrate to Grafana Alloy on Grafana Labs

Migrate Grafana Agent Static to Grafana Alloy

Mon, 30 Mar 2026 15:47:22 +0000

Migrate from Grafana Agent Static to Grafana Alloy

The built-in Alloy convert command can migrate your Grafana Agent Static configuration to an Alloy configuration.

This topic describes how to:

Convert a Grafana Agent Static configuration to an Alloy configuration.
Run a Grafana Agent Static configuration natively using Alloy.

Components used in this topic

Before you begin

You must have a Grafana Agent Static configuration.
You must be familiar with the Components concept in Alloy.

Convert a Grafana Agent Static configuration

To fully migrate Grafana Agent Static to Alloy, you must convert your Grafana Agent Static configuration into an 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 CLI command to output an Alloy configuration from a Grafana Agent Static configuration.

Open a terminal window and run the following command.
shell
```
alloy convert --source-format=static --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
```
Replace the following:
- <INPUT_CONFIG_PATH>: The full path to the configuration file for Grafana Agent Static.
- <OUTPUT_CONFIG_PATH>: The full path to output the Alloy configuration.
Stop Grafana Agent static.
Run Alloy using the new Alloy configuration from <OUTPUT_CONFIG_PATH>:

Debugging

If the convert command can’t convert a Grafana Agent Static configuration, diagnostic information is sent to stderr. You can use the --bypass-errors flag to bypass any non-critical issues and output the Alloy configuration using a best-effort conversion.

Caution
If you bypass the errors, the behavior of the converted configuration may not match the original Grafana Agent Static configuration. Make sure you fully test the converted configuration before using it in a production environment.
shell
```
alloy convert --source-format=static --bypass-errors --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
```
Replace the following:
- <INPUT_CONFIG_PATH>: The full path to the configuration file for Grafana Agent Static.
- <OUTPUT_CONFIG_PATH>: The full path to output the Alloy configuration.
You can use the --report flag to output a diagnostic report.
shell
```
alloy convert --source-format=static --report=<OUTPUT_REPORT_PATH> --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
```
Replace the following:
- <INPUT_CONFIG_PATH>: The full path to the configuration file for Grafana Agent Static.
- <OUTPUT_CONFIG_PATH>: The full path to output the Alloy configuration.
- <OUTPUT_REPORT_PATH>: The output path for the report.
Using the example Grafana Agent Static configuration below, the diagnostic report provides the following information.
plaintext
```
(Warning) Please review your agent command line flags and ensure they are set in your Alloy configuration file where necessary.
```

Run a Grafana Agent Static mode configuration

If you’re not ready to completely switch to an Alloy configuration, you can run Alloy using your Grafana Agent Static configuration. The --config.format=static flag tells Alloy to convert your Grafana Agent Static configuration to Alloy and load it directly without saving the configuration. This allows you to try Alloy without modifying your Grafana Agent Static configuration infrastructure.

In this task, you use the run CLI command to run Alloy using a Grafana Agent Static configuration.

Run Alloy and include the command line flag --config.format=static. Your configuration file must be a valid Grafana Agent Static configuration file.

Debug

Follow the convert CLI command debugging instructions to generate a diagnostic report.
Refer to the Alloy debugging UI for more information about running Alloy.
If your Grafana Agent Static configuration can’t be converted and loaded directly into Alloy, diagnostic information is sent to stderr. You can use the --config.bypass-conversion-errors flag with --config.format=static to bypass any non-critical issues and start Alloy.

Caution
If you bypass the errors, the behavior of the converted configuration may not match the original Grafana Agent Static configuration. Don’t use this flag in a production environment.

Example

This example demonstrates converting a Grafana Agent Static configuration file to an Alloy configuration file.

The following Grafana Agent Static configuration file provides the input for the conversion.

server:
  log_level: info

metrics:
  global:
    scrape_interval: 15s
    remote_write:
      - url: https://prometheus-us-central1.grafana.net/api/prom/push
        basic_auth:
          username: USERNAME
          password: PASSWORD
  configs:
    - name: test
      host_filter: false
      scrape_configs:
        - job_name: local-agent
          static_configs:
            - targets: ['127.0.0.1:12345']
              labels:
                cluster: 'localhost'

logs:
  global:
    file_watch_config:
      min_poll_frequency: 1s
      max_poll_frequency: 5s
  positions_directory: /var/lib/agent/data-agent
  configs:
    - name: varlogs
      scrape_configs:
        - job_name: varlogs
          static_configs:
            - targets:
              - localhost
              labels:
                job: varlogs
                host: mylocalhost
                __path__: /var/log/*.log
          pipeline_stages:
            - match:
                selector: '{filename="/var/log/*.log"}'
                stages:
                - drop:
                    expression: '^[^0-9]{4}'
                - regex:
                    expression: '^(?P<timestamp>\d{4}/\d{2}/\d{2} \d{2}:\d{2}:\d{2}) \[(?P<level>[[:alpha:]]+)\] (?:\d+)\#(?:\d+): \*(?:\d+) (?P<message>.+)$'
                - pack:
                    labels:
                      - level
      clients:
        - url: https://USER_ID:API_KEY@logs-prod3.grafana.net/loki/api/v1/push

traces:
  configs:
    - name: tempo
      receivers:
        otlp:
          protocols:
            grpc:
            http:
      batch:
        send_batch_size: 10000
        timeout: 20s
      remote_write:
        - endpoint: tempo-us-central1.grafana.net:443
          basic_auth:
            username: USERNAME
            password: PASSWORD

The convert command takes the YAML file as input and outputs a Alloy configuration file.

alloy convert --source-format=static --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>

Replace the following:

<INPUT_CONFIG_PATH>: The full path to the configuration file for Grafana Agent Static.
<OUTPUT_CONFIG_PATH>: The full path to output the Alloy configuration.

The Alloy configuration file looks like this:

prometheus.scrape "metrics_test_local_agent" {
    targets = [{
        __address__ = "127.0.0.1:12345",
        cluster     = "localhost",
    }]
    forward_to      = [prometheus.remote_write.metrics_test.receiver]
    job_name        = "local-agent"
    scrape_interval = "15s"
}

prometheus.remote_write "metrics_test" {
    endpoint {
        name = "test-4dec64"
        url  = "https://prometheus-us-central1.grafana.net/api/prom/push"

        basic_auth {
            username = "<USERNAME>"
            password = "<PASSWORD>"
        }

        queue_config { }

        metadata_config { }
    }
}

local.file_match "logs_varlogs_varlogs" {
    path_targets = [{
        __address__ = "localhost",
        __path__    = "/var/log/*.log",
        host        = "mylocalhost",
        job         = "varlogs",
    }]
}

loki.process "logs_varlogs_varlogs" {
    forward_to = [loki.write.logs_varlogs.receiver]

    stage.match {
        selector = "{filename=\"/var/log/*.log\"}"

        stage.drop {
            expression = "^[^0-9]{4}"
        }

        stage.regex {
            expression = "^(?P<timestamp>\\d{4}/\\d{2}/\\d{2} \\d{2}:\\d{2}:\\d{2}) \\[(?P<level>[[:alpha:]]+)\\] (?:\\d+)\\#(?:\\d+): \\*(?:\\d+) (?P<message>.+)$"
        }

        stage.pack {
            labels           = ["level"]
            ingest_timestamp = false
        }
    }
}

loki.source.file "logs_varlogs_varlogs" {
    targets    = local.file_match.logs_varlogs_varlogs.targets
    forward_to = [loki.process.logs_varlogs_varlogs.receiver]

    file_watch {
        min_poll_frequency = "1s"
        max_poll_frequency = "5s"
    }
    legacy_positions_file = "/var/lib/agent/data-agent/varlogs.yml"
}

loki.write "logs_varlogs" {
    endpoint {
        url = "https://USER_ID:API_KEY@logs-prod3.grafana.net/loki/api/v1/push"
    }
    external_labels = {}
}

otelcol.receiver.otlp "default" {
    grpc {
        include_metadata = true
    }

    http {
        include_metadata = true
    }

    output {
        metrics = []
        logs    = []
        traces  = [otelcol.processor.batch.default.input]
    }
}

otelcol.processor.batch "default" {
    timeout         = "20s"
    send_batch_size = 10000

    output {
        metrics = []
        logs    = []
        traces  = [otelcol.exporter.otlp.default_0.input]
    }
}

otelcol.exporter.otlp "default_0" {
    retry_on_failure {
        max_elapsed_time = "1m0s"
    }

    client {
        endpoint = "tempo-us-central1.grafana.net:443"
        headers  = {
            authorization = "Basic VVNFUk5BTUU6UEFTU1dPUkQ=",
        }
    }
}

Integrations Next

You can convert integrations next configurations by adding the extra-args flag for convert or config.extra-args for run.

alloy convert --source-format=static --extra-args="-enable-features=integrations-next" --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>

Replace the following:

<INPUT_CONFIG_PATH>: The full path to the configuration file for Grafana Agent Static.
<OUTPUT_CONFIG_PATH>: The full path to output the Alloy configuration.

Environment variables

You can use the -config.expand-env command line flag to interpret environment variables in your Grafana Agent Static configuration. You can pass these flags to convert with --extra-args="-config.expand-env" or to run with --config.extra-args="-config.expand-env".

It’s possible to combine integrations-next with expand-env. For convert, you can use --extra-args="-enable-features=integrations-next -config.expand-env"

Limitations

Configuration conversion is done on a best-effort basis. Alloy issues warnings or errors if the conversion can’t be done.

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

The Agent Management configuration options can’t be automatically converted to Alloy. Any additional unsupported features are returned as errors during conversion.
There is no gRPC server to configure for Alloy. Any non-default configuration shows as unsupported during the conversion.
Check if you are using any extra command line arguments with Grafana Agent Static that aren’t present in your configuration file. For example, -server.http.address.
Check if you are using any environment variables in your Grafana Agent Static configuration. These are evaluated during conversion, and you may want to replace them with the Alloy Standard library sys.env function after conversion.
Review additional Prometheus Limitations for limitations specific to your Metrics configuration.
Review additional Promtail Limitations for limitations specific to your Logs configuration.
The logs produced by Alloy differ from those produced by Grafana Agent Static.
Alloy exposes the Alloy UI.

Migrate from Grafana Agent Operator to Grafana Alloy

Mon, 30 Mar 2026 15:47:22 +0000

Migrate from Grafana Agent Operator to Grafana Alloy

You can migrate from Grafana Agent Operator to Alloy.

The Monitor types (PodMonitor, ServiceMonitor, Probe, ScrapeConfig, and PodLogs) are all supported natively by Alloy.
The parts of Grafana Agent Operator that deploy Grafana Agent, GrafanaAgent, MetricsInstance, and LogsInstance CRDs, are deprecated.

Deploy Alloy with Helm

Create a values.yaml file, which contains options for deploying Alloy. You can start with the default values and customize as you see fit, or start with this snippet, which should be a good starting point for what Grafana Agent Operator does.
YAML
```
alloy:
  configMap:
    create: true
  clustering:
    enabled: true
controller:
  type: 'statefulset'
  replicas: 2
crds:
  create: false
```
This configuration deploys Alloy as a StatefulSet using the built-in clustering functionality to allow distributing scrapes across all Alloy pods.

This is one of many deployment possible modes. For example, you may want to use a DaemonSet to collect host-level logs or metrics. See the Alloy deployment guide for more details about different topologies.
Create an Alloy configuration file, config.alloy.

In the next step, you add to this configuration as you convert MetricsInstances. You can add any additional configuration to this file as you need.

Install the Grafana Helm repository:

helm repo add grafana https://grafana.github.io/helm-charts
helm repo update

Create a Helm release. You can name the release anything you like. The following command installs a release called alloy-metrics in the monitoring namespace.
shell
```
helm upgrade alloy-metrics grafana/alloy -i -n monitoring -f values.yaml --set-file alloy.configMap.content=config.alloy
```
This command uses the --set-file flag to pass the configuration file as a Helm value so that you can continue to edit it as a regular Alloy configuration file.

Convert `MetricsInstance` to Alloy components

A MetricsInstance resource primarily defines:

The remote endpoints Grafana Agent should send metrics to.
The PodMonitor, ServiceMonitor, ScrapeConfig, and Probe resources this Alloy should discover.

You can use these functions in Alloy with the prometheus.remote_write, prometheus.operator.podmonitors, prometheus.operator.servicemonitors, and prometheus.operator.probes components respectively.

The following Alloy syntax sample is equivalent to the MetricsInstance from the operator guide.


// read the credentials secret for remote_write authorization
remote.kubernetes.secret "credentials" {
  namespace = "monitoring"
  name = "primary-credentials-metrics"
}

prometheus.remote_write "primary" {
    endpoint {
        url = "https://<PROMETHEUS_URL>/api/v1/push"
        basic_auth {
            username = convert.nonsensitive(remote.kubernetes.secret.credentials.data["username"])
            password = remote.kubernetes.secret.credentials.data["password"]
        }
    }
}

prometheus.operator.podmonitors "primary" {
    forward_to = [prometheus.remote_write.primary.receiver]
    // leave out selector to find all podmonitors in the entire cluster
    selector {
        match_labels = {instance = "primary"}
    }
}

prometheus.operator.servicemonitors "primary" {
    forward_to = [prometheus.remote_write.primary.receiver]
    // leave out selector to find all servicemonitors in the entire cluster
    selector {
        match_labels = {instance = "primary"}
    }
}

Replace the following:

<PROMETHEUS_URL>: The endpoint you want to send metrics to.

This configuration discovers all PodMonitor, ServiceMonitor, ScrapeConfig, and Probe resources in your cluster that match the label selector instance=primary. It then scrapes metrics from the targets and forward them to your remote write endpoint.

You may need to customize this configuration further if you use additional features in your MetricsInstance resources. Refer to the documentation for the relevant components for additional information:

Collect logs

The current recommendation is to create an additional DaemonSet deployment of Alloy to scrape logs.

Alloy has components that can scrape Pod logs directly from the Kubernetes API without needing a DaemonSet deployment. These are still considered experimental, but if you would like to try them, see the documentation for loki.source.kubernetes and loki.source.podlogs.

These values are close to what Grafana Agent Operator deploys for logs:

alloy:
  configMap:
    create: true
  clustering:
    enabled: false
  controller:
    type: 'daemonset'
  mounts:
    # -- Mount /var/log from the host into the container for log collection.
    varlog: true

This command installs a release named alloy-logs in the monitoring namespace:

helm upgrade alloy-logs grafana/alloy -i -n monitoring -f values-logs.yaml --set-file alloy.configMap.content=config-logs.alloy

This simple configuration scrapes logs for every Pod on each node:

// read the credentials secret for remote_write authorization
remote.kubernetes.secret "credentials" {
  namespace = "monitoring"
  name      = "primary-credentials-logs"
}

discovery.kubernetes "pods" {
  role = "pod"
  // limit to pods on this node to reduce the amount you need to filter
  selectors {
    role  = "pod"
    field = "spec.nodeName=" + sys.env("<HOSTNAME>")
  }
}

discovery.relabel "pod_logs" {
  targets = discovery.kubernetes.pods.targets
  rule {
    source_labels = ["__meta_kubernetes_namespace"]
    target_label  = "namespace"
  }
  rule {
    source_labels = ["__meta_kubernetes_pod_name"]
    target_label  = "pod"
  }
  rule {
    source_labels = ["__meta_kubernetes_pod_container_name"]
    target_label  = "container"
  }
  rule {
    source_labels = ["__meta_kubernetes_namespace", "__meta_kubernetes_pod_name"]
    separator     = "/"
    target_label  = "job"
  }
  rule {
    source_labels = ["__meta_kubernetes_pod_uid", "__meta_kubernetes_pod_container_name"]
    separator     = "/"
    action        = "replace"
    replacement   = "/var/log/pods/*$1/*.log"
    target_label  = "__path__"
  }
  rule {
    action = "replace"
    source_labels = ["__meta_kubernetes_pod_container_id"]
    regex = "^(\\w+):\\/\\/.+$"
    replacement = "$1"
    target_label = "tmp_container_runtime"
  }
}

local.file_match "pod_logs" {
  path_targets = discovery.relabel.pod_logs.output
}

loki.source.file "pod_logs" {
  targets    = local.file_match.pod_logs.targets
  forward_to = [loki.process.pod_logs.receiver]
}

// basic processing to parse the container format. You can add additional processing stages
// to match your application logs.
loki.process "pod_logs" {
  stage.match {
    selector = "{tmp_container_runtime=\"containerd\"}"
    // the cri processing stage extracts the following k/v pairs: log, stream, time, flags
    stage.cri {}
    // Set the extract flags and stream values as labels
    stage.labels {
      values = {
        flags   = "",
        stream  = "",
      }
    }
  }

  // if the label tmp_container_runtime from above is docker parse using docker
  stage.match {
    selector = "{tmp_container_runtime=\"docker\"}"
    // the docker processing stage extracts the following k/v pairs: log, stream, time
    stage.docker {}

    // Set the extract stream value as a label
    stage.labels {
      values = {
        stream  = "",
      }
    }
  }

  // drop the temporary container runtime label as it is no longer needed
  stage.label_drop {
    values = ["tmp_container_runtime"]
  }

  forward_to = [loki.write.loki.receiver]
}

loki.write "loki" {
  endpoint {
    url = "https://<LOKI_URL>/loki/api/v1/push"
    basic_auth {
      username = convert.nonsensitive(remote.kubernetes.secret.credentials.data["username"])
      password = remote.kubernetes.secret.credentials.data["password"]
    }
}
}

Replace the following:

<LOKI_URL>: The endpoint of your Loki instance.

The logging subsystem is very powerful and has many options for processing logs. For further details, see the component documentation.

Integrations

The Integration CRD isn’t supported with Alloy. However, all Grafana Agent Static mode integrations have an equivalent component in the prometheus.exporter namespace. The reference documentation should help convert those integrations to their Alloy equivalent.

Migrate Grafana Agent Flow to Grafana Alloy

Mon, 30 Mar 2026 15:47:22 +0000

Migrate from Grafana Agent Flow to Grafana Alloy

This topic describes how to perform a live migration from Grafana Agent Flow to Grafana Alloy with minimal downtime.

Note
This procedure is only required for live migrations from a Grafana Agent Flow install to Alloy.

If you want a fresh start with Alloy, you can uninstall Grafana Agent Flow and install Alloy.

Before you begin

You must have a Grafana Agent Flow configuration to migrate.
You must be running Grafana Agent Flow version v0.40 or later.
If you use auto-scaling make sure you disable auto-scaling for your Grafana Agent Flow deployment to prevent it from scaling during the migration.

Differences between Grafana Agent Flow and Alloy

By default, you can only use functionality marked Generally available.

You can enable functionality in Experimental and Public preview by setting the --stability.level flag in run.

The default value of --storage.path has changed from data-agent/ to data-alloy/.
The default value of --server.http.memory-addr has changed from agent.internal:12345 to alloy.internal:12345.
Debug metrics reported by Alloy are prefixed with alloy_ instead of agent_.
The “classic modules”, module.file, module.git, module.http, and module.string have been removed in favor of import configuration blocks.
The prometheus.exporter.vsphere component has been replaced by the otelcol.receiver.vcenter component.

Steps

Prepare your Grafana Agent Flow configuration

Alloy uses the same configuration format as Grafana Agent Flow, but some functionality has been removed.

Before migrating, modify your Grafana Agent Flow configuration to remove or replace any unsupported components:

The “classic modules” in Grafana Agent Flow have been removed in favor of the modules introduced in v0.40:
- module.file is replaced by the import.file configuration block.
- module.git is replaced by the import.git configuration block.
- module.http is replaced by the import.http configuration block.
- module.string is replaced by the import.string configuration block.
prometheus.exporter.vsphere is replaced by the otelcol.receiver.vcenter component.

Deploy Alloy with a default configuration

Follow the installation instructions for Alloy, using the default configuration file. The configuration file is customized in the following steps.

When deploying Alloy, be aware of the following settings:

Alloy should be deployed with topology that’s the same as Grafana Agent Flow. The CPU, and storage limits should match.
Custom command-line flags configured in Grafana Agent Flow should be reflected in your Alloy installation.
Alloy may need to be deployed with the --stability.level flag in run to enable non-stable components:
- Set --stability.level to experimental if you are using the following component:
  - otelcol.receiver.vcenter
- Otherwise, --stability.level may be omitted or set to the default value, generally-available.
When installing on Kubernetes, update your values.yaml file to rename the agent key to alloy.
If you are deploying Alloy as a cluster:
- Set the number of instances to match the number of instances in your Grafana Agent Flow cluster.
- Don’t enable auto-scaling until the migration is complete.

Migrate Grafana Agent Flow data to Alloy

Migrate your Grafana Agent Flow data to Alloy by copying the contents of the Grafana Agent Flow data directory to the Alloy data directory.

Linux installations: copy the contents of /var/lib/grafana-agent-flow to /var/lib/alloy/data.
macOS installations: copy the contents of $(brew --prefix)/etc/grafana-agent-flow/data to $(brew --prefix)/etc/alloy/data.
Windows installations: copy the contents of %ProgramData%\Grafana Agent Flow\data to %ProgramData%\GrafanaLabs\Alloy\data.
Docker: copy the contents of mounted volumes to a new directory, and then mount the directory when running Alloy.
Kubernetes: use kubectl cp to copy the contents of the data directory on Flow pods to the data directory on Alloy pods.
- The data directory is determined by the agent.storagePath (default /tmp/agent) and alloy.storagePath (default /tmp/alloy) fields in values.yaml.

Migrate pipelines that receive data over the network

Telemetry pipelines which receive data over the network (for example, pipelines using otelcol.receiver.otlp or prometheus.receive_http) should be configured in Alloy first:

Configure Alloy with all pipelines where telemetry data is received over the network.
Reconfigure applications to send telemetry data to Alloy instead of Grafana Agent Flow.

Migrate the remaining pipelines

Migrate remaining pipelines from Grafana Agent Flow to Alloy:

Disable remaining pipelines in Grafana Agent Flow to prevent Flow and Alloy from processing the same data.
Configure Alloy with the remaining pipelines.

Note
This process results in minimal downtime as remaining pipelines are moved from Grafana Agent Flow to Alloy.

To completely eliminate downtime, configure remaining pipelines in Alloy before disabling them in Grafana Agent Flow. This alternative approach results in some duplicate data being sent to backends during the migration period.

Uninstall Grafana Agent Flow

After you have completed the migration, you can uninstall Grafana Agent Flow.

Cleanup temporary changes

You can enable auto-scaling in your Alloy deployment if you disabled it during the migration process.

Migrate from OpenTelemetry Collector to Grafana Alloy

Mon, 30 Mar 2026 15:47:22 +0000

Migrate from OpenTelemetry Collector to Alloy

The built-in Grafana Alloy convert command can migrate your OpenTelemetry Collector 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

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 in Alloy.

Convert an OpenTelemetry Collector configuration

To fully migrate your configuration from OpenTelemetry Collector 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 CLI command to output a Alloy configuration from a OpenTelemetry Collector configuration.

Open a terminal window and run the following command.
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.
Run Alloy using the new Alloy configuration from <OUTPUT_CONFIG_PATH>:

Debugging

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
```
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.
You can also output a diagnostic report by including the --report flag.
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 OpenTelemetry Collector configuration below, the diagnostic report provides the following information:
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 CLI command to run Alloy using an OpenTelemetry Collector configuration.

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

You can follow the convert CLI command debugging instructions to generate a diagnostic report.
Refer to the Alloy Debugging for more information about a running Alloy.
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.

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.

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:

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. 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 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.

Migrate from Prometheus to Grafana Alloy

Mon, 30 Mar 2026 15:47:22 +0000

Migrate from Prometheus to Grafana Alloy

The built-in Alloy convert command can migrate your Prometheus configuration to an Alloy configuration.

This topic describes how to:

Convert a Prometheus configuration to an Alloy configuration.
Run a Prometheus configuration natively using Alloy.

Components used in this topic

Before you begin

You must have a Prometheus configuration.
You must have a set of Prometheus applications ready to push telemetry data to Alloy.
You must be familiar with the concept of Components in Alloy.

Convert a Prometheus configuration

To fully migrate your configuration from Prometheus to Alloy, you must convert your Prometheus configuration into an 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 CLI command to output an Alloy configuration from a Prometheus configuration.

Open a terminal window and run the following command.
shell
```
alloy convert --source-format=prometheus --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
```
Replace the following:
- <INPUT_CONFIG_PATH>: The full path to the Prometheus configuration.
- <OUTPUT_CONFIG_PATH>: The full path to output the Alloy configuration.
Run Alloy using the new Alloy configuration from <OUTPUT_CONFIG_PATH>:

Debugging

If the convert command can’t convert a Prometheus 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 Prometheus configuration. Make sure you fully test the converted configuration before using it in a production environment.
shell
```
alloy convert --source-format=prometheus --bypass-errors --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
```
Replace the following:
- <INPUT_CONFIG_PATH>: The full path to the Prometheus configuration.
- <OUTPUT_CONFIG_PATH>: The full path to output the Alloy configuration.
You can also output a diagnostic report by including the --report flag.
shell
```
alloy convert --source-format=prometheus --report=<OUTPUT_REPORT_PATH> --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
```
Replace the following:
- <INPUT_CONFIG_PATH>: The full path to the Prometheus configuration.
- <OUTPUT_CONFIG_PATH>: The full path to output the Alloy configuration.
- <OUTPUT_REPORT_PATH>: The output path for the report.
Using the example Prometheus configuration below, the diagnostic report provides the following information:
plaintext
```
(Info) Converted scrape_configs job_name "prometheus" into...
  A prometheus.scrape.prometheus component
(Info) Converted 1 remote_write[s] "grafana-cloud" into...
  A prometheus.remote_write.default component
```

Run a Prometheus configuration

If you’re not ready to completely switch to an Alloy configuration, you can run Alloy using your Prometheus configuration. The --config.format=prometheus flag tells Alloy to convert your Prometheus configuration to an Alloy configuration and load it directly without saving the new configuration. This allows you to try Alloy without modifying your Prometheus configuration infrastructure.

In this task, you use the run CLI command to run Alloy using a Prometheus configuration.

Run Alloy and include the command line flag --config.format=prometheus. Your configuration file must be a valid Prometheus configuration file rather than an Alloy configuration file.

Debug

You can follow the convert CLI command debugging instructions to generate a diagnostic report.
Refer to Debug Alloy for more information about a running Alloy.
If your Prometheus 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=prometheus.

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 a Prometheus configuration file to an Alloy configuration file.

The following Prometheus configuration file provides the input for the conversion.

global:
  scrape_timeout:    45s

scrape_configs:
  - job_name: "prometheus"
    static_configs:
      - targets: ["localhost:12345"]

remote_write:
  - name: "grafana-cloud"
    url: "https://prometheus-us-central1.grafana.net/api/prom/push"
    basic_auth:
      username: <USERNAME>
      password: <PASSWORD>

The convert command takes the YAML file as input and outputs a Alloy configuration] file.

alloy convert --source-format=prometheus --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>

Replace the following:

<INPUT_CONFIG_PATH>: The full path to the Prometheus configuration.
<OUTPUT_CONFIG_PATH>: The full path to output the Alloy configuration.

The new Alloy configuration file looks like this:

prometheus.scrape "prometheus" {
  targets = [{
    __address__ = "localhost:12345",
  }]
  forward_to     = [prometheus.remote_write.default.receiver]
  job_name       = "prometheus"
  scrape_timeout = "45s"
}

prometheus.remote_write "default" {
  endpoint {
    name = "grafana-cloud"
    url  = "https://prometheus-us-central1.grafana.net/api/prom/push"

    basic_auth {
      username = "USERNAME"
      password = "PASSWORD"
    }

    queue_config {
      capacity             = 2500
      max_shards           = 200
      max_samples_per_send = 500
    }

    metadata_config {
      max_samples_per_send = 500
    }
  }
}

Limitations

Configuration conversion is done on a best-effort basis. 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:

The following configurations aren’t available for conversion to Alloy: rule_files, alerting, remote_read, storage, and tracing. Any additional unsupported features are returned as errors during conversion.
Check if you are using any extra command line arguments with Prometheus that aren’t present in your configuration file. For example, --web.listen-address.
Meta-monitoring metrics exposed by Alloy usually match Prometheus 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 Prometheus.
Alloy exposes the Alloy UI.

Migrate from Promtail to Grafana Alloy

Mon, 30 Mar 2026 15:47:22 +0000

Migrate from Promtail to Grafana Alloy

The built-in Alloy convert command can migrate your Promtail configuration to an Alloy configuration.

This topic describes how to:

Convert a Promtail configuration to an Alloy configuration.
Run a Promtail configuration natively using Alloy.

Components used in this topic

Before you begin

You must have a Promtail configuration.
You must be familiar with the concept of Components in Alloy.

Convert a Promtail configuration

To fully migrate from Promtail to Alloy, you must convert your Promtail configuration into an 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 CLI command to output an Alloy configuration from a Promtail configuration.

Open a terminal window and run the following command.
shell
```
alloy convert --source-format=promtail --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
```
Replace the following:
- <INPUT_CONFIG_PATH>: The full path to the Promtail configuration.
- <OUTPUT_CONFIG_PATH>: The full path to output the Alloy configuration.
Run Alloy using the new configuration from <OUTPUT_CONFIG_PATH>:

Debugging

If the convert command can’t convert a Promtail 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 Promtail configuration. Make sure you fully test the converted configuration before using it in a production environment.
shell
```
alloy convert --source-format=promtail --bypass-errors --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
```
Replace the following:
- <INPUT_CONFIG_PATH>: The full path to the Promtail configuration.
- <OUTPUT_CONFIG_PATH>: The full path to output the Alloy configuration.

You can also output a diagnostic report by including the --report flag.

alloy convert --source-format=promtail --report=<OUTPUT_REPORT_PATH> --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>

Replace the following:

<INPUT_CONFIG_PATH>: The full path to the Promtail configuration.
<OUTPUT_CONFIG_PATH>: The full path to output the Alloy configuration.
<OUTPUT_REPORT_PATH>: The output path for the report.

If you use the example Promtail configuration below, the diagnostic report provides the following information:

(Warning) If you have a tracing set up for Promtail, it cannot be migrated to Alloy automatically. Refer to the documentation on how to configure tracing in Alloy.
(Warning) The metrics from Alloy are different from the metrics emitted by Promtail. If you rely on Promtail's metrics, you must change your configuration, for example, your alerts and dashboards.

Run a Promtail configuration

If you’re not ready to completely switch to an Alloy configuration, you can run Alloy using your Promtail configuration. The --config.format=promtail flag tells Alloy to convert your Promtail configuration to Alloy and load it directly without saving the new configuration. This allows you to try Alloy without modifying your Promtail configuration infrastructure.

In this task, you use the run CLI command to run Alloy using a Promtail configuration.

Run Alloy and include the command line flag --config.format=promtail. Your configuration file must be a valid Promtail configuration file rather than an Alloy configuration file.

Debug

You can follow the convert CLI command debugging instructions to generate a diagnostic report.
Refer to the Alloy Debugging for more information about running Alloy.
If your Promtail 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=promtail.

Caution
If you bypass the errors, the behavior of the converted configuration may not match the original Promtail configuration. Don’t use this flag in a production environment.

Example

This example demonstrates converting a Promtail configuration file to an Alloy configuration file.

The following Promtail configuration file provides the input for the conversion.

clients:
  - url: http://localhost/loki/api/v1/push
scrape_configs:
  - job_name: example
    static_configs:
      - targets:
          - localhost
        labels:
          __path__: /var/log/*.log

The convert command takes the YAML file as input and outputs an Alloy configuration file.

alloy convert --source-format=promtail --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>

Replace the following:

<INPUT_CONFIG_PATH>: The full path to the Promtail configuration.
<OUTPUT_CONFIG_PATH>: The full path to output the Alloy configuration.

The new Alloy configuration file looks like this:

local.file_match "example" {
  path_targets = [{
    __address__ = "localhost",
    __path__    = "/var/log/*.log",
  }]
}

loki.source.file "example" {
  targets    = local.file_match.example.targets
  forward_to = [loki.write.default.receiver]
}

loki.write "default" {
  endpoint {
    url = "http://localhost/loki/api/v1/push"
  }
  external_labels = {}
}

Limitations

Configuration conversion is done on a best-effort basis. 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:

Check if you are using any extra command line arguments with Promtail that aren’t present in your configuration file. For example, -max-line-size.
Check if you are setting any environment variables, whether expanded in the configuration file itself or consumed directly by Promtail, such as JAEGER_AGENT_HOST.
In Alloy, the positions file is saved at a different location. Refer to the loki.source.file documentation for more details. Check if you have any setup, for example, a Kubernetes Persistent Volume, that you must update to use the new positions path.
Meta-monitoring metrics exposed by Alloy usually match Promtail 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 Promtail.
Alloy exposes the Alloy UI, which differs from the Promtail Web UI.
If you are converting a Promtail configuration and not deploying as a Kubernetes daemonset, modify the generated configuration to ensure discovery.kubernetes discovery behaves as expected. The converter makes the same assumption as promtail that any pod discovery is for a daemonset deployment.

Migrate to Grafana Alloy on Grafana Labs

Migrate Grafana Agent Static to Grafana Alloy

Migrate from Grafana Agent Static to Grafana Alloy

Components used in this topic

Before you begin

Convert a Grafana Agent Static configuration

Debugging

Run a Grafana Agent Static mode configuration

Debug

Example

Integrations Next

Environment variables

Limitations

Migrate from Grafana Agent Operator to Grafana Alloy

Migrate from Grafana Agent Operator to Grafana Alloy

Deploy Alloy with Helm

Convert MetricsInstance to Alloy components

Collect logs

Integrations

Migrate Grafana Agent Flow to Grafana Alloy

Migrate from Grafana Agent Flow to Grafana Alloy

Before you begin

Differences between Grafana Agent Flow and Alloy

Steps

Prepare your Grafana Agent Flow configuration

Deploy Alloy with a default configuration

Migrate Grafana Agent Flow data to Alloy

Migrate pipelines that receive data over the network

Migrate the remaining pipelines

Uninstall Grafana Agent Flow

Cleanup temporary changes

Migrate from OpenTelemetry Collector to Grafana Alloy

Migrate from OpenTelemetry Collector to Alloy

Components used in this topic

Before you begin

Convert an OpenTelemetry Collector configuration

Debugging

Run an OpenTelemetry Collector configuration

Debug

Example

Limitations

Migrate from Prometheus to Grafana Alloy

Migrate from Prometheus to Grafana Alloy

Components used in this topic

Before you begin

Convert a Prometheus configuration

Debugging

Run a Prometheus configuration

Debug

Example

Limitations

Migrate from Promtail to Grafana Alloy

Migrate from Promtail to Grafana Alloy

Components used in this topic

Before you begin

Convert a Promtail configuration

Debugging

Run a Promtail configuration

Debug

Example

Limitations

Convert `MetricsInstance` to Alloy components