アプリケーションを Application Real-Time Monitoring Service (ARMS) と連携させると、エージェントは一般的な AI フレームワークを自動的に計装し、コードを変更することなくトレースデータを収集します。ビジネスメソッドをトレースに含める必要がある場合は、loongsuite-otel-util-genai と OpenTelemetry SDK を使用してカスタム計装を実装できます。このトピックでは、loongsuite-otel-util-genai と OpenTelemetry Python SDK を使用してカスタム計装を実装し、カスタム属性を追加する方法について説明します。
ARMS エージェントがサポートする AI コンポーネントとフレームワークについては、以下をご参照ください。
前提条件
依存関係の追加
pip install -U "loongsuite-otel-util-genai>=0.6.1"インストール後、opentelemetry.util.genai パッケージと ExtendedTelemetryHandler などの拡張インターフェイスが利用可能になります。バージョン 0.6.1 以降では、エージェントスパンのライフサイクル中に、エージェント名がダウンストリームの GenAI 子スパンに自動的に伝播されます。詳細については、loongsuite-otel-util-genai ドキュメントをご参照ください。
Langfuse を使用しており、「Langfuse SDK と Alibaba Cloud Python エージェントの同時連携」で説明されているように OpenTelemetry API の計装を無効にしている場合は、このトピックのすべての from opentelemetry.xxx import 文 (付録の例を含む) のモジュールパスに aliyun. プレフィックスを追加してください。例えば、from opentelemetry.trace import get_tracer を from aliyun.opentelemetry.trace import get_tracer に変更します。
loongsuite-otel-util-genai と OpenTelemetry SDK の使用
loongsuite-otel-util-genai と OpenTelemetry SDK を使用すると、以下のことが可能になります。
Entry、Agent、Tool、ReAct Step などの GenAI セマンティックスパンの作成
OpenTelemetry SDK を使用した計装の追加とカスタムスパンの生成
スパンへのカスタム属性の追加
現在のトレースコンテキストの取得と traceId の出力
用語
スパン:リクエスト内の特定の操作 (LLM 呼び出しやツール実行など) です。
SpanContext:traceId や spanId などの情報を含むトレースのコンテキストです。
属性:モデル名やトークン使用量などのキー情報を記録するために使用されるスパン上の追加フィールドです。
ハンドラ:loongsuite-otel-util-genai が提供する
ExtendedTelemetryHandlerで、GenAI セマンティック規則に準拠したスパンを作成するために使用されます。
次の表は、loongsuite-otel-util-genai がサポートするすべてのスパンタイプの一覧です。このトピックでは、Entry、Agent、Tool、ReAct Step、LLM スパンの使用法に焦点を当てます。Embedding、Retrieval、Rerank、Memory などの他のタイプの詳細な使用法については、loongsuite-otel-util-genai の完全なドキュメントをご参照ください。
タイプ | オペレーション名 | 説明 |
Entry |
| アプリケーションのエントリポイントです。session_id、user_id、および完全なインタラクション詳細を保持します。 |
Agent |
| トークン使用量を集計するエージェント呼び出しです。 |
Tool |
| ツールまたは関数の実行です。 |
ReAct Step |
| ReAct ループの 1 回の反復です。 |
LLM |
| LLM チャットで、通常はプローブによって自動的に収集されます。 |
Embedding |
| ベクトル埋め込み操作です。 |
Retrieval |
| Retrieval-Augmented Generation (RAG) における取得操作です。 |
Rerank |
| リランク操作です。 |
Memory |
| メモリの読み書き操作です。 |
以下のセクションでは、各スパンタイプを計装するためのステップバイステップの手順と独立したコードスニペットを提供します。実行可能な完全なコード例については、このトピックの最後にある付録をご参照ください。
ハンドラインスタンスは、必ず get_extended_telemetry_handler() を使用して取得してください。TelemetryHandler を直接インスタンス化しないでください。ARMS プローブは get_extended_telemetry_handler() とのみ互換性があります。TelemetryHandler を直接インスタンス化すると、環境変数の互換性の問題が発生する可能性があります。
カスタム計装を追加する際は、「LLM トレースフィールド定義」のセマンティック規則に従う必要があります。トークン統計やセッション分析などの AI アプリケーション可観測性機能は、データ処理とレンダリングのためにこれらの規則に依存しています。スパン属性が仕様に準拠していない場合、関連データがコンソールで正しく表示されない可能性があります。リソース属性 acs.arms.service.feature=genai_app と gen_ai.instrumentation.sdk.name=loongsuite-genai-utils には特に注意してください。これらの属性は LLM トレースフィールド定義に由来し、アプリケーションが AI アプリケーション可観測性に対して有効であり、データソースが loongsuite-genai-utils であることを示します。これらの属性は、OTEL_RESOURCE_ATTRIBUTES 環境変数または OpenTelemetry Resource オブジェクトを使用して設定してください。通常のスパン属性として設定しないでください。
export OTEL_RESOURCE_ATTRIBUTES="acs.arms.service.feature=genai_app,gen_ai.instrumentation.sdk.name=loongsuite-genai-utils"アプリケーションに既に OTEL_RESOURCE_ATTRIBUTES 環境変数が設定されている場合は、service.name などの既存のリソース情報を上書きしないように、カンマを使用して前述のキーと値のペアを追加してください。
1. ハンドラとトレーサーの取得
get_extended_telemetry_handler() を使用して loongsuite-otel-util-genai からシングルトンハンドラを取得し、get_tracer(__name__) を使用して OpenTelemetry SDK からトレーサーを取得します。ハンドラは GenAI セマンティックスパンの作成に、トレーサーはカスタムビジネススパンの作成に使用します。
from opentelemetry.util.genai.extended_handler import get_extended_telemetry_handler
from opentelemetry.util.genai.extended_types import (
EntryInvocation,
ExecuteToolInvocation,
InvokeAgentInvocation,
ReactStepInvocation,
)
from opentelemetry.util.genai.types import Error, InputMessage, OutputMessage, Text
from opentelemetry.trace import get_tracer
handler = get_extended_telemetry_handler()
tracer = get_tracer(__name__)
ハンドラは 2 つの方法で使用できます。
コンテキストマネージャー (例:
with handler.entry(inv)):スパンのライフサイクルを自動的に管理するため、このアプローチを推奨します。start/stop/fail API (例:
handler.start_entry(inv)、handler.stop_entry(inv)、またはhandler.fail_entry(inv, error)):with文を使用できない非同期、コールバックベース、またはストリーミングシナリオでこのアプローチを使用します。
2. Entry スパンの作成
リクエストのエントリポイントで Entry スパンを作成します。このスパンは session_id と user_id を保持し、input_messages を通じてユーザー入力を記録します。ストリーミング応答が完了したら、出力コンテンツを連結して output_messages に設定し、stop_entry を呼び出してスパンを終了します。これにより、コンソールでリクエストの完全な入力と最終出力を直接表示できます。
entry_inv = EntryInvocation(
session_id=req.session_id or str(uuid.uuid4()),
user_id=req.user_id or "anonymous",
input_messages=[
InputMessage(role="user", parts=[Text(content=req.topic)]),
],
)
def event_generator():
handler.start_entry(entry_inv)
output_chunks: list[str] = [ ]
try:
for chunk in run_agent_stream(topic=req.topic):
output_chunks.append(chunk)
yield f"data: {json.dumps({'content': chunk}, ensure_ascii=False)}\n\n"
yield "data: [DONE]\n\n"
except Exception as exc:
handler.fail_entry(entry_inv, Error(message=str(exc), type=type(exc)))
yield f"data: {json.dumps({'error': str(exc)}, ensure_ascii=False)}\n\n"
return
entry_inv.output_messages = [
OutputMessage(
role="assistant",
parts=[Text(content="".join(output_chunks))],
finish_reason="stop",
),
]
handler.stop_entry(entry_inv)
3. Agent スパンの作成
start_invoke_agent を使用して Agent スパンを作成し、エージェント名、モデル、および説明を記録します。Agent スパンは、トレース全体のルート GenAI スパンとして機能します。後続の ReAct Step、LLM、および Tool の呼び出しは、その子スパンになります。
loongsuite-otel-util-genai 0.6.1 以降、start_invoke_agent を呼び出す際に InvokeAgentInvocation.agent_name が設定されていると、ユーティリティは自動的に gen_ai.agent.name を OpenTelemetry Baggage に書き込みます。この Agent スパンのライフサイクル内で、LoongSuite GenAI プローブまたはこのユーティリティによって作成される LLM、Tool、Embedding、Retrieval、Rerank、Memory、ReAct Step などの他の GenAI 子スパンは、この属性を自動的に継承します。各子スパンでエージェント名を手動で設定する必要はありません。OpenTelemetry SDK を使用して作成された通常のカスタムビジネススパンは、この GenAI 属性を自動的に継承しません。ビジネス属性を記録するには、引き続き span.set_attribute() を使用してください。
invocation = InvokeAgentInvocation(
provider="dashscope",
agent_name="TechContentAgent",
agent_description="Technical content generation assistant",
request_model="qwen-plus",
)
total_input_tokens = 0
total_output_tokens = 0
handler.start_invoke_agent(invocation)
try:
# ... コアエージェントロジック (ReAct ループ) ...
invocation.input_tokens = total_input_tokens
invocation.output_tokens = total_output_tokens
handler.stop_invoke_agent(invocation)
except Exception:
handler.fail_invoke_agent(invocation, Error(message="agent failed", type=RuntimeError))
raise
エージェントの実行が完了したら、蓄積された total_input_tokens と total_output_tokens を Agent スパンに書き込み、集計されたトークンメトリック統計を有効にします。
4. ReAct Step スパンの作成
ReAct 推論ループの各反復に対して ReAct Step スパンを作成し、現在の反復 round を渡します。反復が終了したら、さらに反復が必要な場合は finish_reason を continue に設定し、最終的な回答の場合は stop に設定します。この例では、各反復の LLM 呼び出しは ARMS プローブによって自動的に計装されるため、手動での作成は不要です。
step_inv = ReactStepInvocation(round=iteration + 1)
handler.start_react_step(step_inv)
try:
response = client.chat.completions.create(
model="qwen-plus",
messages=messages,
tools=TOOL_DEFINITIONS,
)
# ... 応答を処理 ...
step_inv.finish_reason = "stop" # または "continue"
handler.stop_react_step(step_inv)
except Exception:
handler.fail_react_step(step_inv, Error(message="step failed", type=RuntimeError))
raise
5. Tool スパンの作成
モデルがツール呼び出しを返した場合、各 tool_call に対して Tool スパンを作成し、ツール名、呼び出し ID、入力引数、および結果を記録します。
tool_inv = ExecuteToolInvocation(
tool_name=tool_call.function.name,
tool_call_id=tool_call.id,
tool_call_arguments=tool_call.function.arguments,
tool_type="function",
)
handler.start_execute_tool(tool_inv)
try:
result = dispatch_tool(tool_name, tool_call.function.arguments)
tool_inv.tool_call_result = result
except Exception as exc:
handler.fail_execute_tool(tool_inv, error=Error(message=str(exc), type=type(exc)))
raise
else:
handler.stop_execute_tool(tool_inv)
6. ASR または TTS 用の LLM スパンの作成
ASR や TTS などの音声モデル呼び出しで、音声の持続時間、認識レイテンシ、初回チャンクレイテンシなどのビジネス属性を追加する必要がある場合は、モデル呼び出し専用の LLM スパンを作成できます。ASR の場合は operation_name="transcribe" を設定します。TTS の場合は operation_name="synthesize_speech" を設定します。標準のトークンフィールドは、モデル API が実際にトークン使用量を返す場合にのみ設定してください。API がトークン使用量を返さない場合は、音声の持続時間、文字数、またはバイトサイズから gen_ai.usage.* 属性を推定しないでください。
def set_llm_attributes(invocation: LLMInvocation, attributes: dict) -> None:
attributes = {key: value for key, value in attributes.items() if value is not None}
invocation.attributes.update(attributes)
if invocation.span is not None:
invocation.span.set_attributes(attributes)
# ASR: 音声認識はテキストを出力します。LLM スパンを使用してモデル推論呼び出しを表します。
asr_invocation = LLMInvocation(
provider="dashscope",
request_model="paraformer-v2",
operation_name="transcribe",
output_type="text",
input_messages=[
InputMessage(
role="user",
parts=[Uri(mime_type="audio/wav", modality="audio", uri=audio_url)],
)
],
attributes={
"gen_ai.asr.channel": "dashscope_transcription_async",
"gen_ai.asr.input.source": "url",
},
)
with handler.llm(asr_invocation) as llm:
# ここで実際の ASR SDK を呼び出し、応答からタスク ID、文字起こしされたテキスト、使用量、タイムスタンプを取得します。
llm.response_id = asr_task_id
llm.output_messages = [
OutputMessage(role="assistant", parts=[Text(content=transcript_text)], finish_reason="stop")
]
llm.input_tokens = asr_usage.get("input_tokens")
llm.output_tokens = asr_usage.get("output_tokens")
set_llm_attributes(
llm,
{
"gen_ai.asr.success": True,
"gen_ai.asr.status": "SUCCEEDED",
"gen_ai.asr.audio.duration": asr_usage.get("duration"),
"gen_ai.asr.call.wall_time": asr_call_wall_time,
"gen_ai.asr.provider.processing.duration": asr_provider_processing_time,
"gen_ai.asr.audio_tokens": asr_usage.get("audio_tokens"),
},
)
# TTS: テキストが音声に合成されます。LLM スパンを使用してモデル推論呼び出しを表すことができます。
tts_invocation = LLMInvocation(
provider="dashscope",
request_model="qwen-tts",
operation_name="synthesize_speech",
output_type="audio",
input_messages=[InputMessage(role="user", parts=[Text(content=tts_text)])],
attributes={
"gen_ai.tts.channel": "qwen_tts_http",
"gen_ai.tts.voice": "Cherry",
"gen_ai.tts.input.text_length": len(tts_text),
},
)
with handler.llm(tts_invocation) as llm:
# ここで実際の TTS SDK を呼び出し、応答からリクエスト ID、音声 ID/URL、および使用量を取得します。
llm.response_id = tts_request_id
llm.input_tokens = tts_usage.get("input_tokens")
llm.output_tokens = tts_usage.get("output_tokens")
llm.output_messages = [
OutputMessage(role="assistant", parts=[Text(content=f"audio generated: {audio_id}")], finish_reason="stop")
]
set_llm_attributes(
llm,
{
"gen_ai.tts.success": True,
"gen_ai.tts.status": "SUCCEEDED",
"gen_ai.tts.audio.duration": generated_audio_duration,
"gen_ai.tts.call.wall_time": tts_call_wall_time,
"gen_ai.tts.first_audio.duration": first_audio_delay,
"gen_ai.tts.audio_tokens": (tts_usage.get("output_tokens_details") or {}).get("audio_tokens"),
"gen_ai.tts.usage.characters": tts_usage.get("characters"),
},
)
一般的な ASR/TTS フィールドは、その目的に基づいて区別します。gen_ai.asr.audio.duration は入力音声の持続時間を表し、gen_ai.asr.provider.processing.duration はサーバー側の認識時間を表します。gen_ai.tts.audio.duration は合成された音声の持続時間を表し、gen_ai.tts.first_audio.duration はストリーミング合成における最初の音声パケットまでの時間を表します。エンドツーエンドの呼び出し時間にはスパンの持続時間を使用するか、追加で gen_ai.asr.call.wall_time または gen_ai.tts.call.wall_time に書き込むことができます。実行可能な完全な例については、付録の asr_llm_span.py と tts_llm_span.py をご参照ください。
7. OpenTelemetry SDK を使用したカスタムスパンの作成
loongsuite-otel-util-genai が提供する GenAI セマンティックスパンに加えて、OpenTelemetry SDK の tracer.start_as_current_span() メソッドを使用してカスタムビジネススパンを作成し、GenAI スパンと組み合わせて使用することもできます。
以下の例は、カスタムスパンの 2 つの典型的なユースケースを示しています。
重複ツール検出
このプロセスは各 ReAct 反復の前に実行され、Counter を使用して各ツールが呼び出された回数をカウントし、検出結果を gen_ai.loop_detection.* 属性に書き込みます。重複が検出された場合、メッセージリストにシステムプロンプトが追加され、モデルが重複を避けるように誘導します。
def _check_duplicate_tools(
tool_usage_counter: Counter,
messages: list[dict[str, Any]],
) -> None:
duplicates = [name for name, count in tool_usage_counter.items() if count > 1]
has_duplicates = len(duplicates) > 0
with tracer.start_as_current_span("duplicate_tool_detection") as span:
span.set_attributes({
"gen_ai.loop_detection.detected": has_duplicates,
"gen_ai.loop_detection.duplicate_tools": str(duplicates) if has_duplicates else "[ ]",
"gen_ai.loop_detection.total_calls": sum(tool_usage_counter.values()),
"gen_ai.loop_detection.unique_tools": len(tool_usage_counter),
})
if has_duplicates:
details = ", ".join(f"{n}({tool_usage_counter[n]} times)" for n in duplicates)
messages.append({
"role": "system",
"content": f"[System Prompt] Duplicate tool calls detected: {details}. Please avoid calling them again.",
})
LLM 応答ループ検出
このプロセスは、各 LLM 応答の後に実行されます。現在の応答と前の応答のテキスト類似度を比較し、is_loop や overlap_ratio などのメトリックをスパン属性に書き込みます。ループが検出された場合 (テキストが同一であるか、重複率が 80% を超える場合)、finish_reason は loop_detected に設定され、エージェントは早期終了します。
def _check_response_loop(
current_content: str | None,
previous_content: str | None,
) -> bool:
cur = (current_content or "").strip()
prev = (previous_content or "").strip()
with tracer.start_as_current_span("response_loop_detection") as span:
if not prev or not cur:
span.set_attributes({
"gen_ai.loop_detection.is_loop": False,
"gen_ai.loop_detection.reason": "no_text_content",
})
return False
is_identical = cur == prev
longer = max(len(cur), len(prev))
common_prefix_len = sum(1 for a, b in zip(cur, prev) if a == b)
overlap_ratio = common_prefix_len / longer if longer > 0 else 0.0
is_loop = is_identical or overlap_ratio > 0.8
span.set_attributes({
"gen_ai.loop_detection.is_loop": is_loop,
"gen_ai.loop_detection.is_identical": is_identical,
"gen_ai.loop_detection.overlap_ratio": round(overlap_ratio, 2),
"gen_ai.loop_detection.current_length": len(cur),
"gen_ai.loop_detection.previous_length": len(prev),
})
return is_loop
カスタムスパンは LLM セマンティック規則に準拠していないため、コンソールのトレースビューで フルビュー に切り替えて表示する必要があります。
モニタリング詳細
Cloud Monitor 2.0 コンソールにログインし、ターゲットワークスペースを選択し、ナビゲーションウィンドウで[すべての機能] > [AI アプリケーションの可観測性]を選択します。
[AI アプリケーション一覧] ページには、統合されたアプリケーションが一覧表示されます。[アプリケーション名] をクリックすると、その詳細なモニタリングデータを表示できます。
計装結果
1. Entry スパンの詳細
Entry スパンには、gen_ai.session.id (一意のセッション ID) や gen_ai.user.id (ユーザー ID) などの主要な属性が表示されます。これらの属性を関数のエントリポイントで設定すると、LLM やツールスパンなどのダウンストリームスパンに自動的に伝播され、セッションおよびユーザー分析のためのデータ相関に役立ちます。Entry スパンには、gen_ai.input.messages (ユーザー入力) と gen_ai.output.messages (最終出力) も含まれており、コンソールでリクエストの完全なインタラクションを直接表示できます。
Entry スパンの詳細パネルには、gen_ai.session.id (一意のセッション ID) や gen_ai.user.id (ユーザー ID) などの主要な属性が含まれており、これらは関数のエントリポイントで設定された後、ダウンストリームの子スパンに自動的に伝播されます。パネルには、gen_ai.input.messages (ユーザーの入力メッセージの完全な内容) と gen_ai.output.messages (最終的なモデル出力メッセージの完全な内容) も表示されます。
2. Agent スパンの詳細
Agent スパンの詳細パネルでは、主要な属性として gen_ai.agent.name (TechContentAgent)、gen_ai.provider.name (dashscope)、gen_ai.request.model (qwen-plus)、およびエージェントレベルのトークン使用量の概要 (gen_ai.usage.input_tokens (3982)、gen_ai.usage.output_tokens (884)、gen_ai.usage.total_tokens (4866)) が含まれます。
3. Tool スパンの詳細
Tool スパンには、ツール名、その入力パラメーター、およびツール呼び出し結果が表示されます。これにより、ツール呼び出しの詳細が提供されます。execute_tool generate_seo_keywords を選択すると、右側の詳細パネルにツール名 (Tool: $generate_seo_keywords)、ツールタイプ (Tool Type: function)、ツール呼び出し引数 (Tool Call Arguments、例:{"topic": "CMS 2.0 AI alert noise reduction"})、およびツール結果 (Tool Result) が表示されます。これにより、ツール呼び出しの入出力が期待通りであるかを簡単にトラブルシューティングできます。
4. LLM スパンの詳細
LLM スパンは、OpenAI や DashScope などのサポートされているコンポーネントに対して ARMS エージェントによって自動的に収集されるか、このドキュメントの例で示されているように LLMInvocation を使用して手動で作成できます。自動収集は、一般的なテキストベースの対話モデルへの呼び出しに使用されます。ASR や TTS など、エージェントによってまだ自動的にカバーされていないモデル呼び出しや、ビジネス属性を追加する必要がある場合は、手動で LLM スパンを作成し、gen_ai.asr.* や gen_ai.tts.* などのカスタム属性を追加できます。
LLM スパンの詳細パネルには、アプリケーション名、API エンドポイント、IP アドレス、開始時刻と終了時刻、spanId、parentSpanId、ステータスコードなどの基本情報が表示されます。[追加情報] タブでは、応答内容、カスタム属性、および呼び出しのトークン使用量を確認できます。
5. カスタムスパンの詳細
サンプルコードでは、OpenTelemetry SDK を使用して 2 つのカスタムビジネススパンを作成し、カスタム計装と GenAI セマンティックスパンを組み合わせる方法を示しています。これらのカスタムスパンは GenAI セマンティクスの一部ではないため、表示するにはフルビューを開く必要があります。
duplicate_tool_detection:このスパンは、各 ReAct 反復の前に実行され、エージェントが繰り返しツールを呼び出すループに陥っていないかを検出します。スパンの属性には、重複が検出されたかどうか、重複したツールのリスト、呼び出しの総数、およびユニークなツールの数が記録されます。これにより、ARMS でエージェントのツール呼び出しループを迅速に特定できます。
ARMS トレース詳細ページで、duplicate_tool_detection スパンをクリックすると、右側の詳細パネルにループ検出属性が表示されます。属性キーは
gen_ai.loop_detection.detected、gen_ai.loop_detection.duplicate_tools、gen_ai.loop_detection.total_calls、gen_ai.loop_detection.unique_tools、およびgen_ai.loop_detection.detailsです。4 つのツール呼び出しがすべてユニークな場合、detectedはfalseで、duplicate_toolsは空の配列[]になります。response_loop_detection:このスパンは、各 LLM 応答の後に実行され、モデルが非常に類似したコンテンツを繰り返し返していないかを検出します。スパンの属性には、ループが特定されたかどうか、テキストが同一であるかどうか、重複率、および現在と前の応答のテキスト長が記録されます。これにより、モデルが反復的な出力ループに陥っている例外的なシナリオをトラブルシューティングするのに役立ちます。
トレース詳細ページのウォーターフォールビューで、response_loop_detection スパンを選択します。右側の属性パネルに特定の属性が表示されます。例えば、
gen_ai.loop_detection.is_loop=falseはループが検出されていないことを示し、gen_ai.loop_detection.reason=no_text_contentは理由がテキストコンテンツなしであることを示します。
参考資料
埋め込み、取得、リランク、メモリなどの loongsuite-otel-util-genai スパンタイプの詳細な使用法については、loongsuite-otel-util-genai の完全なドキュメントをご参照ください。