monitoring-observability

モニタリングとオブザーバビリティ

Prometheus、Grafana、OpenTelemetry、Langfuse を再解説するのではなく、それらをラップするものです。このスキルでは OrchestKit 独自の差分（バージョンの下限、プロジェクト内の決定事項、実体験から得た教訓）を扱い、それ以外はすべてベンダーの情報を参照します。まず references/ork-delta.md を確認してください。

上流ドキュメントでカバーされる内容（再記述しない）

以下のトピックは公式ドキュメントで網羅されています。ソースを読み、ローカルに複製しないでください。

トピック	公式ソース
Prometheus のメトリクスタイプ、RED メソッド、カーディナリティ、PromQL	https://prometheus.io/docs/practices/
Alertmanager のグルーピング、抑制、エスカレーション、ランブック	https://prometheus.io/docs/alerting/latest/configuration/
Grafana のダッシュボード、Loki と LogQL、Promtail	https://grafana.com/docs/
OpenTelemetry のスパン、サンプリング、コンテキスト伝搬	https://opentelemetry.io/docs/
Langfuse Python SDK（@observe、as_type、score_current_span、should_export_span、LangfuseMedia）	https://langfuse.com/docs/sdk/python
Langfuse の Python v2 から v4 および JS v3 から v5 への移行手順	https://langfuse.com/docs/sdk/python/v4-migration
Langfuse のセルフホスティング（ClickHouse、Redis、S3、Helm）	https://langfuse.com/docs/deployment/self-host
Langfuse のコスト追跡、モデル料金、Metrics API v2	https://langfuse.com/docs/model-usage-and-cost
Langfuse のスコア、オンライン評価器、アノテーションキュー、プロンプト管理	https://langfuse.com/docs/scores/overview
Langfuse のフレームワーク統合（LangChain、LangGraph、CrewAI、Pydantic AI、Bedrock、LiveKit）	https://langfuse.com/docs/integrations
エージェントグラフ、オブザベーションタイプ、レンダリングされたツール呼び出し	https://langfuse.com/docs/tracing-features/agent-graphs
PSI、KS 検定、KL および JS ダイバージェンス、Wasserstein、埋め込みドリフト	https://www.evidentlyai.com/blog/data-drift-detection-large-datasets
EWMA 管理図	https://www.itl.nist.gov/div898/handbook/pmc/section3/pmc324.htm
structlog、Winston、相関 ID、ログサンプリング	https://www.structlog.org/en/stable/

クイックリファレンス

カテゴリ	ルール	影響度	使用場面
インフラストラクチャのモニタリング	1	CRITICAL	Grafana ダッシュボード、ゴールデンシグナル、SLO/SLI
LLM オブザーバビリティ	1	HIGH	Langfuse トレース、オブザベーションタイプ、エージェントグラフ
サイレント障害	3	HIGH	ツールのスキップ、品質の低下、ループ／トークン急増のアラート

全 3 カテゴリに 5 つのルールがあります。 ドリフト検出、コスト追跡、評価スコアリング、Prometheus の計装、アラートルールの作成は、上記の上流ソースに移管されました。

クイックスタート

# Langfuse v4 LLM tracing: semantic as_type plus inline scoring
from langfuse import observe, get_client

@observe(as_type="generation", name="analyze_content")
async def analyze_content(content: str):
    get_client().update_current_trace(
        user_id="user_123", session_id="session_abc",
        tags=["production", "orchestkit"],
    )
    result = await llm.generate(content)
    get_client().score_current_span(name="response_quality", value=0.85)
    return result

# Prometheus RED method, wired the way this repo expects (bounded labels only)
from prometheus_client import Counter, Histogram

http_requests = Counter('http_requests_total', 'Total requests', ['method', 'endpoint', 'status'])
http_duration = Histogram('http_request_duration_seconds', 'Request latency',
    buckets=[0.01, 0.05, 0.1, 0.5, 1, 2, 5])

インフラストラクチャのモニタリング

ダッシュボードとヘルスチェックのパターンを扱います。メトリクスの計装とアラートルールの構文は上流ドキュメントを参照してください。

ルール	ファイル	主なパターン
Grafana ダッシュボード	rules/monitoring-grafana.md	ゴールデンシグナル、SLO/SLI、ヘルスチェック

CC 2.1.161 — OTEL リソース属性をメトリクスラベルとして使用： OTEL_RESOURCE_ATTRIBUTES の値がメトリクスのデータポイントにラベルとして付与されるようになりました。これにより、使用状況メトリクスをカスタムディメンション（チーム、リポジトリ、環境）で分類できます。マルチテナント／チーム別のコストおよび使用状況を追跡するには、ダッシュボードにラベルセレクターを追加してください。

LLM オブザーバビリティ

Langfuse ベースの LLM アプリケーション向けトレースです。コスト追跡、スコアリング、ドリフト統計は上流ドキュメントを参照してください。ここでは、このリポジトリでトレースをどのように構成しているかを扱います。

ルール	ファイル	主なパターン
Langfuse トレース	rules/llm-langfuse-traces.md	@observe デコレーター、OTEL スパン、エージェントグラフ

サイレント障害

LLM エージェントのサイレント障害を検出し、アラートを送信します。

ルール	ファイル	主なパターン
ツールのスキップ	rules/silent-tool-skipping.md	予想されたツール呼び出しと実際のツール呼び出し、Langfuse トレース
品質の低下	rules/silent-degraded-quality.md	ヒューリスティックと LLM-as-judge、z スコアのベースライン
サイレントアラート	rules/silent-alerting.md	ループ検出、トークンの急増、エスカレーションワークフロー

CC 2.1.169 — OTEL クライアント証明書のパスには信頼が必要です： 信頼されていないプロジェクト設定では、信頼の確認なしに OTEL クライアント証明書のパスを設定できなくなりました。OTEL エクスポーターがプロジェクトの .claude/settings.json で設定したクライアント証明書を使用する場合、信頼されていないプロジェクトでの初回使用時に一度だけ信頼確認のプロンプトが表示されます。2.1.169 以降にテレメトリーがひそかに送信されなくなった場合、通常はコレクターではなく、この制限が原因です。

主な決定事項

決定事項	推奨事項	理由
メトリクスの手法	RED メソッド（レート、エラー、継続時間）	業界標準であり、サービスの健全性に不可欠な要素を網羅します
ログ形式	構造化 JSON	機械で解析でき、ログの集約に対応します
トレーシング	OpenTelemetry	ベンダーに依存せず、自動計装に対応し、幅広いエコシステムを備えています
LLM のオブザーバビリティ	Langfuse（LangSmith ではなく）	オープンソースでセルフホスト可能、プロンプト管理機能を内蔵しています
LLM トレーシング API	@observe(as_type=...) + score_current_span()	v4：セマンティック型、インラインスコアリング、スパンフィルタリング
Langfuse API	Observations API v2 + Metrics API v2	v4（2026年3月）：クエリの高速化、大規模な集計
フックのテレメトリー転送	~/.claude/analytics/ 配下の JSONL。SDK をプロセス内で使用しないでください	フックはイベントごとに起動するプロセスです。SDK の初期化は起動のたびにコストが発生します（references/ork-delta.md）

詳細ドキュメント

リソース	説明
references/ork-delta.md	まずはこちらをお読みください。 上流のドキュメントには記載されていない最低基準、プロジェクト内の決定事項、過去の問題
references/langfuse-js-v5.md	JS/TS SDK v5 と Python 4.x の差分：パッケージ一覧、存在しないパッケージ、SpanProcessor と exporter の違い。JS で Langfuse のコードを書く前にお読みください
references/experiments-api.md	このリポジトリで使用する Langfuse の実験とデータセットの実行
references/evaluation-scores.md	スコアの形式とスコアリングパイプラインの接続方法
references/session-tracking.md	複数ステップのワークフローにおけるセッションとユーザーのグループ化
references/metrics-collection.md	Claude Code の OTEL メトリクス一覧とコレクター側での結合
references/dashboards.md	ダッシュボードのレイアウト規約
references/structured-logging.md	構造化ログのフィールド規約
references/dev-agent-lens.md	API 境界のオブザーバビリティを実現する LiteLLM プロキシレイヤー
examples/orchestkit-monitoring-dashboard.md	監視ダッシュボードの実例
scripts/	テンプレート：Prometheus、OpenTelemetry、ヘルスチェック、Langfuse

関連スキル

• defense-in-depth - セキュリティアーキテクチャの一部としてのレイヤー 8 オブザーバビリティ
• devops-deployment - CI/CD および Kubernetes とのオブザーバビリティ統合
• resilience-patterns - サーキットブレーカーと障害シナリオの監視
• llm-evaluation - Langfuse のスコアリングと統合する評価パターン
• caching - Langfuse で追跡するコストを削減するキャッシュ戦略