opentelemetry

Grafana と OpenTelemetry

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

ベンダーに依存しない計装パイプラインです。アプリは OTLP → Alloy（または直接）→ Grafana Cloud（Mimir / Loki / Tempo / Pyroscope）の順にデータを送信します。

バックエンド

シグナル	バックエンド
メトリクス	Grafana Mimir
ログ	Grafana Loki
トレース	Grafana Tempo
プロファイル	Grafana Pyroscope

前提条件

• Grafana Cloud スタック、またはセルフホストの Mimir / Loki / Tempo
• Cloud OTLP エンドポイント：https://otlp-gateway-<region>.grafana.net/otlp
• Basic 認証の認証情報：数値のインスタンス ID と、MetricsPublisher + LogsPublisher + TracesPublisher を持つ API トークン
• 計装するアプリ

一般的なワークフロー

1. Grafana Cloud OTLP エンドポイントで認証する

# 1. Build the auth header
INSTANCE_ID=123456
API_KEY="glc_eyJ..."
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-gateway-prod-us-east-0.grafana.net/otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic $(echo -n "${INSTANCE_ID}:${API_KEY}" | base64)"
export OTEL_RESOURCE_ATTRIBUTES="service.name=myapp,service.namespace=myteam,deployment.environment=prod"

# 2. Smoke-test creds with a curl POST against the OTLP traces endpoint (empty body)
curl -s -o /dev/null -w "%{http_code}\n" \
  -X POST -H "Content-Type: application/x-protobuf" \
  -H "Authorization: Basic $(echo -n "${INSTANCE_ID}:${API_KEY}" | base64)" \
  "$OTEL_EXPORTER_OTLP_ENDPOINT/v1/traces" --data-binary '\n'
# Expect 400 (malformed payload) — NOT 401 (auth) or 404 (wrong endpoint).

2. Java アプリを自動計装して検証する

# 1. Download the Grafana JVM agent (single jar)
curl -sLO https://github.com/grafana/grafana-opentelemetry-java/releases/latest/download/grafana-opentelemetry-java.jar

# 2. Run with the agent + env from step 1
java -javaagent:./grafana-opentelemetry-java.jar -jar myapp.jar

# 3. Generate traffic, then verify in Grafana → Explore → Tempo:
#    TraceQL: { resource.service.name = "myapp" }
#    Expect spans within ~30s. Also verify metrics:
#    PromQL: count by (service_name)({service_name="myapp"})

3. Python アプリを自動計装する

pip install "opentelemetry-distro[otlp]"
opentelemetry-bootstrap -a install

# Same env vars as step 1, then:
opentelemetry-instrument python app.py

# Verify the same way — Explore → Traces filter service.name=myapp.

4. バッファリング／サンプリングコレクターとして Alloy を追加する

# Application points at local Alloy (gRPC fastest)
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

# Alloy environment for forwarding to Cloud
export GRAFANA_CLOUD_OTLP_ENDPOINT=https://otlp-gateway-prod-us-east-0.grafana.net/otlp
export GRAFANA_CLOUD_INSTANCE_ID=$INSTANCE_ID
export GRAFANA_CLOUD_API_KEY=$API_KEY
alloy run /etc/alloy/config.alloy

# Verify Alloy received and forwarded
curl -s http://localhost:12345/metrics | grep otelcol_exporter_sent_spans

Alloy の完全な設定、テールサンプリングブロック、OTel Collector YAML、K8s Operator のインストールについては、references/collector-config.md を参照してください。

言語別 SDK の詳細（Go の完全なコード、Node の手動セットアップ、.NET ASP.NET Core、環境変数に関するすべての注意点）については、references/instrumentation.md を参照してください。

5. Kubernetes — Operator 経由で自動インジェクションする

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata: { name: my-instrumentation }
spec:
  exporter: { endpoint: http://otelcol:4317 }
  propagators: [tracecontext, baggage]
  java:
    image: us-docker.pkg.dev/grafanalabs-global/docker-grafana-opentelemetry-java-prod/grafana-opentelemetry-java:2.3.0-beta.1
  nodejs: {}
  python: {}

次に、ポッドにアノテーションを付けます。

metadata:
  annotations:
    instrumentation.opentelemetry.io/inject-java: "true"
    # or: inject-nodejs, inject-python, inject-dotnet

# Verify the operator injected the agent
kubectl describe pod <pod> | grep -A2 'opentelemetry-auto-instrumentation'
# Then run the same Grafana Explore checks.

サンプリング — どれを選ぶか

# Head sampling (cheap, decided at start; may lose rare errors)
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1   # 10%

テールサンプリング（トレース全体を確認してから判断し、エラーは保持して残りをサンプリングする）には、Alloy / OTel-Collector の tail_sampling プロセッサーが必要です。完全な設定ブロックは references/collector-config.md を参照してください。

主な環境変数

変数	例
OTEL_EXPORTER_OTLP_ENDPOINT	https://otlp-gateway-prod-us-east-0.grafana.net/otlp
OTEL_EXPORTER_OTLP_PROTOCOL	grpc または http/protobuf
OTEL_EXPORTER_OTLP_HEADERS	Authorization=Basic <base64>
OTEL_RESOURCE_ATTRIBUTES	service.name=app,service.namespace=team,deployment.environment=prod
OTEL_SERVICE_NAME	service.name の省略形
OTEL_TRACES_SAMPLER / _ARG	parentbased_traceidratio / 0.1

トラブルシューティング

• OTLP ゲートウェイから 401 が返る → インスタンス ID が数値でないか、API キーにパブリッシャーロールがありません
• 404 が返る → エンドポイント URL が間違っています（末尾が /otlp である必要があります）
• スパンが見つからない → OTEL_EXPORTER_OTLP_PROTOCOL がトランスポートと一致していることを確認してください（Cloud OTLP ゲートウェイ = http/protobuf、ローカルの Alloy = grpc）
• バンドル後に Node.js の自動計装が機能しない → @vercel/ncc などのバンドラーは require フックを無効にします
• Gunicorn / uWSGI 上の Python でスパンが表示されない → fork 後のフックで OTel プロバイダーを再初期化してください

リソース

• Grafana OTel ドキュメント
• Grafana Cloud OTLP
• Grafana JVM エージェント
• Grafana .NET SDK
• OTel Operator