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 an existing 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 will enable you to take full advantage of the many additional features available in Alloy.
In this task, you will use the convert CLI command to output an Alloy configuration from a Static configuration.
Open a terminal window and run the following command.
shellalloy convert --source-format=static --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
Replace the following:
<INPUT_CONFIG_PATH>
: The full path to the Grafana Agent Static 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 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.shellalloy convert --source-format=static --bypass-errors --output=<OUTPUT_CONFIG_PATH> <INPUT_CONFIG_PATH>
Replace the following:
<INPUT_CONFIG_PATH>
: The full path to the Grafana Agent Static configuration.<OUTPUT_CONFIG_PATH>
: The full path to output the Alloy configuration.
You can use the
--report
flag to output a diagnostic report.shellalloy 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 Grafana Agent Static configuration.<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 existing 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 new configuration.
This allows you to try Alloy without modifying your existing Grafana Agent Static configuration infrastructure.
In this task, you will use the run CLI command to run Alloy using a 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.
Debugging
You can 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. Do not 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
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 Grafana Agent Static configuration.<OUTPUT_CONFIG_PATH>
: The full path to output the Alloy configuration.
The new 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-3a2a1b"
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 = {}
}
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 Grafana Agent Static configuration.<OUTPUT_CONFIG_PATH>
: The full path to output the Alloy 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 with --extra-args="-config.expand-env"
or to run with --config.extra-args="-config.expand-env"
.
It’s possible to combine
integrations-next
withexpand-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 will issue warnings or errors where the conversion can’t be performed.
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, 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 Grafana Agent Static configuration. These will be evaluated during conversion and you may want to replace them with the Alloy Standard library 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 mode will differ from those produced by Static.
- Alloy exposes the Alloy UI.
Was this page helpful?
Related documentation
Related resources from Grafana Labs
![Getting started with the Grafana LGTM Stack](/static/assets/featured/getting-started-with-grafana-lgtm-stack-amer_featured.png?w=200 200w, /static/assets/featured/getting-started-with-grafana-lgtm-stack-amer_featured.png?w=400 400w)
![Intro to Kubernetes monitoring in Grafana Cloud](/media/webinar/Screenshot-2024-02-12-at-4.09.30-PM.png?w=200 200w, /media/webinar/Screenshot-2024-02-12-at-4.09.30-PM.png?w=400 400w)
![Building advanced Grafana dashboards](/media/webinar/AMER_buildadv_notxt.png?w=200 200w, /media/webinar/AMER_buildadv_notxt.png?w=400 400w)