Alloy
Grafana LabsOfficialPublished by Grafana Labs
- Skill
- Tool integration
- Cloud and DevOps
- Apache-2.0
- Low risk
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
Grafana Alloy is an OpenTelemetry-compatible collector that uses a unified configuration language to build telemetry pipelines. This skill provides guidance on using the Alloy CLI, configuring components for data collection and shipping, and managing pipelines for metrics, logs, traces, and profiles. It covers the Alloy configuration syntax, component discovery, relabeling, and integration with backends like Grafana Cloud, Prometheus, Loki, Tempo, and Pyroscope.
What it does
- Provides syntax and structure for config.alloy files using blocks and component references.
- Explains how to use discovery components for Kubernetes, Docker, and cloud infrastructure.
- Details the configuration of exporters and receivers for metrics, logs, and traces.
- Offers commands for validating and formatting configuration files.
- Describes how to use the Alloy UI to monitor component health and data flow.
- Covers advanced features like modules, clustering, and remote configuration management.
When to use it
- When setting up a telemetry pipeline to collect and ship observability data.
- When migrating from Grafana Agent or OpenTelemetry Collector to Alloy.
- When configuring scrape targets for Kubernetes pods or other infrastructure.
- When debugging issues with data ingestion or pipeline connectivity.
- When needing to transform or drop specific logs or metrics before they are shipped.
Advantages
- Unified binary for handling multiple telemetry signals.
- Native support for OpenTelemetry and Prometheus protocols.
- Built-in validation and formatting tools to ensure configuration correctness.
- Extensive component library for service discovery and data routing.
- Integrated web UI for inspecting component status and troubleshooting.
Usage examples
- “How do I set up a basic Prometheus scrape job in Alloy?”
- The agent provides a configuration block using prometheus.scrape to target an address and forward metrics to a remote_write component.
- “Help me debug why my Alloy logs aren't appearing in Loki.”
- The agent suggests checking the component health via the local UI at port 12345 and verifying the loki.source.file configuration.
- “How do I validate my config.alloy file?”
- The agent instructs to run the alloy validate command to perform a syntax check on the configuration file.
- “Write a configuration to receive OTLP traces and send them to Tempo.”
- The agent provides an otelcol.receiver.otlp block connected to an otelcol.exporter.otlp block with appropriate authentication.
Install
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/grafana/alloy/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip alloy.zip -d .agents/skills
Documentation by Grafana Labs
Grafana Alloy
OpenTelemetry-compatible collector — one binary for metrics + logs + traces + profiles.
Prerequisites
alloyCLI installed (brew install grafana/grafana/alloy,apt install alloy, orgrafana/alloyDocker image)An endpoint to ship to (Grafana Cloud, Prometheus, Loki, Tempo, Pyroscope)
API key + username for that endpoint, exported as
GRAFANA_API_KEYetc.
Common Workflows
1. Write + validate a config locally
// config.alloy — metrics → Grafana Cloud
prometheus.scrape "app" {
targets = [{"__address__" = "localhost:9090"}]
forward_to = [prometheus.remote_write.cloud.receiver]
scrape_interval = "30s"
}
prometheus.remote_write "cloud" {
endpoint {
url = sys.env("PROMETHEUS_URL")
basic_auth {
username = sys.env("PROM_USER")
password = sys.env("GRAFANA_API_KEY")
}
}
}# 1. Format + syntax-check (catches typos before run)
alloy fmt config.alloy
alloy validate config.alloy
# 2. Run it
alloy run config.alloy
# or as a service: systemctl restart alloy
# 3. Verify all components are healthy via the UI on port 12345
curl -s http://localhost:12345/api/v0/web/components \
| jq '.[] | select(.health.state != "healthy") | {id, state:.health.state, msg:.health.message}'
# Expect: empty (nothing unhealthy). Otherwise the row shows the failing component + reason.
# 4. Verify samples are flowing
curl -s http://localhost:12345/metrics \
| grep -E '^prometheus_remote_storage_(samples_total|enqueue_retries_total)' | head
# samples_total should be > 0 and rising; retries should be 0.2. Add log shipping (file → Loki)
loki.source.file "app_logs" {
targets = [{ __path__ = "/var/log/app/*.log", job = "app" }]
forward_to = [loki.write.cloud.receiver]
}
loki.write "cloud" {
endpoint {
url = sys.env("LOKI_URL")
basic_auth {
username = sys.env("LOKI_USER")
password = sys.env("GRAFANA_API_KEY")
}
}
}# Verify in Grafana → Explore → Loki:
# {job="app"}
# Expect lines streaming. If empty:
# - check /var/log/app/*.log actually exists + readable by the alloy user
# - http://localhost:12345 → loki.source.file.app_logs → "Targets" tab3. Receive OTLP traces and ship to Tempo
otelcol.receiver.otlp "default" {
grpc { endpoint = "0.0.0.0:4317" }
http { endpoint = "0.0.0.0:4318" }
output { traces = [otelcol.exporter.otlp.tempo.input] }
}
otelcol.exporter.otlp "tempo" {
client {
endpoint = "tempo-xxx.grafana.net/tempo:443"
auth = otelcol.auth.basic.grafana_cloud.handler
}
}
otelcol.auth.basic "grafana_cloud" {
username = sys.env("TEMPO_USER")
password = sys.env("GRAFANA_API_KEY")
}# Verify in Grafana → Explore → Tempo → service.name = your-service
# At the Alloy level, watch the receiver:
curl -s http://localhost:12345/metrics | grep otelcol_receiver_accepted_spansFull pattern set (Kubernetes discovery + relabel, complete Cloud pipeline for all 4 signals): references/collection-patterns.md.
Reference
references/config-syntax.md— block/attribute/expression grammar,import.*,remotecfg, clusteringreferences/components.md— full component catalog with purpose + typical argsreferences/collection-patterns.md— end-to-end pipelines (K8s pods, OTLP, profiles, logs)
Troubleshooting
alloy validate→ "component not found" → version too old;alloy --versionand upgradeUI shows component
unhealthy→ click into it on http://localhost:12345 for the live errorprometheus_remote_storage_samples_dropped_totalrising → checkenqueue_retries_totaland the remote_write endpoint URL + credsNo spans landing in Tempo → check
otelcol_receiver_refused_spansand the exporter'sotelcol_exporter_sent_spans/otelcol_exporter_send_failed_spans
Resources
Files
- ATTRIBUTION.mdAdded by AutoGineer830 B
- LICENSELicence file added by AutoGineer11.1 KiB
- SKILL.md5.2 KiB
- references/collection-patterns.md10.7 KiB
- references/components.md16.2 KiB
- references/config-syntax.md9.2 KiB
references/components.md
Alloy Components Reference
Index of the most commonly used Alloy components, grouped by namespace. The canonical and complete reference is at https://grafana.com/docs/alloy/latest/reference/components/.
Alloy components are identified by a dotted namespace.name and configured via a labeled
block. Each component has typed arguments (what you set) and exports (what other components
consume — typically .receiver, .input, .targets, .output, .handler, or .content).
Discovery — find targets to scrape
Discovery components emit a targets export: an array of label maps consumed by prometheus.scrape,
loki.source.*, or pyroscope.scrape.
| Component | Purpose |
|---|---|
discovery.kubernetes | Pods, services, endpoints, nodes, ingresses via the K8s API |
discovery.docker | Containers from the Docker daemon |
discovery.dockerswarm | Tasks/services from a Docker Swarm |
discovery.ec2 | AWS EC2 instances |
discovery.gce | GCP Compute Engine instances |
discovery.azure | Azure VMs and scale sets |
discovery.dns | DNS SRV/A/AAAA records |
discovery.consul | Services registered in Consul |
discovery.nomad | Allocations in HashiCorp Nomad |
discovery.file | Targets from a JSON/YAML file (file_sd compatible) |
discovery.http | Targets from an HTTP endpoint (http_sd compatible) |
discovery.relabel | Apply relabeling rules to another component's targets |
discovery.process | Local process listing (used with Beyla / Pyroscope eBPF) |
discovery.kubernetes "pods" {
role = "pod"
}
discovery.relabel "pods" {
targets = discovery.kubernetes.pods.targets
rule {
source_labels = ["__meta_kubernetes_namespace"]
target_label = "namespace"
}
}Prometheus — metrics pipeline
| Component | Purpose |
|---|---|
prometheus.scrape | Pull /metrics from targets |
prometheus.remote_write | Write metrics via Prometheus remote-write protocol |
prometheus.relabel | Add/drop/rewrite labels on metric samples |
prometheus.operator.podmonitors | Scrape using Prometheus Operator PodMonitor CRDs |
prometheus.operator.servicemonitors | Scrape using ServiceMonitor CRDs |
prometheus.operator.probes | Use Probe CRDs |
prometheus.receive_http | Accept remote-write traffic (proxy / fan-out) |
prometheus.exporter.unix | Linux node metrics (node_exporter equivalent) |
prometheus.exporter.windows | Windows host metrics |
prometheus.exporter.mongodb | MongoDB metrics |
prometheus.exporter.mysql | MySQL metrics |
prometheus.exporter.postgres | PostgreSQL metrics |
prometheus.exporter.redis | Redis metrics |
prometheus.exporter.snmp | SNMP-based device metrics |
prometheus.exporter.blackbox | Blackbox probe (HTTP/TCP/ICMP) |
prometheus.exporter.cloudwatch | AWS CloudWatch metrics |
prometheus.exporter.kafka | Kafka metrics |
prometheus.exporter.process | Per-process metrics |
Inputs to scrape/relabel/remote_write chain via:
discovery.* → discovery.relabel → prometheus.scrape → prometheus.relabel → prometheus.remote_write
(.receiver)Loki — logs pipeline
| Component | Purpose |
|---|---|
loki.source.file | Tail log files (file_sd-style) |
local.file_match | Path globs that produce targets for loki.source.file |
loki.source.kubernetes | Tail Kubernetes container logs via API |
loki.source.kubernetes_events | Stream cluster events |
loki.source.journal | systemd journald |
loki.source.docker | Docker container logs |
loki.source.syslog | Listen for RFC5424/RFC3164 syslog |
loki.source.gcplog | GCP Pub/Sub logs |
loki.source.awsfirehose | AWS Kinesis Data Firehose |
loki.source.azure_event_hubs | Azure Event Hubs |
loki.source.cloudflare | Cloudflare logpush |
loki.source.api | Generic HTTP push endpoint |
loki.echo | Print received logs (debugging) |
loki.process | Pipeline stages: parse, label, drop, transform |
loki.relabel | Relabel without parsing |
loki.write | Push logs to Loki |
Pipeline shape:
discovery.* → loki.source.* → loki.process → loki.write
(.receiver)loki.process stages include stage.json, stage.logfmt, stage.regex, stage.labels,
stage.static_labels, stage.label_drop, stage.label_keep, stage.drop, stage.timestamp,
stage.output, stage.template, stage.multiline, stage.match, and stage.replace.
OpenTelemetry — otelcol.*
Receivers
| Component | Purpose |
|---|---|
otelcol.receiver.otlp | OTLP over gRPC (4317) and HTTP (4318) |
otelcol.receiver.jaeger | Jaeger gRPC/Thrift |
otelcol.receiver.zipkin | Zipkin HTTP |
otelcol.receiver.prometheus | Convert Prometheus scrape data into OTel metrics |
otelcol.receiver.loki | Convert Loki log data into OTel logs |
otelcol.receiver.kafka | Consume OTLP/JSON from Kafka |
otelcol.receiver.opencensus | OpenCensus protocol |
otelcol.receiver.vcenter | VMware vCenter |
otelcol.receiver.datadog | Datadog Agent traces/metrics |
Processors
| Component | Purpose |
|---|---|
otelcol.processor.batch | Batch signals before export |
otelcol.processor.memory_limiter | Drop data if memory exceeds threshold |
otelcol.processor.transform | OTTL-based transformation |
otelcol.processor.attributes | Insert/update/delete attributes |
otelcol.processor.resourcedetection | Add resource attributes (k8s/aws/gcp/azure) |
otelcol.processor.k8sattributes | Enrich with k8s metadata |
otelcol.processor.filter | Drop telemetry matching OTTL expressions |
otelcol.processor.tail_sampling | Trace tail sampling |
otelcol.processor.probabilistic_sampler | Head-based sampling |
otelcol.processor.span | Rename / extract attributes from span names |
otelcol.processor.deltatocumulative | Convert delta to cumulative temporality |
Exporters
| Component | Purpose |
|---|---|
otelcol.exporter.otlp | OTLP gRPC |
otelcol.exporter.otlphttp | OTLP HTTP |
otelcol.exporter.prometheus | Forward to prometheus.remote_write |
otelcol.exporter.loki | Forward to loki.write |
otelcol.exporter.loadbalancing | Distribute traces across endpoints (consistent hashing) |
otelcol.exporter.kafka | Kafka producer |
otelcol.exporter.debug | Log telemetry to stderr (debugging) |
otelcol.exporter.faro | Frontend Observability |
Auth and extensions
| Component | Purpose |
|---|---|
otelcol.auth.basic | HTTP basic auth handler for otelcol clients |
otelcol.auth.bearer | Bearer-token auth |
otelcol.auth.headers | Static header auth |
otelcol.auth.oauth2 | OAuth2 client credentials |
otelcol.auth.sigv4 | AWS SigV4 |
otelcol.connector.spanmetrics | Generate RED metrics from spans |
otelcol.connector.servicegraph | Build service-graph metrics from traces |
OTel pipeline shape:
otelcol.receiver.* → otelcol.processor.* → otelcol.exporter.*
(output{traces=, metrics=, logs=}) (.input)Pyroscope — profiles
| Component | Purpose |
|---|---|
pyroscope.scrape | Pull pprof endpoints from targets |
pyroscope.ebpf | eBPF-based whole-system profiling |
pyroscope.java | async-profiler integration for JVMs |
pyroscope.relabel | Relabel profile streams |
pyroscope.write | Send profiles to Pyroscope/Grafana Cloud Profiles |
pyroscope.receive_http | Accept push from other Pyroscope clients |
Beyla — eBPF auto-instrumentation
| Component | Purpose |
|---|---|
beyla.ebpf | Auto-generate traces/metrics from any process without code |
Faro — frontend telemetry
| Component | Purpose |
|---|---|
faro.receiver | Accept browser RUM payloads from the Faro Web SDK |
otelcol.exporter.faro | Forward OTel data to Grafana Cloud Frontend Observability |
Database observability
| Component | Purpose |
|---|---|
database_observability.mysql | Query Performance, EXPLAIN, slow-query parsing for MySQL |
database_observability.postgres | Same for PostgreSQL |
Mimir
| Component | Purpose |
|---|---|
mimir.rules.kubernetes | Sync PrometheusRule CRDs into Mimir ruler |
Local / remote helpers
| Component | Purpose |
|---|---|
local.file | Read a file, expose .content (watches for changes) |
local.file_match | Glob filesystem paths into targets |
remote.http | Fetch a URL, expose body as .content |
remote.s3 | Fetch an S3 object |
remote.kubernetes.configmap | Read a ConfigMap value |
remote.kubernetes.secret | Read a Secret value |
remote.vault | Read a HashiCorp Vault secret |
Imports / modules (top-level)
| Block | Purpose |
|---|---|
import.file | Pull declarations from a local file |
import.git | Pull from a Git repo |
import.http | Pull from an HTTP endpoint |
import.string | Inline declarations |
declare | Define a reusable custom component |
Quick reference — most common imports
prometheus.scrape // pull metrics
prometheus.remote_write // ship metrics
prometheus.relabel // filter/relabel metrics
loki.source.file // tail files
loki.source.kubernetes // tail pod logs
loki.process // parse/label/drop logs
loki.write // ship logs
otelcol.receiver.otlp // accept OTLP
otelcol.processor.batch // batch
otelcol.processor.memory_limiter // backpressure
otelcol.exporter.otlp // ship via gRPC
otelcol.exporter.otlphttp // ship via HTTPS
discovery.kubernetes // k8s SD
discovery.relabel // relabel targets
pyroscope.scrape // scrape pprof
pyroscope.write // ship profiles
beyla.ebpf // zero-code traces/metricsFor the full list and per-component arguments/exports, see https://grafana.com/docs/alloy/latest/reference/components/.
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Needs: Needs network access, Needs an API key
Security
What our scanner noticed· Low risk
- Instructions that use the network
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Published by
- Grafana Labs
- Publisher
- Grafana Labs (Official)
- Source
- grafana/skills · skills/grafana-core/alloy · commit 8fb72a5
- Licence
- Apache License 2.0 (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by Grafana Labs.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download alloy.zip