app-observability

Grafana Cloud アプリケーションオブザーバビリティ

ドキュメント: https://grafana.com/docs/grafana-cloud/monitor-applications/

OTLP + Mimir / Loki / Tempo / Pyroscope の同じパイプラインを共有する 3 つの製品です。

1. Application Observability — OTel spanmetrics による APM
2. Frontend Observability — Faro Web SDK、RUM + セッションリプレイ
3. AI Observability — OpenLIT による LLM / ベクトル DB のモニタリング

前提条件

• Grafana Cloud スタック + OTLP エンドポイント + 数値形式のインスタンス ID + MetricsPublisher + LogsPublisher + TracesPublisher の権限を持つ API キー
• APM の場合：OTel SDK で計装されたアプリ。Frontend の場合：Web アプリ + Faro アプリキー。AI の場合：Python ≥ 3.10
• ローカル OTLP レシーバーとしての Grafana Alloy（推奨）

共通のワークフロー

1. APM をセットアップ — Alloy レシーバー → Grafana Cloud + 検証

# 1. Set Cloud creds + start Alloy with config from references/apm.md
export GRAFANA_CLOUD_OTLP_ENDPOINT=https://otlp-gateway-prod-us-east-0.grafana.net/otlp
export GRAFANA_CLOUD_INSTANCE_ID=123456
export GRAFANA_CLOUD_API_KEY=glc_eyJ...
alloy fmt /etc/alloy/config.alloy   # syntax check
alloy run /etc/alloy/config.alloy

# 2. Verify Alloy is receiving + forwarding
curl -s http://localhost:12345/api/v0/web/components \
  | jq '.[] | select(.id|test("otelcol\\.exporter\\.otlphttp"))
        | {id, health:.health.state}'
# Expect health.state == "healthy"
curl -s http://localhost:12345/metrics \
  | grep -E 'otelcol_(receiver_accepted_spans|exporter_sent_spans)'

# 3. Point your app at Alloy (with required attributes!)
export OTEL_SERVICE_NAME="my-api"
export OTEL_RESOURCE_ATTRIBUTES="service.namespace=myteam,deployment.environment=production"
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

# 4. Verify spans landed in Tempo + spanmetrics generated
#    Tempo (TraceQL):  { resource.service.name = "my-api" }
#    Mimir (PromQL):   sum by (job) (rate(traces_spanmetrics_calls_total{service_name="my-api"}[5m]))
#    Expect > 0 within ~1 minute.

# 5. Verify it's wired to App Observability
#    Grafana → Application → Service Inventory: "my-api" should appear with RED metrics
#    Click into it → Service Map edges visible (requires span.kind on outbound calls)

Alloy の設定一式 + 必須のリソース属性 + spanmetric 名 + 相関リンクについては、references/apm.md を参照してください。

2. Faro で React フロントエンドを計装する

# 1. Install
npm install @grafana/faro-react @grafana/faro-web-tracing

// 2. initializeFaro with TracingInstrumentation + ReactIntegration (see references/faro.md)
//    Push a smoketest event so we have a known signal:
faro.api.pushEvent('faro_smoketest', { ts: Date.now().toString() });

# 3. Verify in DevTools Network — POST to /collect returns 202
#    (401 → wrong app key; 404 → wrong url region)

# 4. Verify in Grafana Cloud
#    - Frontend Observability → your app → Sessions: your session appears
#    - LogQL on Loki: {kind="event"} |= "faro_smoketest"
#    - With TracingInstrumentation: open the session → the trace ID links to Tempo

React の完全なサンプル、CDN の設定、セッション設定については、references/faro.md を参照してください。

3. AI / LLM オブザーバビリティを追加する

pip install openlit==1.42.0

# At app startup
import openlit
openlit.init(application_name="my-ai-app", environment="production")
# Your existing OpenAI / Anthropic / Cohere calls now emit OTel spans + metrics.

# Env (same OTLP endpoint as APM)
export OTEL_SERVICE_NAME="my-ai-app"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-<region>.grafana.net/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic $(echo -n $ID:$KEY | base64)"

# Verify after a few LLM calls:
#   PromQL: sum by (gen_ai_request_model) (rate(gen_ai_usage_input_tokens_total[5m]))
#   Dashboard: Grafana → AI Observability → "GenAI Observability" auto-populates

OpenLIT の完全なインストール、評価／ガード、GenAI メトリクスの一覧、ダッシュボード名については、references/ai-observability.md を参照してください。

フルスタック相関のチートシート

シグナル	製品	ストレージ	クエリ
RED メトリクス	App Observability	Mimir	PromQL
トレース	Tempo	Tempo	TraceQL
ログ	Loki	Loki	LogQL
プロファイル	Pyroscope	Pyroscope	ProfileQL
ブラウザー RUM	Frontend Observability	Loki + Tempo	LogQL / TraceQL
LLM メトリクス	AI Observability	Mimir	PromQL

相関キー：service.name ですべてのシグナルを結合します。トレースエグザンプラーはメトリクスのデータポイントにトレース ID を埋め込みます。ログ内の traceID と Faro が挿入する traceparent は、FE → BE のリンクに使用されます。

トラブルシューティング

• サービスが Service Inventory に表示されない → service.namespace（ジョブラベル）または deployment.environment リソース属性がありません
• Service Map のエッジが表示されない → アウトバウンド呼び出し（CLIENT に設定する必要があります）またはインバウンド呼び出し（SERVER）に span.kind が設定されていません
• Faro の /collect が 401 を返す → アプリキーが間違っています。404 を返す → URL のリージョンが Faro アプリと一致していません
• GenAI メトリクスがない → OpenLIT のバージョンが Cloud の想定する OTel semantic-conv のバージョンと一致していることを確認してください。ワークフロー #3 のように curl で認証を検証してください

参考資料

• references/apm.md — APM の基本：RED メトリクスの生成方法、必須の OTel リソース属性、Alloy の設定、相関リンク
• references/apm-setup.md — 詳細：言語別の OTel SDK セットアップ一式（Node / Python / Java / Go）、span-metrics のオプション、Alloy の完全な設定
• references/faro.md — Faro の基本：SDK の初期化、計装、セッションリプレイ
• references/frontend-observability.md — 詳細：Faro SDK の完全なリファレンス、React/Vue/Angular との統合、カスタムイベント、ソースマップ
• references/ai-observability.md — OpenAI / Anthropic / Bedrock / Vertex AI 向けの OpenLIT 自動計装

リソース

• App Observability のドキュメント
• Frontend Observability のドキュメント
• Faro Web SDK
• AI Observability のドキュメント
• OpenLIT