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://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
ATTRIBUTION.md
Attribution
This folder is an unmodified copy of the Agent Skill "alloy", distributed by AutoGineer (https://autogineer.com/agent-skills).
Commit: 8fb72a527961f05e708f53d2a0500709e12d7970
Published by: Grafana Labs (https://github.com/grafana)
Publisher: Grafana Labs (https://github.com/grafana)
Licence: Apache License 2.0 (https://spdx.org/licenses/Apache-2.0.html)
Licence evidence: declared in the frontmatter ("license: Apache-2.0")
Retrieved: 2026-11-07
The skill's own files are unmodified copies. AutoGineer is not affiliated with or endorsed by the author or the publisher.
Files added by AutoGineer
ATTRIBUTION.md: this file, written by AutoGineer
LICENSE: copied from LICENSE
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 or Grafana Labs.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download alloy.zip