alloy

Grafana Alloy

ドキュメント: https://grafana.com/docs/alloy/latest/

メトリクス、ログ、トレース、プロファイルに対応する、OpenTelemetry 互換のコレクターです。1つのバイナリですべてを扱えます。

前提条件

• 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 ポッド、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 からの移行