--- title: "Migrate Grafana Agent Static to Grafana Agent Flow | Grafana Agent documentation" description: "Learn how to migrate your configuration from Grafana Agent Static to Grafana Agent Flow" --- # Migrate from Grafana Agent Static to Grafana Agent Flow The built-in Grafana Agent convert command can migrate your [Static](/docs/agent/latest/static/) configuration to a Grafana Agent Flow configuration. This topic describes how to: - Convert a Grafana Agent Static configuration to a Grafana Agent Flow configuration. - Run a Grafana Agent Static configuration natively using Grafana Agent Flow. ## Components used in this topic - [prometheus.scrape](/docs/agent/latest/flow/reference/components/prometheus.scrape/) - [prometheus.remote\_write](/docs/agent/latest/flow/reference/components/prometheus.remote_write/) - [local.file\_match](/docs/agent/latest/flow/reference/components/local.file_match/) - [loki.process](/docs/agent/latest/flow/reference/components/loki.process/) - [loki.source.file](/docs/agent/latest/flow/reference/components/loki.source.file/) - [loki.write](/docs/agent/latest/flow/reference/components/loki.write/) ## Before you begin - You must have an existing Grafana Agent Static configuration. - You must be familiar with the [Components](/docs/agent/latest/flow/concepts/components/) concept in Grafana Agent Flow. ## Convert a Grafana Agent Static configuration To fully migrate Grafana Agent [Static](/docs/agent/latest/static/) to Grafana Agent Flow, you must convert your Static 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/latest/flow/reference/cli/convert/) CLI command to output a Grafana Agent Flow configuration from a Static 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=static --output= ``` flow-binary ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```flow-binary grafana-agent-flow convert --source-format=static --output= ``` Replace the following: - *``* : The full path to the [Static](/docs/agent/latest/static/) configuration. - \_`_`: The full path to output the Grafana Agent Flow configuration. 2. [Run](/docs/agent/latest/flow/reference/cli/run/) Grafana Agent Flow using the new Grafana Agent Flow configuration from *``* : ### Debugging 1. If the convert command can’t convert a [Static](/docs/agent/latest/static/) configuration, diagnostic information is sent to `stderr`. You can use the `--bypass-errors` flag to bypass any non-critical issues and output the Grafana Agent Flow 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. 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=static --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=static --bypass-errors --output= ``` Replace the following: - *``* : The full path to the [Static](/docs/agent/latest/static/) configuration. - *``* : The full path to output the Grafana Agent Flow configuration. 2. You can use the `--report` flag to output a diagnostic report. 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=static --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=static --report= --output= ``` ```` Replace the following: - *``* : The full path to the [Static](/docs/agent/latest/static/) configuration. - *``* : The full path to output the Grafana Agent Flow configuration. - *``* : The output path for the report. Using the [example](#example) Grafana Agent Static configuration below, the diagnostic report provides the following information. plaintext ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```plaintext (Warning) Please review your agent command line flags and ensure they are set in your Grafana Agent Flow configuration file where necessary. ``` ## Run a Static mode configuration If you’re not ready to completely switch to a Grafana Agent Flow configuration, you can run Grafana Agent using your existing Grafana Agent Static configuration. The `--config.format=static` flag tells Grafana Agent to convert your [Static](/docs/agent/latest/static/) configuration to Grafana Agent Flow and load it directly without saving the new configuration. This allows you to try Grafana Agent Flow without modifying your existing Grafana Agent Static configuration infrastructure. > In this task, you will use the [run](/docs/agent/latest/flow/reference/cli/run/) CLI command to run Grafana Agent Flow using a Static configuration. [Run](/docs/agent/latest/flow/reference/cli/run/) Grafana Agent Flow and include the command line flag `--config.format=static`. Your configuration file must be a valid [Static](/docs/agent/latest/static/) 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 UI](/docs/agent/latest/flow/tasks/debug/) for more information about running Grafana Agent Flow. 3. If your [Static](/docs/agent/latest/static/) configuration can’t be converted and loaded directly into Grafana Agent Flow, 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 Grafana Agent Flow. > Caution > > If you bypass the errors, the behavior of the converted configuration may not match the original Grafana Agent Static configuration. Do not use this flag in a production environment. ## Example This example demonstrates converting a [Static](/docs/agent/latest/static/) configuration file to a Grafana Agent Flow configuration file. The following [Static](/docs/agent/latest/static/) configuration file provides the input for the conversion. YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml 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\d{4}/\d{2}/\d{2} \d{2}:\d{2}:\d{2}) \[(?P[[:alpha:]]+)\] (?:\d+)\#(?:\d+): \*(?:\d+) (?P.+)$' - pack: labels: - level clients: - url: https://USER_ID:API_KEY@logs-prod3.grafana.net/loki/api/v1/push ``` The convert command takes the YAML file as input and outputs a [River](/docs/agent/latest/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=static --output= ``` flow-binary ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```flow-binary grafana-agent-flow convert --source-format=static --output= ``` Replace the following: - *``* : The full path to the [Static](/docs/agent/latest/static/) 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 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-3a2a1b" url = "https://prometheus-us-central1.grafana.net/api/prom/push" basic_auth { username = "" 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\\d{4}/\\d{2}/\\d{2} \\d{2}:\\d{2}:\\d{2}) \\[(?P[[:alpha:]]+)\\] (?:\\d+)\\#(?:\\d+): \\*(?:\\d+) (?P.+)$" } 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" } } loki.write "logs_varlogs" { endpoint { url = "https://USER_ID:API_KEY@logs-prod3.grafana.net/loki/api/v1/push" } external_labels = {} } ``` ## Integrations Next You can convert \[integrations next]\[] configurations by adding the `extra-args` flag for [convert](/docs/agent/latest/flow/reference/cli/convert/) or `config.extra-args` for [run](/docs/agent/latest/flow/reference/cli/run/). 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=static --extra-args="-enable-features=integrations-next" --output= ``` flow-binary ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```flow-binary grafana-agent-flow convert --source-format=static --extra-args="-enable-features=integrations-next" --output= ``` Replace the following: - *``* : The full path to the [Static](/docs/agent/latest/static/) configuration. - *``* : The full path to output the Grafana Agent Flow configuration. ## Environment Vars 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](/docs/agent/latest/flow/reference/cli/convert/) with `--extra-args="-config.expand-env"` or to [run](/docs/agent/latest/flow/reference/cli/run/) with `--config.extra-args="-config.expand-env"`. > It’s possible to combine `integrations-next` with `expand-env`. For [convert](/docs/agent/latest/flow/reference/cli/convert/), you can use `--extra-args="-enable-features=integrations-next -config.expand-env"` ## 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 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: - The [Agent Management](/docs/agent/latest/static/configuration/agent-management/) configuration options can’t be automatically converted to Grafana Agent Flow. Any additional unsupported features are returned as errors during conversion. - There is no gRPC server to configure for Grafana Agent Flow, as any non-default configuration will show as unsupported during the conversion. - Check if you are using any extra command line arguments with Static that aren’t present in your configuration file. For example, `-server.http.address`. - Check if you are using any environment variables in your [Static](/docs/agent/latest/static/) configuration. These will be evaluated during conversion and you may want to replace them with the Grafana Agent Flow Standard library [env](/docs/agent/latest/flow/reference/stdlib/env/) function after conversion. - Review additional [Prometheus Limitations](/docs/agent/latest/flow/tasks/migrate/from-prometheus/#limitations) for limitations specific to your [Metrics](/docs/agent/latest/static/configuration/metrics-config/) configuration. - Review additional [Promtail Limitations](/docs/agent/latest/flow/tasks/migrate/from-promtail/#limitations) for limitations specific to your [Logs](/docs/agent/latest/static/configuration/logs-config/) configuration. - The logs produced by Grafana Agent Flow mode will differ from those produced by Static. - Grafana Agent exposes the Grafana Agent Flow [UI](/docs/agent/latest/flow/tasks/debug/#grafana-agent-flow-ui).