Migrate from Promtail to Grafana Alloy for Loki

How to migrate from Promtail to Grafana Alloy for Loki without losing logs

Promtail reached end of life on March 2, 2026, with no further updates or commercial support, and Grafana directs Promtail users to Grafana Alloy, its supported log shipper for Loki. Every host or cluster still running Promtail is now collecting logs without fixes or vendor support. The migration should be scheduled as a dated project with a named owner, a rollback plan and a clear finish line, so that the agents running in production are supported before the next incident depends on them.

Effort depends on three factors: the size of the fleet, the number of distinct Promtail configurations, and how much pipeline logic lives inside those configurations. Pipeline logic includes stages that parse lines, extract labels, drop noisy entries, rewrite content or handle multiline events. No fixed duration applies to every environment, and this guide does not assign one. Confirm the effort through an inventory that lists each Promtail instance, its host or cluster, the configuration file it loads, the location of its positions file, the log sources it reads and the pipeline stages it runs. Many hosts sharing one configuration are usually simpler to convert than many one-off configurations.

This page covers agent migration only: moving log collection from Promtail to Grafana Alloy and keeping logs arriving at Loki without gaps. Loki server upgrades, including the schema, storage and configuration changes that a version change can require, belong to the Loki upgrades group. If your Loki servers are also due for a version change, plan that work as a separate track and confirm that the Alloy version you deploy works with the Loki version you run. Keeping the two tracks apart makes it easier to tell which change caused a problem if one occurs.

The main failure mode is a gap in logs or duplicate entries during cutover. Before any host switches, decide whether old and new agents will run side by side for a period, and how each agent will track its read position in each file so that the new agent does not resend or skip lines. Loki also accepts OpenTelemetry logs over HTTP, and documents support for Fluent Bit, Fluentd and the Docker logging driver. If part of the fleet already uses one of those shippers, confirm which option fits each group before converting configurations. Ask your team to document the chosen approach for each host group before the first rollout.

What maps from Promtail to Alloy and what needs rework

This table pairs each Promtail concept in your current configuration with its Grafana Alloy counterpart and marks how much work the move takes. Read the status column first to size the effort, then use the equivalent column to find the Alloy component to confirm. Component names and behavior change between releases, so check each one against the current Alloy documentation rather than assuming a one-to-one match.

Promtail concept	Alloy equivalent	Migration status
Scrape configs	Loki source components such as loki.source.file, wired to discovery components and the write path	Carries over with changes
Targets and service discovery	Discovery components for files, Kubernetes, Docker or other sources, feeding the log pipeline	Carries over with changes
Relabeling	discovery.relabel blocks that set labels before logs enter the pipeline; confirm which label names must stay stable for existing queries	Carries over with changes
Pipeline stages	loki.process blocks with equivalent stages; confirm each stage used in your configuration exists and behaves the same	Carries over with changes
Custom or regex-heavy pipeline logic	Rewrite and retest by hand against sample log lines before cutover	Rebuild by hand
Client settings (URL, batching, backoff, external labels)	loki.write endpoint blocks with batch and retry settings; confirm names and defaults in current documentation	Carries over with changes
Tenant identification	Tenant ID set on the write path for multi-tenant Loki; confirm how the tenant is assigned in the release you deploy	Carries over with changes
Positions file	Alloy keeps its own read offsets, and Promtail positions do not transfer, so plan the cutover window to avoid gaps or duplicate ingestion	Rebuild by hand
Promtail metrics and dashboards	Alloy exposes its own metric names; rebuild alerts and dashboards after confirming the new names in its documentation	Rebuild by hand

Documented conversion paths and what each one produces

Each path below is documented by Grafana, and each produces a different artifact. The converter gives a first draft of Alloy configuration, the send-data documentation defines where logs go, and the Promtail documentation sets the end-of-life deadline. Read the cards together, because the checks that remain after each step decide whether the rollout can start.

alloy convert for Promtail configs

Input: an existing Promtail configuration file. Output: a Grafana Alloy configuration file generated by the alloy convert command. This output is a first draft that still needs review. Read every block the converter emits, check its warnings for settings it could not carry over, and confirm the file loads under the Alloy version you plan to deploy. Keep the original Promtail file beside the output so each setting can be compared.

Alloy log collection components

Input: the Alloy configuration you produced or wrote by hand. Output: a running agent that reads log files and pushes them to Loki. The Loki send-data documentation names Grafana Alloy as Grafana's supported log shipper for Loki, so converted pipelines should end here. Check the component reference for your Alloy version, confirm that each log source and processing block you need exists, and verify that the labels reaching Loki match what your dashboards and alerts query.

Loki send-data endpoints and headers

Input: the shipper your team chooses, which may be Alloy, Fluent Bit, Fluentd, the Docker logging driver or OpenTelemetry logs sent over HTTP. Output: log pushes to Loki's ingest endpoint. Use this page when a team needs a shipper other than Alloy or wants to compare options. Check that every push sends the X-Scope-OrgID header when auth_enabled is true, and confirm that an authenticating reverse proxy sits in front of Loki, since Loki does not provide authentication itself.

Promtail end-of-life documentation

Input: your current Promtail deployments and their versions. Output: the migration direction in Grafana's Promtail documentation. Promtail reached end of life on March 2, 2026, receives no further updates or commercial support, and Grafana directs users to Grafana Alloy. Inventory every host and cluster still running Promtail, assign a replacement date for each environment, and record the lack of security updates as an open risk until each agent is replaced.

Manual review of converter gaps

Input: the converter output compared line by line with the original Promtail file. Output: a written list of settings the converter did not carry over or that need a different Alloy form. The documentation available to this review does not confirm that alloy convert covers every pipeline stage or handles positions files, so treat both as open items until tested. Check each pipeline stage in the Promtail file, confirm where read offsets will be stored after cutover, and test each gap on a non-production host.

What Alloy convert cannot carry over and how to find the gaps

Treat the output of alloy convert as a draft. The converter translates the Promtail settings it can map, but it does not confirm that the result behaves like the original, and it does not list what it skipped. On every host, diff the converted Alloy configuration against the Promtail file it came from, line by line, and keep both versions in source control so the comparison can be repeated. Run this for each host, not once per fleet, because hosts often carry local edits, different file paths or host-specific labels that one reviewed copy will not reveal. Record each difference as carried over, changed on purpose or missing. The converted file is not ready for rollout until every difference has one of those three labels.

Start with the pipeline stages. Any Promtail stage without a direct equivalent in Alloy's log processing components needs either a written replacement or an explicit decision to drop it. Confirm each mapping against the Alloy component reference for the version you deploy. Next, list every relabeling rule and every label it creates or removes. Labels define the streams that Loki indexes and queries, so a dropped or renamed label changes what dashboards and alert rules match. Note which dashboards and alerts depend on each label. Also check regex anchoring and replacement behavior in each rule, since small differences there can change label values without any visible error.

Next, review file discovery. The scrape paths, glob patterns, exclusion rules and file-watching behavior in the Promtail scrape configuration must match what Alloy discovers on each host, or logs will be missed or duplicated. Compare the discovered file list on a test host with the Promtail list from the same host. Then check tenancy. When auth_enabled is true in Loki, each request must carry the X-Scope-OrgID header. The Promtail setting that controls the tenant may be expressed differently in Alloy, so confirm which tenant each host writes to and that the value matches what your Loki and authentication layer expect. Confirm the tenancy behavior in the Loki multi-tenancy documentation before you rely on it.

Finally, look for secrets and templated values. Promtail configurations often hold basic auth passwords, bearer tokens, or paths to client certificates for the Loki push URL. Some also use environment variable substitution or host-specific templating that the converter may copy literally or drop. Move credentials into the secret mechanism your platform already uses, and confirm that Alloy resolves each reference on every host before rollout. Do not leave plaintext secrets in the converted file. Check that the user running the Alloy process can read every certificate and token file it references, because a permissions failure often appears only after the service restarts.

Write one gap list per configuration file. Each entry should name the original Promtail setting, the converted Alloy equivalent, its status and the person who will test it. Confirm every entry against the Alloy documentation for your deployed version, and record that version in the list. Items still open after review should block rollout for the host group they affect. If an implementation partner is involved, ask for this list as a written deliverable within the agreed scope, because on-call engineers will rely on it when they troubleshoot log gaps after cutover.

The migration sequence from inventory to Promtail decommission

The sequence moves each Promtail host and Kubernetes DaemonSet to Grafana Alloy in controlled stages, so log arrival is verified before any agent is removed. Each stage has a named owner on the client side and a written exit check. Promtail is decommissioned only after the parallel run and the rollback path are signed off.

Inventory every Promtail host and DaemonSet
DeployOpen lists every virtual machine, bare-metal host, container node and Kubernetes DaemonSet running Promtail, along with its configuration file, positions file location, scrape targets, pipeline stages and the Loki streams it feeds. The client team provides read access to hosts and clusters and names the owners of the dashboards and alerts that depend on those streams. The step is complete when each agent has a row in the inventory, the client team has signed it off, and no unknown Promtail instances remain.
Convert and review configurations with alloy convert
Each Promtail configuration is run through alloy convert, and the output is reviewed line by line against the original. The review records what the converter could not carry over, such as options without a direct equivalent or custom pipeline logic, and each manual rewrite is documented. The plan for positions also gets checked here, so Alloy resumes reading from the correct offsets without skipping or duplicating lines. The client engineer approves the reviewed configurations and the manual change list before any deployment.
Pilot Alloy on non-production hosts
DeployOpen deploys Alloy with the converted configuration to a small set of non-production hosts that cover the main operating systems and workload types in the estate. Pilot checks compare the labels, log content and timestamps in Loki with what the original Promtail configuration produced, and they include a restart and a log rotation test. The client team provides a non-production change window, host access and the queries it uses to judge results. The step closes when the pilot results match the expected output and the client team accepts them in writing.
Run Alloy and Promtail in parallel
Alloy and Promtail ship logs from the same hosts for a period agreed with the client, so arrival can be compared stream by stream. Because both agents send the same lines, the comparison must use a label, stream selector or tenant that separates the two sets, and this approach should be confirmed for the environment before the run starts. Alloy also exposes its own metrics, and some names used by dashboards and alerts may differ, so the metric mapping is updated during this stage. Dashboard owners sign off once every gap has an explanation.
Cut over host group by host group
Promtail is stopped and Alloy becomes the only shipper one host group at a time, with each group moved in its own change window. After each cutover, the team checks that every expected stream arrives in Loki and that dashboards and alerts respond. The rollback path, which restarts Promtail with its original configuration and retained positions file, is tested on at least one group before the wider cutover proceeds. The client team supplies change windows, on-call contacts and a decision owner for each group, and the step closes when every group has verified arrival.
Decommission Promtail after sign-off
Promtail is removed only after the parallel run and the rollback path have been signed off in writing. The work removes Promtail packages, service units and DaemonSets, archives its configuration according to the client's retention policy, and retires any dashboards built only for Promtail. Runbooks and the host inventory are updated to show Alloy as the shipper. Promtail reached end of life on March 2, 2026, with no further updates, so leaving it in place also leaves an unpatched agent running. The step is complete when no Promtail process or DaemonSet remains and the client team accepts the handover documents.

Staging the rollout across Linux hosts and Kubernetes

Host-based installs usually run Promtail as a systemd service on each machine, so the cutover is a per-host change to the service unit, file access and position tracking. Treat each host as a unit of work: install Alloy with the converted configuration, confirm it can read every path in scope, then stop Promtail. Keep the Promtail unit and its configuration on disk until the wave passes, so rollback is a service restart.

Service units: Run Alloy under a dedicated service account with a unit file managed by your configuration tooling. Disable the Promtail unit at the cutover step and leave the package installed so the old agent can be restarted.
Log path access: Grant the Alloy account read access to each log path through group membership or ACLs. Verify access while logged in as that account, since a test run as root proves little about the service.
Positions file: Promtail records read offsets per file. Decide whether Alloy resumes from those offsets, which avoids gaps but can replay old lines, or starts at the end of each file, which avoids replay but drops lines written during the switch. Confirm the behavior on a test host first.
Journal and rotation: If hosts ship from the systemd journal, confirm the Alloy account can read it. Test rotation on a sample file to confirm Alloy follows the new file.
Configuration delivery: Push the converted file through the pipeline that delivers Promtail configuration so drift between hosts stays visible.

Before starting the next wave, confirm that every host in the current wave shows recent lines in Loki and that its Promtail unit is stopped.

What drives the cost and duration of a Promtail to Alloy migration

This table lists the factors that change the effort of a Promtail to Grafana Alloy migration, who usually carries each piece of work, and what to request in a written quote. Use it to scope your own estate before asking for a fixed-scope proposal. The main takeaway is that configuration variety and the number of dashboards and alerts often matter as much as host count.

Driver	Why it changes effort	Who carries the work	Ask for in the written quote
Number of hosts and clusters	Each host needs a converted config, a deployed Alloy instance, a positions check and a rollback path. Kubernetes clusters add their own rollout steps.	Both: partner plans and automates rollout, client runs change control	Per-host and per-cluster rollout steps and which environments are included
Distinct Promtail configurations	Each unique scrape config, job and pipeline needs review after alloy convert, so variety multiplies checking work.	Partner converts and reviews; client confirms log sources and owners	Count of unique configurations and whether conversion output is reviewed for each one
Pipeline stages and relabeling	Stages and relabel rules the converter cannot carry over must be rewritten by hand and tested against sample logs.	Partner rewrites and tests; client validates expected labels and log content	Named list of unsupported stages and the rewrite and test method for each
Dashboards and alerts reading changed metrics	Queries and alert rules that depend on metric names or labels from the agent must be mapped and updated before cutover.	Client owns dashboards and alerts; partner supplies the metric mapping	Inventory of affected dashboards and alert rules and who updates each one
Positions files	Positions must be carried over or reset on purpose so logs are neither duplicated nor missed during cutover.	Partner designs the approach; client accepts duplicate and gap tolerance	Positions handling method per host and the checks used to detect gaps and duplicates
Change-window constraints	Limited change windows, freeze periods and approval cycles force smaller batches and a longer rollout calendar.	Client sets windows and approvals; partner shapes batches to fit them	Batch plan mapped to your windows and the fallback if a window is missed
Parallel run validation	Running Promtail and Alloy side by side needs its own comparison of log counts, labels and query results before retirement.	Both: partner defines checks, client confirms acceptance criteria	Whether the parallel run is in scope, the comparison method and the exit criteria

What usually goes wrong during a Promtail to Alloy cutover

Most cutover problems come from overlap, state and identity: two agents reading the same files, offsets that stay behind, labels and tenants that change in transit, and Kubernetes manifests that miss host access. Each risk below has a check to run during the parallel run, before Promtail is stopped on any host.

Lost or duplicated log lines

While Promtail and Alloy both run on the same host, each may ship the same file, or one may stop before the other picks up. Both outcomes distort counts, alerts and incident timelines. During the parallel run, compare line counts for a sample of streams in Grafana between the old and new pipelines across a full business cycle, and confirm each stream arrives from exactly one agent after cutover. Record the Promtail stop step in the change record so the handover is explicit and reversible.

Positions state that does not carry over

Promtail records how far it has read each file in a positions file. Do not assume Alloy reads that file. A converted configuration may start from its own state, so a new agent can re-read old files and duplicate lines, or start at the end of files and leave gaps. Before cutover, confirm with the converted configuration how existing files are handled, record current read offsets where the tooling allows, and check a rotated file for duplicated or missing lines during the parallel run.

Label changes that break queries

Converted pipelines can rename labels, change label values, or attach a different set of labels to a stream. Any dashboard panel, alert rule or saved LogQL query that selects on the old labels then returns empty results or the wrong series. Inventory every query and alert in use, map each old label to its new name, and run both sets of queries side by side during the parallel run. Treat any empty panel as a failed check before the old agent is stopped.

Tenant headers dropped in conversion

When multi-tenancy is enabled in Loki, every request identifies its tenant with the X-Scope-OrgID header. If a converted pipeline does not set the tenant on each write, logs can land in the wrong tenant or be rejected. Check the converted output for the tenant setting on every destination, send a test line for each tenant, and confirm it is queryable only under the intended tenant. Also verify that the authenticating reverse proxy in front of Loki passes the header through unchanged.

DaemonSets missing host mounts

On Kubernetes, log agents usually run as a DaemonSet and read container log files from host paths. A converted manifest that omits those volume mounts, or the security context that grants read access to them, can deploy cleanly and ship nothing. Compare the Alloy DaemonSet against the Promtail manifest, confirm log files are readable on every node pool including tainted nodes, and check that logs from newly scheduled pods reach Loki during the parallel run.

Positions files and changed metrics that break dashboards

The positions decision comes first, because it determines whether logs are duplicated or missing at cutover. Promtail records how far it has read each tailed file in a positions file and resumes from those offsets after a restart. Alloy keeps its own read offsets in its own state, and the converter does not move Promtail's positions into that state for you. Confirm in the Alloy documentation for your version where offsets are stored and whether the location is configurable. You then have three options. You can carry the offsets over, which avoids both gaps and duplicates but depends on the file format and path matching between the two agents. You can rebuild, which starts Alloy from the current end of each file and loses any lines written during the gap. You can accept a controlled re-read, which sends some lines twice and inflates volume and counts for that window. Choose per log source, stop Promtail before you capture offsets, and record the gap for each file.

Dashboards and alerts are the second risk, and they fail quietly. Any panel, recording rule, alert rule or exported report that reads metrics emitted by the agent will show no data after the switch if its metric names or labels changed, and nothing in the logs will say so. Build a complete inventory before decommissioning Promtail. Search Grafana dashboard JSON, provisioning files, Prometheus rule files, and any external reporting jobs for the Promtail metric prefix and for any job or instance label values that identify Promtail targets. Record the owner of each item and whether it is a panel, a rule or a report. The inventory is a deliverable you can ask a partner to produce as part of a fixed-scope engagement, but your own team should confirm it against the live Grafana instance.

Next, compare metric names and labels between the two agents in your own environment. During the overlap period, scrape both agents' metrics endpoints and save the raw output from each. Build a mapping table with the old name, the new name, the type, and every label that was added, renamed or removed. Pay attention to counters and gauges, since a changed type can break rate and increase functions even when the name looks similar. Check label cardinality too, because a new label can multiply series counts. Do not rely on memory or on a summary copied from a migration guide. Confirm exact metric names against the Alloy documentation for your version and against your own scrape output, then update each query and test it against data from the overlap window.

Before you decommission Promtail, set a clear gate. Every item in the inventory should reference only the new metrics, and each alert that depends on the agent should fire correctly in a controlled test. Add an alert that triggers when the new agent's metrics are absent for a host or cluster, so a future break is caught by monitoring rather than by a user noticing an empty panel. Agree with dashboard and alert owners how long the old dashboards stay available in read-only form, and record who signs off. Ask any implementation partner to show how the inventory, mapping table and gate evidence will be delivered, and confirm who maintains those documents after handover.

Questions buyers ask before migrating Promtail to Alloy

How much does a Promtail to Grafana Alloy migration cost?

Cost follows the written scope, and DeployOpen does not publish a price list. The main drivers are the number of hosts and Kubernetes clusters, how many distinct Promtail configurations exist, how complex the pipeline stages and relabeling rules are, how many dashboards and alerts depend on existing metric names, and how many change approvals the rollout needs. The one-time work covers inventory, conversion, manual rewrites, testing, the parallel run, cutover and documentation. Recurring cost appears only if you add a retainer for ongoing support or upgrades. When you ask for a quote, request it broken down by phase, with the assumptions about host count, configuration complexity and change windows stated. Also ask which tasks your team carries, so you can compare the quote with your own effort.

How long does a Promtail migration take across our hosts?

Duration varies with inventory size and change windows, so no single figure applies to every fleet. A small set of hosts with similar configurations can move in a few passes, while a large, mixed fleet needs grouping by configuration type and by the maintenance windows each team allows. Most of the calendar time usually goes to approvals and the parallel run, not to the conversion itself. Ask for a timeline that lists the inventory step, the number of rollout waves, the parallel-run period and the dates your change board has agreed. A timeline tied to your change calendar is more useful than a generic estimate, because it shows where delays are likely and who must act on them.

What does our team need to provide during a migration?

The migration depends on several inputs that only your organization can supply. Expect to provide:

Host access: administrative access to the machines or cluster namespaces where Promtail runs, plus a way to deploy Alloy.
Dashboard owners: named people who confirm which Grafana panels and alert rules matter and who sign off on updated queries.
Change approvals: a change board or on-call owner who approves each rollout wave and the rollback steps.
Loki details: the push endpoint, tenant identifiers if multi-tenancy is enabled, and the labels your teams query on.
Config ownership: someone who knows why each Promtail configuration exists, including custom pipeline stages.

If these owners are unavailable during the planned windows, the schedule will move, so confirm them before the quote is final.

Can our own team migrate from Promtail to Alloy without a partner?

Yes, a team can migrate itself when the fleet is small and the Promtail configurations are simple, such as a few hosts with standard scrape configs and no complex pipeline logic. The team should start with the alloy convert command, review every output line and test each converted file in a non-production environment. The parallel run still applies: Promtail and Alloy must ship the same logs for a period so you can compare line counts, confirm that positions are handled without gaps or duplicates, and check that dashboards return matching results. Teams should not treat the parallel run as optional. If the configurations include custom regex stages, multiline handling or Kubernetes discovery with unusual relabeling, a partner review of the converted output usually saves rework.

Does migrating our agents change the Loki server or its stored logs?

Migrating the agents does not change Loki itself. Loki keeps running with the same storage, retention settings and tenant model, and it continues to receive logs over the same push interface, now from Alloy instead of Promtail. The points to check are labels and tenant headers. If the converted Alloy configuration assigns labels differently from Promtail, queries that filter on those labels will return different results for logs ingested after cutover, so label mapping must be reviewed before rollout. Upgrades to the Loki server are a separate project with their own schema, storage and configuration steps, and they are covered in the Loki upgrades work rather than in this migration. Ask the provider to confirm how the scope separates the two.

What does alloy convert not carry over from Promtail configurations?

The converter translates many common Promtail constructs, but it does not guarantee full coverage of every configuration. Expect manual work for custom or unusual pipeline stages, complex relabeling, multiline or regex logic that depends on Promtail-specific behavior, and any option that has no direct Alloy equivalent. Positions file handling also needs attention, because the file on each host records how far Promtail has read, and the migration must avoid re-shipping or skipping log lines when Alloy takes over. Before relying on the output, run the converter against a copy of each configuration, diff the results and check every warning. Confirm the current converter's coverage against your own files in a test, since converter behavior changes between releases.

Will our dashboards and alerts break after moving to Alloy?

They can, because Alloy exposes its own internal metrics, and some metric names and label sets differ from those Promtail produced. Any dashboard or alert that charts or fires on Promtail's internal metrics needs to be found, mapped to the Alloy equivalent and tested before cutover. Start by listing every panel and rule that references Promtail metrics, including those in shared dashboards that other teams own. Then assign an owner for each one, update the queries in a staging Grafana instance and compare results during the parallel run. Log queries against Loki may also change if label names change during conversion. Keep the old dashboards available until the new ones have matched output for an agreed period, so you have a clear fallback.

How DeployOpen scopes, delivers and supports a Promtail to Alloy migration

DeployOpen scopes the move from Promtail to Grafana Alloy as a fixed-scope engagement, with deliverables and timelines agreed in writing before work starts. Promtail reached end of life on March 2, 2026, so the work covers every host and Kubernetes cluster that ships logs to the Loki deployment you run in infrastructure you control. Ongoing support after cutover is available as a retainer.

How we scope

The written scope lists every host group and Kubernetes cluster that currently runs Promtail agents.
Scope records each Promtail configuration, positions file location and the Loki labels that dashboards and alerts depend on.
The quote should list the converter gaps and the manual work to close each one separately.

How we build

Configurations are converted with alloy convert, then each output is reviewed by hand against the original Promtail file.
Pipeline stages the converter cannot carry over are rebuilt and tested against sample log lines from each source.
Dashboards and alert rules are checked for metric names that changed in Alloy, with updates documented.

How we hand over

Hosts and Kubernetes clusters move in waves, and each wave is checked against Loki ingestion before the next.
Runbooks cover rollback to the old agent, positions file handling and where Alloy's own logs and metrics are found.
Handover includes the converted configuration repository, change record and a list of retired Promtail hosts.

How we support

Promtail's end of life on March 2, 2026 means no further updates or commercial support for the old agent.
Post-cutover support is available as a retainer covering Alloy upgrades, configuration changes and log pipeline fixes.
Ask whether the retainer covers Loki upgrades, which follow a separate upgrade guide and are scoped separately.