すべてのプロダクト
Search
ドキュメントセンター

Cloud Monitor:OpenTelemetry GenAI Utils による LLM アプリケーションのインストルメンテーション

最終更新日:Jul 02, 2026

生成 AI (GenAI) アプリケーションがカスタムフレームワークや多言語アーキテクチャを使用している場合、Application Real-Time Monitoring Service (ARMS) のプローブは、大規模言語モデル (LLM)、エージェント、またはツールコンポーネントへの呼び出しからテレメトリーデータを自動的に収集できないことがあります。OpenTelemetry GenAI Utils (GenAI Utils) は、手動インストルメンテーション ソリューションを提供します。これにより、アプリケーションコードから GenAI セマンティック規約に準拠した標準スパンを生成し、ARMS Tracing OpenTelemetry Edition にレポートできます。このガイドでは、Python を例に、環境設定からデータ検証までの統合プロセス全体を説明します。

ユースケース

大規模言語モデル (LLM) および AI エージェント アプリケーションが一般的になるにつれて、その開発と運用において可観測性の重要性がますます高まっています。エージェントとモデルコンテキストプロトコル (MCP) ツール間の複数ターンにわたる対話、vLLM や SGLang などの推論エンジンのスケジューリングトレース、トークン使用量や最初のトークンまでの時間 (TTFT) などの重要なメトリクスといった主要な情報を収集し、分析するための統一された方法が必要です。ARMS アプリケーションモニタリングは、典型的な GenAI シナリオ向けに、すぐに使えるプローブ機能をすでに提供しています。MCP プロトコルに基づくエンドツーエンドのトレースでは、Python プローブがコード変更なしで LangChain エージェントと MCP サーバーの完全な呼び出しチェーンをインストルメンテーションする方法を示しています。vLLM/SGLang 推論エンジンの可観測性に関するガイドでは、リクエストレベルのスパン、gen_ai.latency.* 属性、TTFT や TPOT などのメトリクスについて説明しています。しかし、カスタムフレームワーク、多言語アーキテクチャ、またはスパンの内容をきめ細かく制御する必要があるシナリオでは、LLM の呼び出し、エージェントのオーケストレーション、ツールの実行などの操作をアプリケーションコードで手動でインストルメンテーションする必要があります。GenAI Utils は、このような特定の状況のために設計されています。

GenAI Utils は、アプリケーションモニタリングのプローブを置き換えるものではなく、補完するものです。プローブは、LangChain、vLLM、MCP などの既知のフレームワークをノーコードまたはローコードのアプローチで自動的にインストルメンテーションするため、標準化されたデプロイに最適です。対照的に、GenAI Utils はアプリケーションコードから Handler API を明示的に呼び出す必要があり、カスタムエージェント フレームワーク、カスタムスパン属性を必要とするシナリオ、またはプローブがまだカバーしていない統合に適しています。両方の方法で生成されたテレメトリーデータは、同じ GenAI セマンティック規約に従っており、ARMS コンソールまたは任意の OpenTelemetry 互換のバックエンドでまとめて分析できます。

仕組み

GenAI Utils は、生成 AI オペレーションのための共有テレメトリライブラリです。そのコア機能は、LLM 推論、エージェントコール、埋め込み、ツールの実行、検索などのオペレーションを、OpenTelemetry GenAI セマンティック規約に従う標準の Span、Event、およびメトリクスにマッピングすることです。また、start、stop、fail などの統一された一連のライフサイクル管理 API も提供します。

課題

解決策

フレームワークごとにトレースフィールドの定義が異なり、クロスプラットフォーム分析が困難です。

gen_ai.system、gen_ai.request.model、gen_ai.usage.* などの標準属性を使用してデータを統一します。

手動でのスパン作成では、トークン使用量や TTFT などの重要な情報が欠落する可能性があります。

データ収集ロジックをカプセル化する TelemetryHandler を提供します。

エージェント、ツール、検索のシナリオに関する統一された規約がありません。

invoke_agent、execute_tool、retrieval などのオペレーションのサポートを拡張します。

メッセージ内容の収集とプライバシーコンプライアンスの両立。

OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT などの環境変数を使用して、柔軟に制御できます。

OpenTelemetry コミュニティは、最初に Python エコシステムでリファレンス実装である opentelemetry-util-genai をリリースしました。その後、Java、Go、Node.js 向けに同等の実装がリリースされ、それぞれが同じ API 設計とセマンティック規約に従っています。

典型的なデータフローは次のとおりです:

アプリケーションコード + GenAI Utils (スパンを生成)
        ↓
OpenTelemetry SDK / エクスポーター (エンドポイントと認証を設定)
        ↓
ARMS Tracing OpenTelemetry Edition
        ↓
ARMS コンソールのトレースエクスプローラー

前提条件

GenAI Utils は、セマンティック規約に従うスパンとメトリクスを生成します。しかし、このデータを ARMS Tracing OpenTelemetry Edition にレポートし、コンソールで表示するには、OpenTelemetry SDK とエクスポーターも設定する必要があります。アプリケーションコードを記述する前に、次の前提条件を満たしてください:

  1. ARMS Tracing OpenTelemetry Edition サービスを有効化してください。

  2. お使いのリージョンのエンドポイントドメイン、ポート、認証トークンを取得してください。

  3. OTLP などのプロトコルを介して ARMS にトレースデータをレポートするように、OpenTelemetry SDK またはコレクターを設定してください。

統合プロセス、さまざまなリージョンのエンドポイント、ポートとプロトコルのマッピング、および OpenTelemetry SDK またはコレクターの設定方法の詳細については、「統合ガイド」をご参照ください。このドキュメントでは、次の内容について説明しています:

  • 前提条件:エンドポイント、ポート、認証トークンの取得方法。

  • OpenTelemetry との統合:OpenTelemetry SDK またはコレクターを使用してデータレポートを設定する方法。

  • その他のクライアント統合方法 (Jaeger、Zipkin、SkyWalking など)。

アプリケーションが Alibaba Cloud の外部にデプロイされている場合は、「統合ガイド」に記載されているように、必要なポートを開き、ドメインアクセス権限を付与する必要もあります。

クイックスタート (Python の例)

Python は、OpenTelemetry エコシステムで GenAI Utils を搭載した最初の言語であり、その API 設計は他の言語での実装の参考となっています。次の例では、TelemetryHandler を使用して LLM コール用の標準の GenAI Span を収集する方法を示します。

GenAI Utils と、それに依存する OpenTelemetry SDK およびエクスポーターパッケージをインストールしてください:

pip install opentelemetry-util-genai
重要

次のコードを実行する前に、「前提条件」セクションで説明されているように、OpenTelemetry TracerProvider とエクスポーターを初期化および設定する必要があります。これにより、スパンデータが ARMS にレポートされるようになります。

from opentelemetry.util.genai.handler import get_telemetry_handler
from opentelemetry.util.genai.types import InputMessage, LLMInvocation, OutputMessage, Text

handler = get_telemetry_handler()

invocation = LLMInvocation(
    provider="openai",
    request_model="gpt-4o-mini",
    input_messages=[
        InputMessage(role="user", parts=[Text(content="Explain OpenTelemetry in one sentence.")]),
    ],
)
with handler.llm(invocation) as inv:
    # ここで実際のモデル API を呼び出します
    inv.output_messages = [
        OutputMessage(
            role="assistant",
            parts=[Text(content="OpenTelemetry is an open standard and implementation for observability.")],
            finish_reason="stop",
        )
    ]
    inv.input_tokens = 10
    inv.output_tokens = 20

統合手順の概要は次のとおりです。依存関係をインストール → OpenTelemetry Provider を初期化 → ハンドラーを作成 → モデル API 呼び出しを with handler.llm(...) でラップします。より多くの操作タイプを収集したり、メッセージ内容の収集ポリシーを設定したりするには、お使いのプログラミング言語の詳細ドキュメントをご参照ください。

データレポートの検証

サンプルコードを実行した後、ARMS コンソールにログインします。[トレースエクスプローラー] ページで、報告された GenAI スパンを表示します。スパンには、コードで設定された provider、request_model、およびトークン使用量の値に対応する、 gen_ai.system、gen_ai.request.model、gen_ai.usage.* などの標準属性が含まれています。

GenAI Utils のドキュメント

各言語の実装は、同じセマンティック規約と Handler API 設計パターンに従っています。インストール手順、完全な API リファレンス、およびコード例については、お使いの言語のドキュメントをご参照ください:

言語

ドキュメント

Java

ドキュメント

Python

ドキュメント

Go

ドキュメント

Node.js

ドキュメント