built-in-metrics

エージェントメトリクスの計測

あなたは、既存のプロバイダー呼び出しの周囲に LaunchDarkly のエージェントメトリクスを組み込むスキルを使用しています。あなたの仕事は、すでに存在するものを監査し、以下のラダーから適切なティアを選び、Monitoring タブが必要とするメトリクス（duration、input/output tokens、success/error、およびストリーミング時の TTFT）を依然として取得できる、最も儀式の少ない方法で実装することです。

最も重要なポイントは次のとおりです。呼び出しの形状に合う最も高いティアをデフォルトにすること。より低いティア（「手動のトラッカー呼び出しを書くだけ」）を選ぶと柔軟に見えますが、ドリフト、取得漏れのメトリクス、SDK がすでに卒業したレガシーパターンという代償を払うことになります。

4 段階のラダー

これは公式 SDK の README（Python コア、Node コア、およびすべてのプロバイダーパッケージ）が推奨する順序です。上から順に見ていき、最初に適合するティアで止めてください:

ティア	パターン	使用する場面	自動的に追跡されるもの
1 — マネージドランナー	Python: ManagedModel を返す ai_client.create_model(...)、続いて await model.run(...)。 Node: ManagedModel を返す aiClient.createModel(...)、続いて await model.run(...)。	呼び出しが会話型（チャット履歴、ターンベース）である場合。これはプロバイダーの README が最初に示すものです。	Duration、tokens、success/error — すべて、トラッカー呼び出しはゼロ。
2 — プロバイダーパッケージ + trackMetricsOf	tracker.trackMetricsOf(Provider.getAIMetricsFromResponse, () => providerCall())。現在のプロバイダーパッケージ: @launchdarkly/server-sdk-ai-openai、-langchain、-vercel（Node）および launchdarkly-server-sdk-ai-openai、-langchain（Python）。	形状がチャットループではない（ワンショット補完、構造化出力、エージェントステップ）が、フレームワークまたはプロバイダーにパッケージがある場合。	ラッパーから Duration + success/error、パッケージ組み込みの getAIMetricsFromResponse エクストラクターから tokens。
3 — カスタムエクストラクター + trackMetricsOf	同じ trackMetricsOf ラッパーを使用しますが、プロバイダーの応答を LDAIMetrics（tokens + success）にマッピングする小さな関数を自分で書きます。	プロバイダーパッケージが存在しない場合（Anthropic 直接、Gemini、Cohere、カスタム HTTP）。	ラッパーから Duration + success/error、あなたのエクストラクターから tokens。
4 — 生の手動	trackDuration、trackTokens、trackSuccess / trackError への個別の呼び出し、およびストリーム用の trackTimeToFirstToken。	TTFT を伴うストリーミング、特殊な応答形状、部分的な追跡、ティア 2〜3 ではきれいにラップできないもの。	明示的に呼び出したもののみ — 漏らさないことはあなたの責任です。

すべてのプロバイダー — OpenAI、LangChain、Vercel、Bedrock、Anthropic、Gemini、カスタム HTTP — は同じ汎用的な形状を使用します: Node では tracker.trackMetricsOf(getAIMetricsFromResponse, () => providerCall())、Python では tracker.track_metrics_of(get_ai_metrics_from_response, provider_call)。プロバイダーごとに変わるのはエクストラクターだけです: 対応する @launchdarkly/server-sdk-ai-<provider>（または ldai_<provider>）パッケージから getAIMetricsFromResponse をインポートするか、LDAIMetrics を返す小さなカスタム関数を書きます。プロバイダー固有のトラッカーメソッドはありません。

ワークフロー

1. 既存の呼び出し箇所を調査する

ティアを選択する前に、プロバイダーの呼び出しを見つけて次の質問に答えてください。

• 形状? チャットループ（履歴 + ターンベース）ですか、単発の完了ですか、エージェントのステップですか、それとも何か別のものですか？ → ティア 1 と 2 のどちらになるかを決めます。
• フレームワーク? 生のプロバイダー SDK？ LangChain / LangGraph？ Vercel AI SDK？ CrewAI？ Strands？ → どのティア 2 プロバイダーパッケージ（該当する場合）が適用されるかを決めます。
• プロバイダー? OpenAI、Anthropic、Bedrock、Gemini、Azure、カスタム HTTP？ → 以下のパッケージ利用可否マトリクスと照合してください。
• ストリーミング? はいの場合、TTFT トラッキングが必要になります。つまり、残りの部分がティア 2 であっても、TTFT の部分はティア 4 になります。
• 言語? Python それとも Node？ プロバイダーパッケージのカバレッジは両者で異なります。
• すでに設定を使用していますか? 使用していない場合は、まず configs-create にルーティングしてください。トラッキングにはトラッカーが必要であり、トラッカーは completion_config() / completionConfig() / createModel() から返される設定オブジェクトに対して create_tracker() / createTracker() を呼び出すことで取得します。
• 現在の SDK API を使用していますか? 呼び出し箇所が aiclient.config(...) / aiClient.config(...) を使用している場合、または AIConfig(...) / LDAIConfig のデフォルトを構築している場合、それは 0.20 より前のサーフェスです。トラッキングを追加する前に、この作業の一環として移行してください。
  • aiclient.config(...) → 単発/チャットの場合は aiclient.completion_config(...)、エージェントモードの場合は aiclient.agent_config(...)（呼び出しシグネチャをそのまま反映させてください）。Node では camelCase で同様です。
  • AIConfig(...) のデフォルト → AICompletionConfigDefault(...) または AIAgentConfigDefault(...)（Node: LDAICompletionConfigDefault / LDAIAgentConfigDefault）。AIConfig は SDK が返す基底クラスであり、有効なデフォルト値コンストラクターではありません。型付きの *Default バリアントがそれに当たります。
  • 結果がタプルのアンパック（config, tracker = aiclient.config(...)）になっていた場合は、アンパックを削除してください。新しいメソッドは単一の設定オブジェクトを返します。トラッカーは config.create_tracker() / aiConfig.createTracker() を介して取得してください。
  • より深い書き換え（モデル/プロンプトもハードコードされている呼び出し箇所）については、ここで完全な移行を行うのではなく、migrate に引き渡してください。

2. ティア 2 の選択肢を調べる

このマトリクスを使用して、あなたの状況でティア 2（プロバイダーパッケージ）が利用可能かどうかを判断してください。利用できない場合は、ティア 3（カスタム抽出器）に下げてください。形状がチャットループの場合は、このマトリクスの内容に関係なく、まずティア 1 に進んでください。

フレームワーク / プロバイダー	Python プロバイダーパッケージ	Node プロバイダーパッケージ	参照
OpenAI（直接 SDK）	launchdarkly-server-sdk-ai-openai	@launchdarkly/server-sdk-ai-openai	openai-tracking.md
LangChain / LangGraph	launchdarkly-server-sdk-ai-langchain	@launchdarkly/server-sdk-ai-langchain	langchain-tracking.md
Vercel AI SDK	—	@launchdarkly/server-sdk-ai-vercel	（Vercel プロバイダーのドキュメントを使用）
AWS Bedrock（Converse または InvokeModel）	—（LangChain-aws またはカスタム抽出器を使用）	—（LangChain-aws またはカスタム抽出器を使用）	bedrock-tracking.md
Anthropic 直接 SDK	—	—	anthropic-tracking.md
Gemini / Google GenAI	—	—	gemini-tracking.md
Strands Agents	—（ティア 3 カスタム抽出器）	—（ティア 3 カスタム抽出器）	strands-tracking.md
Cohere、Mistral、カスタム HTTP	—	—	ティア 3 カスタム抽出器
任意のプロバイダー、ストリーミング + TTFT	—（ティア 4 のみ）	trackStreamMetricsOf（TTFT なし）+ 手動 TTFT	streaming-tracking.md

3. 一致するリファレンスから実装する

ティアとプロバイダーがわかったら、リファレンスファイルを開いてパターンに従います。リファレンスは、ティア 1 が常に最初の例、次にティア 2/3、最後にティア 4 となるように書かれています。アプリの形状に一致する最初のティアで止めてください。

すべてのティアに適用されるガードレール:

1. トラッキング対象の呼び出しを行う前に、必ず config.enabled を確認してください。 無効化された設定は、ユーザーがその機能をオフにしたことを意味します。プロバイダーの呼び出しをまったく行うのではなく、アプリが使用するフォールバック（キャッシュされたレスポンス、エラー、縮退したパス）へショートサーキットすべきです。
2. 既存の呼び出しをラップし、書き換えないでください。 ティア 2 とティア 3 は、変更されていないプロバイダーの呼び出しを囲むように設計されています。トラッカーに合わせて呼び出しを書き換えていることに気づいたら、間違ったティアにいます。1 つ下のティアに落としてください。
3. エラーは trackMetricsOf の内部で処理されます。 ラッパーは例外をキャッチし、内部的に trackError() を記録して、再スローします — その上に except: tracker.trackError() を追加しないでください**、これは noop であり、at-most-once ガードにも抵触します。ティア 1 は両方のパスを自動的に処理します。ティア 4（手動、ストリーミング、track_duration_of）では、呼び出し元がエラートラッキング呼び出しを自身で担当します。
4. クローズの前に必ずフラッシュしてください。 クライアントをクローズする前に ldClient.flush()（Python: ldclient.get().flush()、Node: await ldClient.flush()）を呼び出してください。そうしないと、末尾のイベントが失われるおそれがあります — 短命なスクリプトでも長時間実行されるサービスでも同様です。Node では、ldClient.close() は Promise を返します。await してください。

4. 検証する

Monitoring タブが埋まることを確認します:

• 計測されたパスを通して実際のリクエストを 1 回実行します。
• LaunchDarkly で設定を開き → Monitoring タブを確認します。Duration、トークン数、生成回数が 1〜2 分以内に表示されるはずです。
• エラーを強制的に発生させ（不正な API キー、max_tokens をゼロにする、など何でも構いません）、エラー数が増加することを確認します。
• ストリーミングの場合: TTFT が表示されることを確認します。表示されない場合は、おそらくストリームの作成を trackMetricsOf でラップしたものの、手動の trackTimeToFirstToken 呼び出しを追加していない可能性があります — streaming-tracking.md を参照してください。

クイックリファレンス: トラッカーメソッド

設定オブジェクトのファクトリーを介してトラッカーを取得します: tracker = config.create_tracker() (Python) または const tracker = aiConfig.createTracker() (Node)。ファクトリーは実行ごとに 1 回呼び出し、返された tracker をすべての呼び出しで再利用してください。ファクトリーを呼び出すたびに新しい runId が発行され、そのトラッカーが発行するすべてのトラッキングイベントにタグ付けされるため、単一の実行からのイベントを相互に関連付けることができます (エクスポートされたイベント / 下流システム経由)。Monitoring タブは現在、イベントを実行ごとにグループ化するのではなく集約します。runId はイベントを UI の外部でエクスポートまたはクエリする際に役立ち、SDK の at-most-once ガードがキーとする識別子です。以下のメソッドは生の API サーフェスです。ほとんどの場合、これらを個別に呼び出すべきではありません。trackMetricsOf または Tier-1 のマネージドランナーを使用してください。このリストは、既存のコード内でこれらのメソッドを認識し、本当に Tier 4 が必要なときに適切なものを選べるようにするために記載しています。

メソッド (Python ↔ Node)	Tier	動作
track_metrics_of(extractor, fn) / trackMetricsOf(extractor, fn)	2 / 3	プロバイダー呼び出しをラップし、所要時間 + 成功/エラーをキャプチャし、トークン用に抽出器を呼び出します。これがデフォルトの汎用トラッカーです。
track_metrics_of_async(extractor, fn) (Python)	2 / 3	上記の非同期版です。
trackStreamMetricsOf(extractor, streamFn) (Node のみ)	2 / 3	ストリーミング版です。抽出器がチャンクを処理する場合、チャンクごとの使用量をキャプチャします。TTFT は自動キャプチャしません。
track_duration(ms) / trackDuration(ms)	4	レイテンシをミリ秒単位で記録します。
track_duration_of(fn) / trackDurationOf(fn)	4	呼び出し可能オブジェクトをラップし、所要時間を自動的に記録します。トークンや成功はキャプチャしません。明示的な呼び出しと組み合わせて使用してください。
track_tokens(TokenUsage) / trackTokens({input, output, total})	4	トークン使用量を記録します。
track_time_to_first_token(ms) / trackTimeToFirstToken(ms)	4	ストリーミングレスポンスの TTFT を記録します。
track_success() / trackSuccess()	4	生成を成功としてマークします。Monitoring タブでカウントするために必要です。
track_error() / trackError()	4	生成を失敗としてマークします。同じリクエストで trackSuccess() も呼び出さないでください。
track_feedback({kind}) / trackFeedback({kind})	any	フィードバック UI から thumbs-up / thumbs-down を記録します。成功/エラーのパスとは独立しています。
track_tool_call(name) / trackToolCall(name)	any	単一のツール呼び出しを名前で記録します。両方の SDK で利用可能です。
track_tool_calls([names]) / trackToolCalls([names])	any	バッチ版です。ツール呼び出しのリストを 1 回の呼び出しで記録します。
track_judge_result(result) / trackJudgeResult(result)	any	プログラムによる judge 評価を記録します。result.sampled は評価が実行されたかどうかを示します。

関連スキル

• configs-create — アプリにまだ設定がない場合の前提条件
• custom-metrics — このスキルがキャプチャするエージェントメトリクスの上に重ねるビジネスメトリクス (コンバージョン、解決、リテンション)
• online-evals — サンプリングされたライブリクエストに対する自動品質スコアリング (LLM-as-judge)。ここでのメトリクスを補完します
• migrate — ハードコードから AgentControl への移行の Stage 4 はこのスキルに委譲します