LLM Observability のための自動インスツルメンテーション

Docs > LLM Observability > LLM Observability Instrumentation > LLM Observability のための自動インスツルメンテーション

概要

Datadog の LLM Observability は、さまざまな LLM インテグレーションを通じて、サポートされている LLM フレームワークやライブラリへの呼び出しを自動的にトレースし、注釈を付けることができます。LLM Observability SDK を使用して LLM アプリケーションを実行すると、これらの LLM インテグレーションはデフォルトで有効になり、コードを変更することなく、すぐにトレースと観測可能性を提供します。

自動インスツルメンテーションは、サポートされているフレームワークやライブラリへの呼び出しに対して機能します。他の呼び出しをトレースするには (例: API 呼び出し、データベースクエリ、内部関数)、 LLM Observability SDK リファレンスを参照し、手動でインスツルメンテーションを追加する方法を確認してください。

###サポートされているフレームワークとライブラリ

| フレームワーク | サポートされているバージョン | トレースバージョン | |||| | Amazon Bedrock | >= 1.31.57 | >= 2.9.0 | | Amazon Bedrock Agents | >= 1.38.26 | >= 3.10.0 | | Anthropic | >= 0.28.0 | >= 2.10.0 | | CrewAI | >= 0.105.0 | >= 3.5.0 | | Google ADK | >= 1.0.0 | >= 3.15.0 | | Google GenAI | >= 1.21.1 | >= 3.11.0 | | LangChain | >= 0.0.192 | >= 2.9.0 | | LangGraph | >= 0.2.23 | >= 3.10.1 | | LiteLLM | >= 1.70.0 | >= 3.9.0 | | MCP | >= 1.10.0 | >= 3.11.0 | | OpenAI, Azure OpenAI | >= 0.26.5 | >= 2.9.0 | | OpenAI Agents | >= 0.0.2 | >= 3.5.0 | | Pydantic AI | >= 0.3.0 | >= 3.11.0 | | Strands Agents | >= 1.11.0 | すべて | | Vertex AI | >= 1.71.1 | >= 2.18.0 |

| フレームワーク | サポートされているバージョン | トレースバージョン | |||| | Amazon Bedrock | >= 3.422.0 | >= 5.35.0 (CJS)、>=5.35.0 (ESM) | | Anthropic | >= 0.14.0 | >= 5.71.0 (CJS)、>=5.71.0 (ESM) | | LangChain | >= 0.1.0 | >= 5.32.0 (CJS), >=5.38.0 (ESM) | | OpenAI, Azure OpenAI | >= 3.0.0 | >= 4.49.0、>= 5.25.0 (CJS)、>= 5.38.0 (ESM) | | Vercel AI SDK | >=4.0.0 | >= 5.63.0 (CJS)、>=5.63.0 (ESM) | | VertexAI | >= 1.0.0 | >= 5.44.0 (CJS), >=5.44.0 (ESM) | | Google GenAI | >= 1.19.0 | >= 5.81.0 (CJS), >=5.81.0 (ESM) |

ESM (ESMAScript モジュール) へのサポート

ESM プロジェクトの自動インスツルメンテーションは、ddtrace@>=5.38.0 からサポートされています。ESM プロジェクトで自動インスツルメンテーションを有効にするには、次の Node オプションでアプリケーションを実行してください。

--import dd-trace/register.js

commandline setup には、代わりに次のオプションを使用してください。

--import dd-trace/initialize.mjs
# or
--loader dd-trace/initialize.mjs

#####トラブルシューティング: モジュールの互換性のためのカスタムローダー

このオプションを使用してアプリケーションを起動する際にエラーが発生した場合、モジュールの互換性の問題が考えられます。モジュールとファイルを除外した独自のフックファイルを作成できます。

// hook.mjs

import { register } from 'node:module';

register('import-in-the-middle/hook.mjs', import.meta.url, {
  parentURL: import.meta.url,
  data: { exclude: [
    /langsmith/,
    /openai\/_shims/,
    /openai\/resources\/chat\/completions\/messages/,
    // Add any other modules you want to exclude
  ]}
});

このカスタムローダーを使用するには、次の Node オプションでアプリケーションを実行してください。

--import ./hook.mjs

バンドルされたアプリケーション (esbuild、Webpack) をサポートしています。

バンドルされたアプリケーション (esbuild、Webpack) でLLM Observability インテグレーションを使用するには、これらのインテグレーションのモジュールをバンドルから除外する必要があります。

#####esbuild esbuild を使用している場合は、Node.js トレーサーによるバンドリングを参照してください。

#####Webpack Webpack の場合、webpack 設定の externals セクションに対応するインテグレーションを指定してください。

// webpack.config.js
module.exports = {
  resolve: {
    fallback: {
      graphql: false,
    }
  },
  externals: {
    openai: 'openai'
  }
}

Next.js のサポート

アプリケーション内でトレーサーを適切に初期化して、自動インスツルメンテーションが正しく機能するようにしてください。Next.js アプリケーションに TypeScript または ESM を使用している場合は、次のように instrumentation.{ts/js} ファイル内でトレーサーを初期化し、構成オプションを環境変数として指定してください。

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const initializeImportName = 'dd-trace/initialize.mjs';
    await import(/* webpackIgnore: true */ initializeImportName as 'dd-trace/initialize.mjs')
  }

  // ...
}

それ以外の場合、CommonJS Next.js アプリケーションでは、init 関数を直接使用できます。

// instrumentation.js
const tracer = require('dd-trace')

function register () {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    tracer.init({}); // specify options here or they will be read from environment variables
  }

  // ...
}

module.exports = register;

次に、ddtrace および serverExternalPackages 内の他のサポートされているインテグレーションを、next.config.{ts/js} ファイルで指定してください。

// next.config.ts
module.exports = {
  serverExternalPackages: ['dd-trace', 'openai'], // add any other supported integrations here to be auto-instrumented
}

| フレームワーク | サポートされているバージョン | トレーサーバージョン | |||| | OpenAI, Azure OpenAI | >= 3.0.0 | >= 1.59.0 |

Datadog LLM Observability は、ネイティブに OpenTelemetry GenAI セマンティック規約 v1.37+ に準拠したスパンを発行する任意のフレームワークもサポートしており、Datadog トレーサーを必要としません。詳細については、OpenTelemetry インスツルメンテーションを参照してください。

##LLM インテグレーション

Datadog の LLM インテグレーションは、トレースされた呼び出しのレイテンシ、エラー、入力パラメーター、入力および出力メッセージ、トークン使用量 (利用可能な場合) をキャプチャします。

Amazon Bedrock

Amazon Bedrock インテグレーションは、Amazon Bedrock Runtime Python SDK のチャットモデル呼び出しに対して自動インスツルメンテーションを提供します (Boto3/Botocore を使用)。

###トレース対象メソッド

Amazon Bedrock インテグレーションは、以下のメソッドをインスツルメントします。

チャットメッセージ: InvokeModel ストリーミングされたチャットメッセージ: InvokeModelWithResponseStream チャットメッセージ: Converse (ddtrace>=3.4.0 が必要) ストリーミングされたチャットメッセージ: ConverseStream (ddtrace>=3.5.0 が必要)

Amazon Bedrock インテグレーションは、埋め込み呼び出しのトレースをサポートしていません。

Amazon Bedrock インテグレーションは、Amazon Bedrock Runtime Node.js SDK のチャットモデル呼び出しに対して自動トレースを提供します (BedrockRuntimeClient を使用)。

###トレース対象メソッド

Amazon Bedrock インテグレーションは、以下のメソッドをインスツルメントします。

チャットメッセージ: InvokeModel

Amazon Bedrock エージェント

Amazon Bedrock エージェントインテグレーションは、Amazon Bedrock エージェントランタイム Python SDK のエージェント呼び出しに対して自動トレースを提供します (Boto3/Botocore を使用)。

###トレース対象メソッド

Amazon Bedrock エージェントインテグレーションは、以下のメソッドをインスツルメントします。

Invoke Agent: InvokeAgent (ddtrace>=3.10.0 が必要)

Amazon Bedrock エージェントインテグレーションは、デフォルトでは、全体の InvokeAgent メソッドのみをトレースします。エージェント内のステップをトレースするには、enableTrace=True を InvokeAgent リクエストパラメーターに設定する必要があります。

Anthropic

Anthropic インテグレーションは、Anthropic Python SDK のチャットメッセージ呼び出しに対して自動トレースを提供します。

###トレース対象メソッド

Anthropic インテグレーションは、以下のメソッドをインスツルメントします。

チャットメッセージ (ストリーミングされた呼び出しを含む): Anthropic().messages.create()、AsyncAnthropic().messages.create() ストリーミングされたチャットメッセージ： Anthropic().messages.stream()、AsyncAnthropic().messages.stream()

Anthropic インテグレーションは、Anthropic Node.js SDK のチャットメッセージ呼び出しの自動トレースを提供します。

###トレース対象メソッド

Anthropic インテグレーションは、以下のメソッドをインスツルメントします。

チャットメッセージ (ストリーミングされた呼び出しを含む): anthropic.messages.create() ストリーミングされたチャットメッセージ： anthropic.messages.stream()

CrewAI

CrewAI インテグレーションは、CrewAI の Python SDK を通じて行われるタスク/エージェント/ツールの呼び出しを含む Crew キックオフの実行を自動的にトレースします。

###トレース対象メソッド

CrewAI インテグレーションは、以下のメソッドをインスツルメントします。

Crew キックオフ: crew.kickoff() crew.kickoff_async() crew.kickoff_for_each() crew.kickoff_for_each_async()

タスク実行: task.execute_sync() task.execute_async()

エージェント実行: agent.execute_task()

ツール呼び出し: tool.invoke()

Google ADK

Google ADK インテグレーションは、Google の ADK Python SDK を通じて行われるエージェントの実行、ツールの呼び出し、およびコードの実行を自動的にトレースします。

###トレース対象メソッド

Google ADK インテグレーションは、以下のメソッドをインスツルメントします。

Agent Runs Tool Calls コードの実行

run_live と run_async の両方のメソッドがサポートされています。

Google GenAI

Google GenAI インテグレーションは、Google GenAI Python SDK 内のメソッドを自動的にトレースします。

注意: Google GenAI Python SDK は Google GenerativeAI SDK の後継であり、Gemini Developer API と Vertex の両方に対応しています。

###トレース対象メソッド

Google GenAI インテグレーションは、以下のメソッドをインスツルメントします。

コンテンツ生成 (ストリーミング呼び出しを含む): models.generate_content() (chat.send_message() もキャプチャ) aio.models.generate_content() (aio.chat.send_message() もキャプチャ) コンテンツ埋め込み models.embed_content() aio.models.embed_content()

Google GenAI インテグレーションは、@google/genai パッケージをインスツルメントすることにより、Google GenAI Node.js SDK 内のメソッドを自動的にトレースします。

注意: Google GenAI Node.js SDK は Google GenerativeAI SDK の後継であり、Gemini Developer API と Vertex の両方に対応しています。

###トレース対象メソッド

Google GenAI インテグレーションは、以下のメソッドをインスツルメントします。

コンテンツ生成 (ストリーミング呼び出しを含む) コンテンツ埋め込み

LangChain

LangChain インテグレーションは、LangChain Python SDK の LLM、チャットモデル、チェーン呼び出しの自動トレースを提供します。

###トレース対象メソッド

LangChain インテグレーションは、以下のメソッドをインスツルメントします。

LLMs: llm.invoke()、llm.ainvoke() llm.stream()、llm.astream() チャットモデル chat_model.invoke()、chat_model.ainvoke() chat_model.stream()、chat_model.astream() Chains/LCEL chain.invoke()、chain.ainvoke() chain.batch()、chain.abatch() chain.stream()、chain.astream() Embeddings OpenAI : OpenAIEmbeddings.embed_documents(), OpenAIEmbeddings.embed_query() Tools BaseTool.invoke()、BaseTool.ainvoke() Retrieval langchain_community.<vectorstore>.similarity_search() langchain_pinecone.similarity_search() プロンプトテンプレート BasePromptTemplate.invoke()、BasePromptTemplate.ainvoke()

最良の結果を得るために、テンプレートに意味のある名前の変数を割り当ててください。自動インスツルメンテーションは、これらの名前を使用してプロンプトを特定します。

# "translation_template" will be used to identify the template in Datadog
translation_template = PromptTemplate.from_template("Translate {text} to {language}")
chain = translation_template | llm

LangChain インテグレーションは、LangChain Node.js SDK のLLM、チャットモデル、チェーン、および OpenAI 埋め込みモデルの呼び出しに対して自動トレースを提供します。

###トレース対象メソッド

LangChain インテグレーションは、以下のメソッドをインスツルメントします。

LLMs: llm.invoke() チャットモデル chat_model.invoke() Chains chain.invoke() chain.batch() Embeddings embeddings.embedQuery() embeddings.embedDocuments()

LangGraph

LangGraph インテグレーションは、LangGraph Python SDK を通じて行われた Pregel/CompiledGraph および RunnableSeq (node) の呼び出しを自動的にトレースします。

###トレース対象メソッド

LangGraph インテグレーションは、以下のメソッドの同期および非同期バージョンをインスツルメントします。

CompiledGraph.invoke()、Pregel.invoke()、CompiledGraph.stream()、Pregel.stream() RunnableSeq.invoke()

LiteLLM

LiteLLM インテグレーションは、LiteLLM Python SDK およびプロキシサーバールーター呼び出しの自動トレースを提供します。

###トレース対象メソッド

LiteLLM インテグレーションは、以下のメソッドをインスツルメントします。

チャット完了 (ストリーミング呼び出しを含む): litellm.completion litellm.acompletion 完了 (ストリーミング呼び出しを含む): litellm.text_completion litellm.atext_completion ルーターチャット完了 (ストリーミング呼び出しを含む): router.Router.completion router.Router.acompletion ルーター完了 (ストリーミング呼び出しを含む): router.Router.text_completion router.Router.atext_completion

MCP

Model Context Protocol (MCP) インテグレーションは、MCP SDK におけるクライアントおよびサーバーツール呼び出しをインスツルメントします。

###トレース対象メソッド

MCP インテグレーションは、以下のメソッドをインスツルメントします。

クライアントツール呼び出し: mcp.client.session.ClientSession.call_tool

サーバーツール呼び出し: mcp.server.fastmcp.tools.tool_manager.ToolManager.call_tool

OpenAI、Azure OpenAI

OpenAI インテグレーションは、OpenAI Python SDK の完了エンドポイントおよびチャット完了エンドポイントに対して、OpenAI および Azure OpenAI への自動トレースを提供します。

###トレース対象メソッド

OpenAI インテグレーションは、ストリーミングされた呼び出しを含め、以下のメソッドをインスツルメントします。

完了: OpenAI().completions.create()、AzureOpenAI().completions.create() AsyncOpenAI().completions.create()、AsyncAzureOpenAI().completions.create() チャット完了: OpenAI().chat.completions.create()、AzureOpenAI().chat.completions.create() AsyncOpenAI().chat.completions.create()、AsyncAzureOpenAI().chat.completions.create() レスポンス: OpenAI().responses.create() AsyncOpenAI().responses.create() OpenAI().responses.parse() (現在のバージョン: ddtrace==3.17.0) AsyncOpenAI().responses.parse() (現在のバージョン: ddtrace==3.17.0) OpenAI Python SDK を通じて DeepSeek に対して行われた呼び出し (現在のバージョン: ddtrace==3.1.0)

OpenAI インテグレーションは、OpenAI Node.js SDK の完了エンドポイント、チャット完了エンドポイント、埋め込みエンドポイントに対して、OpenAI および Azure OpenAI への自動トレースを提供します。

###トレース対象メソッド

OpenAI インテグレーションは、ストリーミングされた呼び出しを含め、以下のメソッドをインスツルメントします。

完了: openai.completions.create() および azureopenai.completions.create() チャット完了: openai.chat.completions.create() および azureopenai.chat.completions.create() 埋め込み: openai.embeddings.create() および azureopenai.embeddings.create() OpenAI Node.js SDK を通じて DeepSeek に行われた呼び出し (現在のバージョン: ddtrace@5.42.0） Responses openai.responses.create() (現在のバージョン: ddtrace@5.76.0)

OpenAI インテグレーションは、OpenAI Java.js SDK の完了エンドポイント、チャット完了エンドポイント、埋め込みエンドポイント、応答エンドポイントに対して、OpenAI および Azure OpenAI への自動トレースを提供します。

###トレース対象メソッド

OpenAI インテグレーションは、ストリーミングされた呼び出しを含め、OpenAIClient 上の以下のメソッドをインスツルメントします。

完了: openAiClient.completions().create() openAiClient.completions().createStreaming() openAiClient.async().completions().create() openAiClient.async().completions().createStreaming() チャット完了: openAiClient.chat().completions().create() openAiClient.chat().completions().createStreaming() openAiClient.async().chat().completions().create() openAiClient.async().chat().completions().createStreaming() 埋め込み: openAiClient.embeddings().create() openAiClient.async().embeddings().create() 応答: openAiClient.responses().create() openAiClient.responses().createStreaming() openAiClient.async().responses().create() openAiClient.async().responses().createStreaming()

プロバイダー (OpenAI と Azure OpenAI の区別 )は、ClientOptions で設定された baseUrl に基づいて自動的に検出されます。すべてのメソッドは、ブロッキングおよび非同期 (CompletableFuture ベース) の形式の両方をサポートしています。

OpenAI Agent

OpenAI Agent インテグレーションは、組み込みトレースを OpenAI Agents SDK から変換します。 LLM Observability フォーマットに変換し、Datadog の LLM Observability製品に Datadog トレースプロセッサーを追加して送信します。

次の操作がサポートされています。 traces agent generation Datadog の OpenAI インテグレーションを使用 response guardrail handoff function custom

Pydantic AI

Pydantic AI インテグレーションは、Pydantic AI エージェントフレームワークを使用して行われるエージェント呼び出しとツール呼び出しをインスツルメントします。

###トレース対象メソッド

Pydantic AI インテグレーションは、以下のメソッドをインスツルメントします。

エージェント呼び出し (エージェントに関連するツールやツールセットを含む): agent.Agent.iter (agent.Agent.run と agent.Agent.run_sync もトレースします) agent.Agent.run_stream

Strands Agents

v1.11.0 以降、Strands Agents は、OpenTelemetry GenAI セマンティック規約 v1.37 に準拠したスパンをネイティブに発行し、Datadog LLM Observability が Datadog トレーサーを必要とせずに自動的に取り込むことができます。

セットアップ手順と完全な例については、Strands Agent を使用した OpenTelemetry インスツルメンテーションを参照してください。

Vercel AI SDK

Vercel AI SDK インテグレーションは、基盤となるコア Vercel AI SDK によって作成された OpenTelemetry スパンをインターセプトし、それを Datadog LLM Observability スパンに変換することによって、テキストおよびオブジェクト生成、埋め込み、ツール呼び出しを自動的にトレースします。

###トレース対象メソッドテキスト生成: generateText streamText オブジェクト生成: generateObject streamObject 埋め込み: embed embedMany ツール呼び出し: tool.execute

Vercel AI Core SDK テレメトリ

このインテグレーションは、experimental_telemetryオプションの下で追跡された各メソッドに渡されたトレーサーを自動的にパッチします。experimental_telemetry 構成が渡されない場合、インテグレーションは LLM Observability のスパンを送信できるようにそれを有効にします。

require('dd-trace').init({
  llmobs: {
    mlApp: 'my-ml-app',
  }
});

const { generateText } = require('ai');
const { openai } = require('@ai-sdk/openai');

async function main () {
  let result = await generateText({
    model: openai('gpt-4o'),
    ...
    experimental_telemetry: {
      isEnabled: true,
      tracer: someTracerProvider.getTracer('ai'), // this tracer will be patched to format and send created spans to Datadog LLM Observability
    }
  });

  result = await generateText({
    model: openai('gpt-4o'),
    ...
  }); // since no tracer is passed in, the integration will enable it to still send LLM Observability spans
}

注意: experimental_telemetry.isEnabled が false に設定されている場合、インテグレーションはそれをオンにせず、LLM Observability にスパンを送信しません。

Vertex AI

Vertex AI インテグレーションは、Google の Vertex AI Python SDK を通じて行われたコンテンツ生成とチャットメッセージ呼び出しを自動的に追跡します。

###トレース対象メソッド

Vertex AI インテグレーションは、以下のメソッドをインスツルメントします。

コンテンツ生成 (ストリーミングされた呼び出しを含む) model.generate_content() model.generate_content_async()

チャットメッセージ (ストリーミングされた呼び出しを含む): chat.send_message() chat.send_message_async()

Vertex AI インテグレーションは、Google の Vertex AI Node.js SDK を通じて行われたコンテンツ生成とチャットメッセージの呼び出しを自動的に追跡します。

###トレース対象メソッド

Vertex AI インテグレーションは、以下のメソッドをインスツルメントします。

コンテンツ生成: model.generateContent() model.generateContentStream() チャットメッセージ: chat.sendMessage() chat.sendMessageStream()

LLM インテグレーションの有効化/無効化

すべてのインテグレーションはデフォルトで有効になっています。

すべての LLM インテグレーションの無効化

incode SDK セットアップを使用し、integrations_enabled=False を指定してください。

例: すべての LLM インテグレーションを無効にする incode SDK セットアップ

from ddtrace.llmobs import LLMObs

LLMObs.enable(
  ml_app="<YOUR_ML_APP_NAME>",
  api_key="<YOUR_DATADOG_API_KEY>",
  integrations_enabled=False
)

incode SDK セットアップを使用し、plugins: falseを指定します。

例: すべての LLM インテグレーションを無効にする incode SDK セットアップ

const tracer = require('dd-trace').init({
  llmobs: { ... },
  plugins: false
});
const { llmobs } = tracer;

特定の LLM インテグレーションのみの有効化

incode SDK セットアップを使用し、integrations_enabled=False で全てのインテグレーションを無効にします。
特定のインテグレーションを手動で有効にするには、ddtrace.patch() を使用します。

例: LangChain インテグレーションのみを有効にする incode SDK セットアップ

from ddtrace import patch
from ddtrace.llmobs import LLMObs

LLMObs.enable(
  ml_app="<YOUR_ML_APP_NAME>",
  api_key="<YOUR_DATADOG_API_KEY>",
  integrations_enabled=False
)

patch(langchain=True)

incode SDK セットアップを使用し、plugins: false で全てのインテグレーションを無効にします。
特定のインテグレーションを手動で有効にするには、use() を使用します。

例: LangChain インテグレーションのみを有効にする incode SDK セットアップ

const tracer = require('dd-trace').init({
  llmobs: { ... },
  plugins: false
});
const { llmobs } = tracer;
tracer.use('langchain', true);

ライブラリのパッチ適用やスパンを開始するインテグレーションをより細かく制御するには、以下の環境変数を設定します。

DD_TRACE_DISABLED_PLUGINS: トレーサー初期化時に自動的に無効化されるインテグレーション名をカンマ区切りで指定する文字列
例: DD_TRACE_DISABLED_PLUGINS=openai,http
DD_TRACE_DISABLED_INSTRUMENTATIONS: トレーサーの初期化時にパッチが適用されないライブラリ名を、カンマ区切りで並べた文字列
例: DD_TRACE_DISABLED_INSTRUMENTATIONS=openai,http

##参考資料

お役に立つドキュメント、リンクや記事:

LLM Observability SDK リファレンスDOCUMENTATION