alloy

Grafana Alloy

文档：https://grafana.com/docs/alloy/latest/

兼容 OpenTelemetry 的采集器——一个二进制文件即可处理指标、日志、链路和性能剖析数据。

前置条件

• 已安装 alloy CLI（brew install grafana/grafana/alloy、apt install alloy，或使用 grafana/alloy Docker 镜像）
• 用于发送数据的端点（Grafana Cloud、Prometheus、Loki、Tempo、Pyroscope）
• 该端点的 API 密钥和用户名，并导出为 GRAFANA_API_KEY 等环境变量

常见工作流

1. 在本地编写并验证配置

// 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. 添加日志发送（文件 → 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. 接收 OTLP 链路并发送到 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

完整模式集（Kubernetes 发现与重新标记，以及包含全部 4 种信号的完整 Cloud 管道）：references/collection-patterns.md。

参考资料

• references/config-syntax.md — 块、属性和表达式语法、import.*、remotecfg、集群
• references/components.md — 完整组件目录，包含用途和典型参数
• references/collection-patterns.md — 端到端管道（K8s Pod、OTLP、性能剖析数据、日志）

故障排查

• alloy validate → “component not found” → 版本过旧；运行 alloy --version 并升级
• UI 显示组件 unhealthy → 在 http://localhost:12345 中点击该组件，查看实时错误
• prometheus_remote_storage_samples_dropped_total 持续增长 → 检查 enqueue_retries_total、remote_write 端点 URL 和凭据
• 没有链路到达 Tempo → 检查 otelcol_receiver_refused_spans，以及导出器的 otelcol_exporter_sent_spans / otelcol_exporter_send_failed_spans

资源

• Alloy 文档
• 组件参考
• 从 Grafana Agent 迁移