Generated banner for Alloy
Generated logo for Alloy

Alloy

Grafana LabsOfficialPublished by Grafana Labs

  • Skill
  • Tool integration
  • Cloud and DevOps
  • Apache-2.0
  • Low risk

From the author

Build a unified telemetry pipeline with Grafana Alloy — one OpenTelemetry-compatible binary that collects metrics, logs, traces, and profiles and ships to Grafana Cloud / Prometheus / Loki / Tempo / Pyroscope. Covers the Alloy config language (blocks, `sys.env`, component refs), `prometheus.scrape` → `remote_write`, `loki.source.file` + `loki.process` → `loki.write`, `otelcol.receiver.otlp` → `otelcol.exporter.otlp`, `pyroscope.scrape`, K8s / Docker / EC2 discovery, relabeling, modules (`import.file/git/http`), clustering, Fleet Management `remotecfg`, the Alloy UI at `:12345`, and `alloy fmt` / `alloy validate`. Use when writing a `config.alloy`, replacing Grafana Agent / OTel Collector, scraping K8s pods, parsing logs, ingesting OTLP, or debugging "Alloy isn't sending anything" — even when the user says "set up the agent", "write me a scrape config", "drop these logs before sending", or "OTel collector config" without naming Alloy.
— the description by Grafana Labs

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

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/grafana/alloy/download
  2. Unzip 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

Docs: https://grafana.com/docs/alloy/latest/

OpenTelemetry-compatible collector — one binary for metrics + logs + traces + profiles.

Prerequisites

  • alloy CLI installed (brew install grafana/grafana/alloy, apt install alloy, or grafana/alloy Docker image)

  • An endpoint to ship to (Grafana Cloud, Prometheus, Loki, Tempo, Pyroscope)

  • API key + username for that endpoint, exported as GRAFANA_API_KEY etc.

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" tab
3. 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_spans

Full pattern set (Kubernetes discovery + relabel, complete Cloud pipeline for all 4 signals): references/collection-patterns.md.

Reference

Troubleshooting

  • alloy validate → "component not found" → version too old; alloy --version and upgrade

  • UI shows component unhealthy → click into it on http://localhost:12345 for the live error

  • prometheus_remote_storage_samples_dropped_total rising → check enqueue_retries_total and the remote_write endpoint URL + creds

  • No spans landing in Tempo → check otelcol_receiver_refused_spans and the exporter's otelcol_exporter_sent_spans / otelcol_exporter_send_failed_spans

Resources

Files

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.

ComponentPurpose
discovery.kubernetesPods, services, endpoints, nodes, ingresses via the K8s API
discovery.dockerContainers from the Docker daemon
discovery.dockerswarmTasks/services from a Docker Swarm
discovery.ec2AWS EC2 instances
discovery.gceGCP Compute Engine instances
discovery.azureAzure VMs and scale sets
discovery.dnsDNS SRV/A/AAAA records
discovery.consulServices registered in Consul
discovery.nomadAllocations in HashiCorp Nomad
discovery.fileTargets from a JSON/YAML file (file_sd compatible)
discovery.httpTargets from an HTTP endpoint (http_sd compatible)
discovery.relabelApply relabeling rules to another component's targets
discovery.processLocal 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

ComponentPurpose
prometheus.scrapePull /metrics from targets
prometheus.remote_writeWrite metrics via Prometheus remote-write protocol
prometheus.relabelAdd/drop/rewrite labels on metric samples
prometheus.operator.podmonitorsScrape using Prometheus Operator PodMonitor CRDs
prometheus.operator.servicemonitorsScrape using ServiceMonitor CRDs
prometheus.operator.probesUse Probe CRDs
prometheus.receive_httpAccept remote-write traffic (proxy / fan-out)
prometheus.exporter.unixLinux node metrics (node_exporter equivalent)
prometheus.exporter.windowsWindows host metrics
prometheus.exporter.mongodbMongoDB metrics
prometheus.exporter.mysqlMySQL metrics
prometheus.exporter.postgresPostgreSQL metrics
prometheus.exporter.redisRedis metrics
prometheus.exporter.snmpSNMP-based device metrics
prometheus.exporter.blackboxBlackbox probe (HTTP/TCP/ICMP)
prometheus.exporter.cloudwatchAWS CloudWatch metrics
prometheus.exporter.kafkaKafka metrics
prometheus.exporter.processPer-process metrics

Inputs to scrape/relabel/remote_write chain via:

discovery.* → discovery.relabel → prometheus.scrape → prometheus.relabel → prometheus.remote_write
                                                                        (.receiver)

Loki — logs pipeline

ComponentPurpose
loki.source.fileTail log files (file_sd-style)
local.file_matchPath globs that produce targets for loki.source.file
loki.source.kubernetesTail Kubernetes container logs via API
loki.source.kubernetes_eventsStream cluster events
loki.source.journalsystemd journald
loki.source.dockerDocker container logs
loki.source.syslogListen for RFC5424/RFC3164 syslog
loki.source.gcplogGCP Pub/Sub logs
loki.source.awsfirehoseAWS Kinesis Data Firehose
loki.source.azure_event_hubsAzure Event Hubs
loki.source.cloudflareCloudflare logpush
loki.source.apiGeneric HTTP push endpoint
loki.echoPrint received logs (debugging)
loki.processPipeline stages: parse, label, drop, transform
loki.relabelRelabel without parsing
loki.writePush 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
ComponentPurpose
otelcol.receiver.otlpOTLP over gRPC (4317) and HTTP (4318)
otelcol.receiver.jaegerJaeger gRPC/Thrift
otelcol.receiver.zipkinZipkin HTTP
otelcol.receiver.prometheusConvert Prometheus scrape data into OTel metrics
otelcol.receiver.lokiConvert Loki log data into OTel logs
otelcol.receiver.kafkaConsume OTLP/JSON from Kafka
otelcol.receiver.opencensusOpenCensus protocol
otelcol.receiver.vcenterVMware vCenter
otelcol.receiver.datadogDatadog Agent traces/metrics
Processors
ComponentPurpose
otelcol.processor.batchBatch signals before export
otelcol.processor.memory_limiterDrop data if memory exceeds threshold
otelcol.processor.transformOTTL-based transformation
otelcol.processor.attributesInsert/update/delete attributes
otelcol.processor.resourcedetectionAdd resource attributes (k8s/aws/gcp/azure)
otelcol.processor.k8sattributesEnrich with k8s metadata
otelcol.processor.filterDrop telemetry matching OTTL expressions
otelcol.processor.tail_samplingTrace tail sampling
otelcol.processor.probabilistic_samplerHead-based sampling
otelcol.processor.spanRename / extract attributes from span names
otelcol.processor.deltatocumulativeConvert delta to cumulative temporality
Exporters
ComponentPurpose
otelcol.exporter.otlpOTLP gRPC
otelcol.exporter.otlphttpOTLP HTTP
otelcol.exporter.prometheusForward to prometheus.remote_write
otelcol.exporter.lokiForward to loki.write
otelcol.exporter.loadbalancingDistribute traces across endpoints (consistent hashing)
otelcol.exporter.kafkaKafka producer
otelcol.exporter.debugLog telemetry to stderr (debugging)
otelcol.exporter.faroFrontend Observability
Auth and extensions
ComponentPurpose
otelcol.auth.basicHTTP basic auth handler for otelcol clients
otelcol.auth.bearerBearer-token auth
otelcol.auth.headersStatic header auth
otelcol.auth.oauth2OAuth2 client credentials
otelcol.auth.sigv4AWS SigV4
otelcol.connector.spanmetricsGenerate RED metrics from spans
otelcol.connector.servicegraphBuild service-graph metrics from traces

OTel pipeline shape:

otelcol.receiver.* → otelcol.processor.* → otelcol.exporter.*
                  (output{traces=, metrics=, logs=})       (.input)

Pyroscope — profiles

ComponentPurpose
pyroscope.scrapePull pprof endpoints from targets
pyroscope.ebpfeBPF-based whole-system profiling
pyroscope.javaasync-profiler integration for JVMs
pyroscope.relabelRelabel profile streams
pyroscope.writeSend profiles to Pyroscope/Grafana Cloud Profiles
pyroscope.receive_httpAccept push from other Pyroscope clients

Beyla — eBPF auto-instrumentation

ComponentPurpose
beyla.ebpfAuto-generate traces/metrics from any process without code

Faro — frontend telemetry

ComponentPurpose
faro.receiverAccept browser RUM payloads from the Faro Web SDK
otelcol.exporter.faroForward OTel data to Grafana Cloud Frontend Observability

Database observability

ComponentPurpose
database_observability.mysqlQuery Performance, EXPLAIN, slow-query parsing for MySQL
database_observability.postgresSame for PostgreSQL

Mimir

ComponentPurpose
mimir.rules.kubernetesSync PrometheusRule CRDs into Mimir ruler

Local / remote helpers

ComponentPurpose
local.fileRead a file, expose .content (watches for changes)
local.file_matchGlob filesystem paths into targets
remote.httpFetch a URL, expose body as .content
remote.s3Fetch an S3 object
remote.kubernetes.configmapRead a ConfigMap value
remote.kubernetes.secretRead a Secret value
remote.vaultRead a HashiCorp Vault secret

Imports / modules (top-level)

BlockPurpose
import.filePull declarations from a local file
import.gitPull from a Git repo
import.httpPull from an HTTP endpoint
import.stringInline declarations
declareDefine 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/metrics

For 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