How to migrate from Grafana Agent to Alloy and how much effort it takes
The move from Grafana Agent Static to Alloy is mostly an inventory and configuration exercise, run alongside the existing agents until each host is verified. Effort depends on how many configurations, components and hosts are involved, and on how many of them rely on settings that do not convert automatically. A team with a few hosts running one simple configuration will have a very different job from a team with dozens of hosts, several configuration files per host and custom pipelines for logs, metrics and traces. Start by listing every Static configuration in use, which host runs it, which receivers, scrape jobs and exporters it defines, and who owns the dashboards and alerts that depend on the data it sends. That list is the basis for any estimate, and it is the first thing to ask a partner or an internal team to produce.
Effort also depends on what must be proven before a host is switched over. Each Alloy configuration needs to produce the same series, logs and traces that the Static agent produced, and dashboards and alert rules need to keep working against them. Plan a parallel run in which both agents send data for a period, then compare the outputs before stopping the Static service. Because DeployOpen does not publish a price list, the cost of this work is set by the written scope, so ask for the inventory, the parallel-run criteria and the rollback steps to be written into that scope. Confirm the current Alloy and Grafana Agent documentation for your versions before you begin, since conversion behavior and supported components change between releases.
What maps cleanly from Grafana Agent to Alloy and what does not
This table compares the Grafana Agent Static capabilities most teams rely on with their Alloy counterparts and notes where conversion needs manual work. Read each row as a question to check against the report generated by alloy convert, since automatic conversion does not cover every setting. Component names and support status change between releases, so confirm each one in the Alloy documentation for your version before you cut over.
| Static capability | Alloy equivalent | Migration note |
|---|---|---|
| Metrics scraping with scrape configs | Prometheus scrape components built from discovery and scrape blocks | Check the generated report for each job. Relabeling rules and job names usually carry over, but confirm each scrape target still resolves. |
| Service discovery settings | Discovery components for the same providers used by Static | Discovery blocks are not always converted one to one. Verify every discovery source in the report against the Alloy docs. |
| Remote write targets | Prometheus remote write component with endpoint and authentication blocks | Credentials and TLS settings often need manual entry. Store them in a secrets mechanism your team controls rather than in plain config files. |
| Logs collection from files and journals | Log file and journal source components forwarded to a Loki write component | Pipeline stages and label handling may not convert. Test label cardinality on a single host before fleet rollout. |
| Integrations (embedded exporters) | Matching exporter or integration components, where Alloy provides one | Not every Static integration has an Alloy component with the same options. Mark any integration without a match as a blocker to resolve first. |
| Traces and OpenTelemetry pipelines | OpenTelemetry receivers and exporters in Alloy | Static pipeline definitions do not map automatically in every case. Review exporter endpoints and sampling settings by hand. |
| Settings the converter reports as unsupported | Manual rewrite or removal, based on the reason in the report | Treat every unsupported line as an open item. Assign an owner and a verification step before any host is changed. |
Which documented conversion tools and export paths the move uses
Four routes are available for leaving Grafana Agent Static: converting its configuration with the Alloy tooling, running the existing files for a short period, or moving telemetry to a vendor-neutral collector. Each answers a different question, so confirm which one fits each host group before the cutover order is set.
The alloy convert command
The alloy convert command reads a Static configuration file and writes an Alloy configuration plus a report listing what was translated and what was not. The report is the working document for the migration, because it tells you which blocks need manual rework. It does not validate that the converted pipeline sends data where you expect, so run each converted file against a test host before you rely on it. Confirm the flags and report format in the Alloy release you deploy.
Static configuration files as input
The Static YAML files on each host are the source of truth for what is scraped, processed and forwarded today. Inventory every file, including those in drop-in directories and those pushed by configuration management, because a converter can only convert what it is given. Settings that depend on host paths, secrets in environment variables or remote configuration may need to be rebuilt by hand. Record which file belongs to which host group before you convert anything.
Running Static as a stopgap
Keeping Grafana Agent Static running unchanged buys time for hosts that cannot be cut over yet, such as systems in a change freeze. This path adds no new configuration work, but it also keeps an agent you are moving away from in production. Plan a dated exit for each stopgap host and confirm with Grafana Labs how long the Static release you run will receive support before you commit to it.
OpenTelemetry Collector as an alternative
The OpenTelemetry Collector is a vendor-neutral receiver, processor and exporter that can run as an agent beside workloads or as a gateway for many sources. It is Apache-2.0 licensed and is not an Alloy export path, so choose it only if you want to change collectors, not just the agent. Its components have mixed stability levels, so check each component's README and confirm that your Static pipelines map onto supported components before you pick it.
Why some Static settings do not convert one for one
Conversion from Grafana Agent Static to Alloy is a translation between two configuration models, not a copy of a file. Static organizes telemetry collection around its own YAML layout, where metrics, logs and integrations are declared as sections that each carry their own settings. Alloy describes the same work as a graph of components connected by arguments and exports, so a single Static setting may become a block in one place, a reference to another component somewhere else, or a value that no longer exists because Alloy handles that job differently. The alloy convert command performs the mechanical part of this translation, but the output is a new Alloy configuration that must be read as a design, not as a faithful mirror of the old file.
The conversion report is the first place to see where the translation broke down. It lists settings the converter could not map, settings it mapped with changed behavior, and features that have no direct Alloy equivalent. Treat every entry as an open item with an owner and a decision: accept the change, rebuild the behavior with different components, or keep that host on Static for now. Secrets, credentials and file paths need a separate manual review even when the report is clean. Passwords, tokens and TLS key locations may be carried over as literal values or as paths that exist on the old host but not on the new one, and Alloy's own handling of sensitive values should be checked against your secret store before any configuration leaves a test environment. Confirm the exact Alloy version you are targeting against the current documentation, since component behavior changes between releases.
A clean conversion only proves that the file parses and the components link together. It does not prove that the same metrics, logs and labels arrive at the backend with the same names, cardinality and timing that your dashboards and alert rules depend on. Before cutover, run the converted Alloy configuration beside the Static agent on a representative host, compare series and log streams in the backend for the same source, and check the dashboards and alert rules that consume them. Illustrative example: a missing relabeling rule can leave a dashboard that still renders but silently drops a label that an alert uses for routing. Record each comparison in the migration log so the cutover decision rests on evidence from your own telemetry.
Running Static as a stopgap or converting before the cutover
Teams that need a bridge usually run a working Static configuration on hosts that cannot change yet, while someone reviews what that configuration does. Leaving Static in place keeps existing scrape, log and forwarding pipelines running without touching the host fleet, so dashboards and alerts that depend on current series and labels keep working during the review.
- What it keeps running: the existing Static binary and configuration file, so telemetry flows as it does today.
- What it defers: conversion, pipeline review, handling of settings that have no direct equivalent, and any change to labels or metric names.
- Duplicate data risk: if Alloy is installed on a host while Static still scrapes the same targets, both collectors send overlapping series or logs, which inflates storage and can double-count alerts.
- Decision criteria: choose the bridge when the review has a named owner, the host group uses a small number of configuration files, and the Static release in use is confirmed as supported for the period you need.
Confirm the supported lifetime of Static with Grafana Labs before you commit to a bridge, because that date sets how long the bridge can safely run.
Teams that can convert now translate each Static configuration into Alloy, review the output against the conversion report, and then cut over one host group at a time. Conversion moves effort to the front of the project: the review of converted pipelines, labels and credentials happens before any production host changes, and the report shows which settings need a manual decision.
- What it changes: the configuration is translated, reviewed and deployed first to a small canary subset of the group.
- What it defers: little on the host itself, but the review of unconverted settings is pulled forward and needs an owner.
- Duplicate data risk: overlap is brief if the process is ordered correctly, but it appears when Alloy starts before Static stops on the same targets.
- Decision criteria: the host group shares a standard configuration, the owner can compare dashboards and alerts against the converted output, and a rollback path to the Static package is kept until the group is verified.
Check the conversion report for each group before the canary starts, and confirm with the Alloy release notes which settings the report flags as unsupported in your version.
Whichever path you take, each host group should follow exactly one path at any moment. Mixed fleets are the usual source of duplicate series, so the practical work is an inventory that records, for every group, which collector runs, which targets it scrapes and who signs off on the change.
- Inventory by target: list the scrape targets and log sources each host group feeds, so you can see where two collectors would read the same source.
- Dependency check: note which alerts, recording rules and dashboards read the affected series, because those are the first to show a change in names or label sets.
- Stop before start: plan each cutover so the Static service stops before Alloy starts on the same targets, or disable the Static scrape job first.
- Rollback plan: keep the Static package and configuration available for each group until its dashboards and alerts are confirmed against the new collector.
- Verification: compare series counts and alert states before and after each group moves, and record the result with the group owner.
Ask your team to confirm which path each group is on in a single shared inventory, since that record is what prevents two collectors from running against the same host.
The cutover order for a fleet of hosts
This sequence moves a fleet from Grafana Agent Static to Alloy one host group at a time, with a reviewed configuration, a parallel comparison and a rollback path at every stage. Each step ends with a sign-off so that no group changes until the previous one is proven.
Inventory every Static configuration and host group
Before any conversion, list every Static configuration file, the hosts that load each one and the backends they write to. Group hosts by shared configuration, operating system and owning team, because each group becomes one cutover unit. Record which components each configuration uses, such as metrics scrapes, log pipelines, integrations and remote write endpoints, and note any host-specific values. The output is an inventory with one row per host group. Sign-off: the platform owner and each team that runs hosts confirm the inventory is complete, including hosts that are rarely touched.
Convert and review in a non-production environment
Run the conversion command on copies of the Static configurations in a non-production environment, and keep the generated Alloy configuration and the conversion report together for each group. Work through every warning and every setting the report marks as unconverted, and decide whether it needs a manual rewrite, a different component or removal. Check secrets and file paths separately, since they are often the first things to break on a new host. Sign-off: the engineer who owns the group confirms that each report entry has an explicit disposition and that the Alloy configuration validates in the non-production environment.
Pilot on a small host group
Deploy the reviewed Alloy configuration to one small, representative host group, and keep Static running on the same hosts in a stopped or standby state so the rollback path is ready. Read the conversion report line by line against the running Alloy configuration and confirm that each scrape target, log source and output endpoint is present. Check that host labels and external labels match what dashboards and alert rules expect. The output is a pilot record of what was checked and what was changed. Sign-off: the owning team confirms that the pilot data arrives in the same backends with the expected labels before the next group is considered.
Run both collectors in parallel and compare
For each group that passes the pilot, run Static and Alloy side by side so that both send telemetry for the same hosts, and compare the series and log counts per host and per job over the same window. Investigate any gap in either direction, because a missing series usually means a dropped scrape target or a filter that was converted differently. Keep the two streams apart with distinct labels or a test tenant so that duplicate data does not pollute production dashboards and alerts. Sign-off: the team records the comparison and accepts any remaining differences in writing, with each difference traced to a cause.
Cut over group by group with a rollback path
Move one host group at a time from Static to Alloy, starting with the group that carries the least operational risk. Stop the Static service on each host only after Alloy is confirmed to be sending data, and keep the Static package and configuration in place so the group can be restored quickly. Watch dashboards, alert rules and the Alloy service health during each cutover before starting the next group. The output is a cutover log per group with the time of change and the rollback steps tested. Sign-off: the group owner confirms that data is flowing and that the rollback has been exercised or verified on a host before the next group moves.
Confirm the fleet is fully on Alloy
Once every group has cut over, check the full inventory against the running fleet to confirm that no host still runs Static or sends data through it. Review dashboards and alert rules for any leftover references to Static-specific labels, job names or metric names, and update them to the Alloy equivalents. Keep the rollback artifacts for an agreed retention period that your change process defines. The output is a signed inventory showing each host on Alloy. Sign-off: the platform owner confirms that the inventory matches the fleet and that no group is waiting on a Static fallback.
Decommission Static and remove its service definitions
Remove the Static service definitions, unit files and scheduled checks from every host, then uninstall the Static package once the rollback retention period has ended. Delete or archive the Static configuration files in your configuration repository so that nobody restores them by mistake, and update runbooks, provisioning templates and images so new hosts start with Alloy only. Record the removal in the change log. The output is a clean fleet with a documented final state. Sign-off: the platform owner and the security owner confirm that no Static binaries, credentials or configuration remain on hosts or in build pipelines.
What drives the cost and duration of the Alloy migration
This table lists the factors that change the effort of moving from Grafana Agent Static to Alloy, with the direction each one moves cost and how to keep it down. Read it as a checklist for scoping: the one-time work (inventory, conversion, testing, cutover) is separated from the recurring work (maintaining Alloy configurations and upgrading collectors). Ask any quote to price each driver separately so you can see which ones your environment triggers.
| Driver | Effect on cost and duration | How to keep it down |
|---|---|---|
| Number of Static configurations and host groups | Rises with each distinct configuration file and host group, since each needs its own conversion, review and cutover wave | Group hosts by shared configuration so one converted file serves many hosts |
| Custom integrations and scrape jobs | Rises with each non-standard integration or hand-written scrape job that the converter does not map cleanly | Retire unused jobs during the inventory before converting anything |
| Secrets and identity handling | Rises when credentials are embedded in files or when authentication to backends must be redesigned | Move secrets to a managed store before cutover and reuse existing identity settings |
| Backends and dashboards that depend on series names | Rises when relabeling or metric name changes break queries, alert rules or dashboards downstream | List dependent dashboards and rules during inventory and keep metric names stable where possible |
| Parallel-run length | Rises with every week both agents ship data, because duplicate ingestion and comparison work continue | Set exit criteria for the comparison before the parallel run starts |
| Change windows | Rises when host groups can only be touched in narrow maintenance windows, which stretches the calendar more than the effort | Agree window availability with change owners before scheduling waves |
| Amount of testing | Rises with the number of signal types, backends and environments that need verified output | Test against a representative host group first and reuse the test cases for later waves |
| Recurring Alloy configuration maintenance | Recurs for as long as Alloy configurations are owned, including reviews and changes to pipelines | Keep configurations in version control with a named owner and documented change process |
| Recurring collector upgrades | Recurs with each Alloy release that needs validation across the fleet, so cost grows with fleet size | Standardize versions and include upgrade testing in the support scope |
What usually goes wrong during the Agent to Alloy move and how to prevent it
Most failures in an Agent to Alloy move come from the overlap period, from names that change under dashboards and alerts, and from decisions made host by host without a plan. Each card below names one risk, the step that prevents it, and what to check in the component documentation before cutover.
Duplicate or missing series during overlap
While Static and Alloy both run, the same host can send the same series twice, or a series can disappear when one side is stopped too early. Duplicates inflate panels and break rate calculations, and gaps look like outages. Before cutover, assign one owner per host and decide which agent writes to the backend at each stage. Compare series counts per job for a defined window on a pilot host before expanding. Check each Alloy component's stability level in the component documentation before relying on it for those series.
Dashboards and alerts that break on renamed metrics
Converted pipelines can change metric names, job labels or instance labels, so queries and alert rules that match the old values stop returning data. This failure is often silent because the alert simply never fires. Inventory every dashboard panel and alert rule that filters on agent-generated labels, then map old names to new ones in a spreadsheet. Run the old and new queries side by side and confirm the results match before you retire the Static job. Treat any label change as a change request for the owning team.
Secrets left in converted files
Converted configurations often carry remote write credentials, basic auth passwords or tokens inline, and those values then sit in files, version control and shared tickets. Review every converted file for literal credentials before it is copied to a host or committed. Move secrets to the mechanism your team already uses, such as environment variables or a secrets manager, and restrict file permissions on the Alloy configuration directory. Rotate any credential that appeared in a report or log during conversion.
Host groups cut over without a rollback
Cutting an entire fleet in one change window leaves no working collector if the converted configuration fails on a common setting. Schedule cutover in rings, starting with a small group of non-critical hosts, and keep the Static package and its configuration installed until the ring is verified. Write the rollback command for each ring, such as stopping the Alloy service and restarting the Static service, and rehearse it on one host. Expand to the next ring only after the previous one passes the checks you defined.
Unsupported settings discovered late
Some Static settings have no direct equivalent, or convert into a form that needs manual review. Teams that read the conversion report only after deploying find these gaps when a collector fails to start or a scrape job goes quiet. Read the full report before any host is touched, and record each item as either fixed, accepted or blocked. Confirm the status of each replacement component in its documentation, since stability levels vary and may affect whether you can accept a given gap.
Undocumented Static integrations
Integrations enabled years ago, such as exporters or custom log sources, are often absent from the configuration files people review, so they are missed in the migration plan. When they stop, the gap goes unnoticed until someone asks for a dashboard. Before planning, query each host for the enabled integrations and compare them with the list in your configuration management. Add every undocumented integration to the migration plan with an owner and a verification step.
How long, how much effort and what the migration needs from our team
Does alloy convert cover our whole Grafana Agent configuration?
No, treat it as a starting point rather than a finished migration. The converter translates the parts of a Static configuration it recognizes and writes a report listing what it could not carry over. Your engineers still need to review every item in that report, decide how each unconverted setting should behave in Alloy, and test the output against real hosts. Effort is driven by how many non-default settings, custom relabeling rules, remote write targets and integrations your current files contain, not by the file count alone. Ask any partner to show how they will work through the report for your configuration before agreeing on scope.
How does migration effort grow with the number of hosts?
Effort grows with the number of distinct configurations, not simply with the number of machines. Hosts that share a role, operating system and config template can usually be converted once, tested once and then rolled out in groups, while hosts with bespoke scrape targets or unusual service setups each need their own review. Other drivers include how many environments you have (development, staging and production each need a cutover), whether hosts are managed by configuration management or by hand, and how much automation already exists for rollout and rollback. Ask for the quote to list configuration groups and environments separately from the host count.
What must our team provide before a migration starts?
Most delays come from missing inputs, so prepare these before the work begins:
- An inventory of every host running Grafana Agent Static, with its operating system, role and the configuration file it uses
- Read access to those configuration files, plus the Grafana Cloud or self-hosted endpoints they send data to
- Administrator access to the hosts, the configuration management tooling and the deployment pipeline
- Agreed change windows for each environment and a named approver for each cutover group
- A named owner for every dashboard and alert rule that depends on the telemetry, who can confirm that the data still looks correct
Confirm these items with your partner and with your own change management process, since requirements differ by organization.
Can our internal team migrate to Alloy without outside help?
Often yes, if the fleet is small, the configurations are uniform and the team already runs staged rollouts with rollback. The work is less about the converter and more about verification: comparing series and logs before and after each change, and confirming that alerts and dashboards still behave. Outside help tends to make sense when the fleet is large, several teams own different configurations, or the team has no spare capacity during change windows. Whichever way you go, ask for the cutover order, the test evidence you will keep and the rollback steps written down before the first host changes.
What happens to alerts and dashboards while both agents run in parallel?
During a parallel run, the same metrics or logs may reach your backend from two sources, which can create duplicate series, double-counted data or alerts that fire twice. Decide in advance which agent is authoritative for each dataset, and mute or scope duplicate alert notifications until the old agent is retired. Check that dashboards and alert rules query the expected series labels, because converted pipelines can change label sets. Your alerting owners should sign off on each group before its Static agent is stopped. The exact handling depends on your backend and alert setup, so confirm it against your own rule and routing design.
What recurring work follows the cutover?
Once the fleet runs Alloy, you carry ongoing work that is not one-time. Alloy and its components change over time, so you need a upgrade cadence, a test step for each new version and a way to roll it out across hosts. Configuration changes continue as services are added or retired, and each change should go through the same review you used for the migration. You also need someone who owns the Alloy configurations, the backend credentials they use and the alert rules that depend on them. Ask a partner whether support or an upgrade retainer is part of the scope, and what it covers after the initial cutover.
How DeployOpen scopes, delivers and supports the Alloy migration
DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside your own infrastructure, so the Grafana Agent to Alloy migration runs in your environment under your change controls. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- Inventory every Grafana Agent Static configuration, host group and the signals each one collects, including logs, metrics and traces.
- Record which settings convert with alloy convert and which need manual rewriting, so the written scope names each exception.
- Agree in writing whether a Static stopgap stays on certain hosts, and the date each host group moves to Alloy.
- Confirm the cutover order, rollback steps and the downstream backends, such as Grafana, Loki, Mimir or Tempo, that receive the data.
How we build
- Convert configurations in a staging environment, then review the conversion report line by line against the original files.
- Rewrite non-converting components and pipelines as Alloy configuration, keeping labels, relabeling and credentials consistent across hosts.
- Test each host group against live dashboards and alert queries to confirm that series and log streams still arrive without gaps.
- Keep configuration under version control and deploy it with repeatable tooling so every host receives the same reviewed files.
How we hand over
- Deliver a written record of the conversion report, every manual change and the reasoning behind it.
- Provide runbooks for deploying, restarting and rolling back Alloy on each host group, written for the team that will operate it.
- Walk your platform and operations engineers through the pipelines, verification checks and the Static decommission checklist.
- Document which Static agents were removed, when, and which data sources were checked after each cutover step.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer if your team wants DeployOpen to keep operating the pipelines.
- Review Alloy releases and component changes before you upgrade, so configuration changes are planned rather than discovered in production.
- Confirm with your team which support responsibilities stay internal and which move to a retainer before the engagement starts.
