Guide to installing and configuring Grafana Alloy agents to discover, tail, batch, and ship host logs to Loki as the supported replacement for Promtail
We built the sorting center. Now we need the couriers.Picture a courier stationed at each building. Their whole job is to pick up the mail as it arrives and deliver it to the sorting center repeatedly, without anyone having to ask each time.
Your machines need the same thing.Loki is running, but it will remain empty until something sends logs to it. On each host, your applications write log files; you need an agent to watch those files and forward every new line to Loki as it appears.That role is fulfilled by Grafana Alloy.Alloy is a lightweight, host-level agent you install on every machine — like a courier at each building — which ships logs to Loki on your behalf. If you’ve used Promtail in older guides, note that Promtail has been deprecated; Grafana now recommends Alloy as the supported successor.
We will use Alloy for the rest of this lesson.How Alloy works (high level)
Alloy’s configuration is built from small, focused components. You connect these components into a pipeline so that the output of one is the input of the next.
Typical pipeline stages:
File discovery — find the log files to read (for example, everything under /var/log).
File tailing — follow files and emit each new line as it is written.
Batching and shipping — group entries and forward them to your Loki server endpoint.
Think of it as a conveyor belt: discovery feeds tailing, tailing feeds batching, and batching pushes into Loki.Table — Alloy pipeline components (overview)
Pipeline stage
Purpose
Example / Notes
File discovery
Locate files to ingest (paths, glob patterns)
Common paths: /var/log, application log directories
File tailing
Read files line-by-line and produce log entries
Handles rotated files and new data appended to files
Batching & shipping
Buffer entries and send them to Loki over HTTP
Sends to Loki push endpoint (e.g. https://loki.example.com/loki/api/v1/push)
Promtail — which you may see in older guides — is deprecated. Use Alloy as the supported replacement for tailing and shipping logs to Loki. For official docs and migration guidance, see the Grafana Alloy and Loki documentation.
Simple, conceptual example configurationThe exact syntax of Alloy configuration depends on the agent version and installer you use. The snippet below is a simplified conceptual example to illustrate the pipeline idea:
# Conceptual example only — check official docs for real syntaxcomponents: - type: file_discovery paths: - /var/log/*.log - /srv/app/logs/*.log - type: file_tailer follow: true encoding: utf-8 - type: loki_shipper url: "https://loki.example.com/loki/api/v1/push" batch: max_size: 1048576 timeout: 5s
Next steps
Install Alloy on each host you want to collect logs from.
Configure discovery patterns to include your application and system logs.
Point Alloy at your Loki instance (use the Loki push endpoint).
Test by generating log lines and verifying they appear in Loki / Grafana.
This establishes the courier pattern: lightweight agents on each host continuously collect and forward logs into the sorting center (Loki), so you can search, visualize, and alert on your logs centrally.
