Promtail is now considered legacy and is being replaced by Grafana Alloy as the default log collector for Loki. This means no new features and limited fixes going forward, so staying on Promtail increases your long‑term maintenance and security risk. When you migrate Promtail to Grafana Alloy, you align with the current Loki ecosystem and avoid a last‑minute migration when something finally breaks.

For a clean place to run Loki and Alloy, you can start with a reliable VPS server that is optimized for always‑on services and monitoring workloads.

Migration Plan Overview

This tutorial focuses on migrating a host‑based Promtail service, for example, a systemd unit on a Linux server, to a host‑based Grafana Alloy service. If you want to run Loki and Grafana Alloy as Docker containers, you can check this guide on Centralized Docker Logging with Grafana Alloy and Loki.

Before you migrate Promtail to Grafana Alloy, it helps to define a simple plan:

1. Inventory Promtail usage

• Where is Promtail running: systemd, sidecar, or Kubernetes DaemonSet?
• Which log sources do you tail? files under /var/log, app logs, or journald?

2. Choose migration style

• In‑place: install Alloy on the same host where Promtail runs.
• New host: Run a new server, then switch agents once you trust the new setup.

3. Define success

• Same log volume in Loki.
• Same or better labels.
• No gaps during the migration window.

Later, you will use the official convert tool to migrate Promtail to Grafana Alloy configuration without rewriting everything manually.

Back up the Existing Promtail Config

The first step to migrate Promtail to Grafana Alloy is to back up your Promtail configuration file. On many Linux systems, the config is located at:

• /etc/promtail/config.yml
• /etc/loki/promtail.yaml

Backup and check with the commands below:

sudo cp /etc/promtail/config.yml /etc/promtail/config.yml.bak
sudo sed -n '1,120p' /etc/promtail/config.yml

When you plan to migrate Promtail to Grafana Alloy, pay attention to:

• server: listen address and port.
• clients: Loki endpoints and credentials.
• scrape_configs: file paths, labels, and relabel rules.

Install Grafana Alloy on Linux

To migrate Promtail to Grafana Alloy safely, you should be able to run both agents side by side during testing. Start by installing Alloy on the host.

Example installation for Debian and Ubuntu:

curl -L "https://github.com/grafana/alloy/releases/latest/download/alloy-linux-amd64" -o /usr/local/bin/alloy
sudo chmod +x /usr/local/bin/alloy

sudo useradd --no-create-home --system --shell /usr/sbin/nologin alloy
sudo mkdir -p /etc/alloy

Create a simple systemd unit file:

cat << 'EOF' | sudo tee /etc/systemd/system/alloy.service
[Unit]
Description=Grafana Alloy
After=network-online.target

[Service]
User=alloy
Group=alloy
ExecStart=/usr/local/bin/alloy run /etc/alloy/config.alloy
Restart=always
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload

You are now ready to migrate Promtail to Grafana Alloy using the built‑in config converter.

Use the Grafana Alloy Converter to Migrate Promtail Configuration

Grafana Alloy includes a convert command that can read your Promtail config and output an Alloy config file. To do this, you can run:

sudo alloy convert \
  --source-format=promtail \
  --output=/etc/alloy/config.alloy \
  /etc/promtail/config.yml

What this does when you migrate Promtail to Grafana Alloy:

• Use --source-format=promtail to treat the input as Promtail YAML.
• Write an Alloy configuration in HCL‑style syntax to /etc/alloy/config.alloy.
• Translate scrape_configs and clients into loki.source.*, loki.process, and loki.write blocks.

Then, you can check the new config:

sudo sed -n '1,120p' /etc/alloy/config.alloy

Understand the Alloy Logging Pipeline

To adjust the config after you migrate Promtail to Grafana Alloy, you need to understand the basic Alloy pipeline structure.

Typical Alloy layout:

• loki.source.*: where logs come from, files, journald, Kubernetes, etc.
• loki.process: parsing and relabeling stages, similar to Promtail pipeline_stages.
• loki.write: where logs are sent, with Loki endpoint and auth configuration.

Example pattern:

loki.source.file "local_logs" {
  targets = [{
    __path__ = "/var/log/*.log",
    job      = "system-logs",
  }]
  forward_to = [loki.process.main.receiver]
}

loki.process "main" {
  stage {
    # stages generated from Promtail pipeline_stages
  }
  forward_to = [loki.write.out.receiver]
}

loki.write "out" {
  endpoint {
    url = "http://loki:3100/loki/api/v1/push"
  }
}

Adjust Log Paths and Label Mapping

The converter will do most of the job, but it is common to adjust file paths and labels manually.

Check file targets: You must make sure the path in loki.source.file matches the paths from your Promtail scrape_configs. Verify all important log directories are still included.

Check labels: In Promtail, labels were set with static_configs.labels and relabel_configs. In Alloy, those become parts of loki.process stages, and you want to keep key labels like job, host, and env the same where possible.

Structured metadata: If you do a lot of structured searches, you can enable or tune structured log handling in Alloy, which is helpful in high‑volume setups.

Run Alloy Alongside Promtail

To avoid downtime when you migrate Promtail to Grafana Alloy, you can run both agents in parallel for a while.

Start Alloy:

sudo systemctl enable --now alloy
sudo systemctl status alloy

Check its logs:

journalctl -u alloy -n 50 --no-pager

Leave Promtail running for this test period so you can compare and be sure there are no gaps or major label differences.

Verify Loki Receives Logs Correctly

Now you must confirm that the choice to migrate Promtail to Grafana Alloy did not stop logs from reaching Loki. In Grafana:

1. Open Explore and pick your Loki data source.
2. Run a query such as {job="system-logs"} or whatever label you use for the node.
3. Confirm:
   • New log lines keep appearing while Alloy is running.
   • Labels look as expected and match or improve on the old Promtail labels.

If you monitor log rate metrics, compare counts before and after migration so you can spot any large drop.

Disable Promtail and Run Only Alloy

Once you are satisfied with how Alloy works, you can complete the move by shutting down Promtail.

On the host, run:

sudo systemctl stop promtail
sudo systemctl disable promtail

ps aux | grep promtail

Keep Alloy running:

sudo systemctl restart alloy
sudo systemctl status alloy

Watch Loki and Grafana for a while:

• Verify that logs still arrive in real time.
• Confirm that dashboards and alerts based on logs still behave as expected.

If your log volume has grown a lot, this might also be a good time to move Loki and Grafana Alloy to a more powerful dedicated server and keep only agents on smaller nodes.

How to Roll Back Safely

If something goes wrong after the migration, you should be able to quickly return to your old setup without losing logs. A clear rollback path gives you the freedom to test Alloy in production while still having Promtail ready as a backup.

If you notice missing logs or serious label issues, you can re-enable Promtail:

sudo systemctl enable --now promtail
sudo systemctl status promtail

Then, stop the Alloy:

sudo systemctl stop alloy

To fix the configuration, you must compare /etc/promtail/config.yml with /etc/alloy/config.alloy for the problematic targets and adjust file paths, labels, or processing stages in Alloy.

Finally, run Alloy alongside Promtail again.

Mistakes to Avoid in Your Migration

Even with a good plan, it is easy to miss small details when you move from Promtail to Alloy. Knowing the most common mistakes helps you avoid downtime and saves time when you debug the migration.

• Skipping the backup of the original Promtail config.
• Missing one or more log paths in the new loki.source.file targets.
• Forgetting to copy TLS or auth settings, which causes Alloy to fail writes to Loki.
• Losing important labels because the relabel rules changed too much.
• Turning off Promtail before validating Alloy in Grafana Explore.

Avoiding these issues makes it much safer to migrate Promtail to Grafana Alloy in production.

Troubleshooting Tips after Migration

If logs stop showing up or labels look wrong after the migration, a few quick checks can usually tell you what went wrong.

Check Alloy service logs:

journalctl -u alloy -n 100 --no-pager

Validate configuration: If available in your Alloy version, use the config checker:

sudo alloy check-config /etc/alloy/config.alloy

This helps find syntax errors that might have slipped in after editing the file you used to migrate Promtail to Grafana Alloy.

Confirm Loki endpoint:

• In the loki.write block, verify the URL is correct and has /loki/api/v1/push.
• For Grafana Cloud, copy the exact URL and token format from the official Alloy log collection docs.

Use metrics and labels: If you scrape Alloy metrics, compare the log line rate before and after migration so you can catch quiet failures quickly.

For more detailed information on migration, you can check the official Promtail migration to Alloy docs.

Conclusion

Migrating from Promtail to Grafana Alloy can be easy by backing up your old config, using the official converter, running both agents in parallel, and checking Loki carefully before the final move. You can change the log collector without interrupting log flow or breaking your dashboards.

We hope you enjoy this guide.

FAQs