Basics

• Grafana Alloy is an OpenTelemetry Collector distribution with Prometheus-compatible pipelines. It is the recommended successor to Grafana Agent (both Static and Flow modes) and Promtail. It can collect, transform, and forward metrics, logs, traces, and profiles in a single binary.
  • The configuration language is Alloy syntax — an HCL-inspired language that supports expressions, references between components, and a standard library. Config files use the .alloy extension.
• Alloy favors explicit configuration over implicit behavior. You define pipelines, routing, and scaling decisions in config rather than relying on automatic inference. This makes behavior predictable but means topology changes (e.g., DaemonSet → centralized) have visible effects.
• Alloy replaces the older Grafana Agent tooling and can migrate configs from Agent Static, Agent Flow, Promtail, and vanilla OpenTelemetry Collector (alloy convert command).
• Supported platforms: Linux, Windows, macOS, FreeBSD. Deployable as a binary, Docker container, DaemonSet, or via Helm.
• The HTTP server listens on 127.0.0.1:12345 by default. It exposes a debugging UI (visual component graph + live debugging), /metrics for Prometheus scraping, and /-/ready / /-/healthy health endpoints.
• Data durability: Alloy includes a Write-Ahead Log (WAL) for metrics. It buffers data locally and retries if the backend is unavailable. Configure persistent storage with -storage.path; without it, buffered data is lost on restart.
• Secrets can be injected via environment variables or external integrations: HashiCorp Vault (remote.vault), Kubernetes Secrets (remote.kubernetes.secret), AWS S3 (remote.s3), and local files (local.file).

Architecture

Components

Components are the core building block of Alloy. Each component performs a single task (collect, transform, forward) and has two parts:

• Arguments — settings you configure in the component block.
• Exports — values the running component produces and makes available to other components. These can change over time (e.g., a file watcher exports updated content as the file changes).

Component naming follows the pattern NAMESPACE.TYPE (e.g., prometheus.scrape, loki.write). You identify a specific instance by combining name + label: prometheus.scrape.my_scraper.

// Component syntax:
COMPONENT_NAME "LABEL" {
  attribute = "value"
}

// Example: scrape and forward metrics
prometheus.scrape "app" {
  targets    = [{"__address__" = "localhost:8080"}]
  forward_to = [prometheus.remote_write.prod.receiver]
}

prometheus.remote_write "prod" {
  endpoint {
    url = "https://prometheus.example.com/api/v1/write"
  }
}

Component categories (by namespace prefix):