このチュートリアルでは、Python LLM アプリケーション用に GenAI エントリースパンを作成し、OpenTelemetry バゲージを使用してカスタムビジネス属性をコールチェーン内のすべてのスパンに伝播させる方法を説明します。これにより、最終的に アプリケーションモニタリング コンソールで `user_id`、`session_id`、`tenant_id` などの属性に基づいてトレースをフィルター処理したり集計したりできるようになります。
後続スパンでビジネス属性が失われる理由
大規模言語モデル (LLM) アプリケーションでは、単一のユーザーリクエストが、エントリーサービス → エージェントオーケストレーション → 複数のモデル呼び出し → ツール/取得の呼び出し、というコールチェーン全体をトリガーすることがよくあります。このチェーンは、多数のスパンを生成します。デフォルトでは、user_id、session_id、テナント、チャンネル、実験グループなどのビジネスディメンションは、エントリーポイントにのみ存在します。後続のスパンはこれらの属性を持たないため、問題のトラブルシューティングや、ビジネスディメンションごとの集計分析が困難になります。
このチュートリアルでは、次の 2 つの機能について説明します。
GenAI エントリスパンの作成 — 呼び出しチェーン全体に統一されたエントリスパンを作成し、
user_idとsession_idを渡します。これらの属性は、チェーン内のすべての子スパンの属性に自動的に伝播されます。ビジネス属性のカラーリング —
user_idおよびsession_id以外のカスタムビジネス属性については、現在のコンテキストで バゲージ を設定し、コンソールで [収集対象のバゲージリスト] を設定して、これらの属性をチェーン内のすべてのスパンの属性に伝播 (「カラーリング」) させます。
前提条件
項目 | 要件 |
エージェントバージョン | 3.1.0 以降 (「収集対象のバゲージリスト」機能は 3.1.0 から有効になり、再起動は不要です) |
依存ライブラリ | loongsuite-otel-util-genai がインストールされていること (エントリースパンの作成に使用) |
連携状態 | アプリケーションが OpenTelemetry 向けマネージドサービスに接続済みであること。コンソールでトレースデータを表示できる必要があります |
ステップ 1:GenAI エントリースパンの作成と user_id/session_id の受け渡し
loongsuite-otel-util-genai を使用した完全なイベントトラッキングの詳細については、「loongsuite-otel-util-genai と OpenTelemetry SDK を使用してカスタムイベントトラッキングを追加する」をご参照ください。ビジネスエントリーポイントで Entry Span を作成し、作成時に user_id と session_id を渡します。
user_id と session_id を渡して EntryInvocation を作成し、handler.start_entry() を呼び出してエントリー スパンを開始します。ビジネスロジックが完了したら、handler.stop_entry() を呼び出して完了させます。例外が発生した場合は、handler.fail_entry() を呼び出してエラーを記録します。
from opentelemetry import baggage, context
from opentelemetry.util.genai.extended_handler import get_extended_telemetry_handler
from opentelemetry.util.genai.extended_types import EntryInvocation
from opentelemetry.util.genai.types import Error, InputMessage, OutputMessage, Text
async def generate_stream(req: GenerateRequest) -> StreamingResponse:
handler = get_extended_telemetry_handler()
user_prompt = f"Audience: {req.target_audience}, Topic: {req.topic}"
# エントリースパン:user_id と session_id を渡します。両方とも、後続のすべての子スパンに自動的に渡されます。
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=user_prompt)]),
],
)
def event_generator():
# ===== エントリースパンの作成 (user_id / session_id を含む) =====
# genai util は user_id と session_id を後続のすべての子スパンに自動的に渡します。コンソールでの設定は不要です。
# エントリースパンはカスタムバゲージを持つコンテキストで開始されるため、バゲージ属性も持ちます。
handler.start_entry(entry_inv)
output_chunks: list[str] = []
try:
try:
for chunk in run_marketing_agent_stream(
content_type=req.content_type,
product=req.product,
target_audience=req.target_audience,
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)),
)
return
entry_inv.output_messages = [
OutputMessage(
role="assistant",
parts=[Text(content="".join(output_chunks))],
finish_reason="stop",
),
]
handler.stop_entry(entry_inv)
finally:
# バゲージが後続のリクエストに漏れるのを防ぐため、速やかにコンテキストをデタッチします。
context.detach(token)
return StreamingResponse(event_generator(), media_type="text/event-stream")結果: user_id と session_id は、genai util によってバゲージに自動的に書き込まれ、現在のチェーン内のすべての子スパンの属性に、「デフォルトで収集される」属性として伝播されます。追加のコンソール構成は不要です。
ステップ 2:カスタムビジネス属性の伝播 (カラーリング)
user_id や session_id に加えて、テナント、チャンネル、モデルバージョン、実験グループ、注文番号などでチェーンを分析することもできます。これらのカスタム属性には 2 つのステップが必要です。(1) コードにバゲージを書き込む、(2) コンソールで収集するバゲージキーを宣言する。
2.1 コードでのバゲージの設定
カラーリングを行いたいポイント (通常はエントリースパンの前) で、ビジネス属性を現在のコンテキストのバゲージに書き込みます。
from opentelemetry import baggage, context
ctx = baggage.set_baggage("tenant_id", req.tenant_id or "default")
ctx = baggage.set_baggage("channel", req.channel or "web", context=ctx)
token = context.attach(ctx)バゲージは、プロセス間の呼び出しにおいてリクエストヘッダーと共に伝播します。サービスをまたいだ後続のアプリケーションもこれらの属性を収集できます (後続のアプリケーションもコンソールで設定を完了させる必要があります)。
2.2 コンソールでのバゲージ収集リストの設定
コードでバゲージを書き込んだ後、コンソールでどのバゲージキーをスパン属性として収集するかを宣言します。パフォーマンスとデータ量を考慮して、エージェントはデフォルトではバゲージを収集しません。
アプリケーションの エージェント収集設定 セクションに移動し、収集対象のバゲージリスト フィールドに、カラーリングが必要なバゲージキーを入力します。複数のキーはカンマで区切ります。
tenant_id,channel入力された baggageKey がすでに存在する場合、それらは対応するスパンの属性に追加されます。
構成を保存すると、即時に有効になります。新しく生成されたチェーンでは、コンテキストに tenant_id または channel を含むすべてのスパンに、対応する属性が付与されます。
完全な例
以下の例は、両方の機能をまとめて示しています。実行順序に注意してください:最初にバゲージを設定し、次にエントリースパンを作成します。これにより、エントリースパンとそのすべての子スパンが、カスタムバゲージを含むコンテキスト内で作成されることが保証されます。
import json
import uuid
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from pydantic import BaseModel
from opentelemetry import baggage, context
from opentelemetry.util.genai.extended_handler import get_extended_telemetry_handler
from opentelemetry.util.genai.extended_types import EntryInvocation
from opentelemetry.util.genai.types import Error, InputMessage, OutputMessage, Text
from agent import run_marketing_agent_stream
app = FastAPI(title="Cloud Product Technical Content Generation Assistant")
class GenerateRequest(BaseModel):
content_type: str = "blog"
product: str = "CMS"
target_audience: str = "O&M Engineer"
topic: str = ""
session_id: str = ""
user_id: str = ""
# 以下は、バゲージプロパティによるタグ付けをデモンストレーションするためのカスタムビジネスプロパティです。
tenant_id: str = ""
channel: str = ""
@app.post("/api/v1/generate/stream")
async def generate_stream(req: GenerateRequest) -> StreamingResponse:
handler = get_extended_telemetry_handler()
user_prompt = f"Audience: {req.target_audience}, Topic: {req.topic}"
# エントリースパン:user_id と session_id を渡します。これらは後続のすべての子スパンに自動的に渡されます。
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=user_prompt)]),
],
)
def event_generator():
# ===== ステップ 1:カスタムビジネスプロパティによるタグ付け (エントリースパン作成前) =====
# カスタムビジネスプロパティをバゲージに書き込み、現在のコンテキストにアタッチします。
# 順序が重要です:最初にバゲージを設定し、次にエントリースパンを作成します。これにより、エントリースパン
# とそのすべての子スパンが、バゲージを含むコンテキストに基づいて作成され、タグ付けされます。
# コンソールの「エージェント収集設定 > 収集対象のバゲージ」でこれらのキー (例:tenant_id, channel) を宣言する限り、
# エージェントはそれらを現在のトレース内の各スパンの属性に書き込みます。
ctx = baggage.set_baggage("tenant_id", req.tenant_id or "default")
ctx = baggage.set_baggage("channel", req.channel or "web", context=ctx)
token = context.attach(ctx)
# ===== ステップ 2:エントリースパンの作成 (user_id と session_id を含む) =====
# user_id と session_id は genai util によって後続のすべての子スパンに自動的に渡され、コンソールでの設定は不要です。
# この時点で、エントリースパンはカスタムバゲージを含むコンテキストに基づいて開始されるため、プロパティでタグ付けもされます。
handler.start_entry(entry_inv)
output_chunks: list[str] = []
try:
try:
for chunk in run_marketing_agent_stream(
content_type=req.content_type,
product=req.product,
target_audience=req.target_audience,
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)),
)
return
entry_inv.output_messages = [
OutputMessage(
role="assistant",
parts=[Text(content="".join(output_chunks))],
finish_reason="stop",
),
]
handler.stop_entry(entry_inv)
finally:
# バゲージが後続のリクエストに漏れるのを防ぐため、速やかにデタッチします。
context.detach(token)
return StreamingResponse(event_generator(), media_type="text/event-stream")
@app.get("/health")
async def health():
return {"status": "ok"}
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8990)よくある質問
「収集対象のバゲージリスト」を設定しましたが、スパンに対応する属性がありません。
エージェントのバージョンが 3.1.0 以降であることを確認してください。
コードで
context.attach(ctx)が呼び出されていることを確認します。Baggage は、現在のコンテキストにアタッチされた後にのみ、ダウンストリームのスパンに伝播します。バゲージを書き込むタイミングが、対象のスパンが作成される前であることを確認してください。カラーリングは「バゲージが設定された後」に作成されたスパンに対してのみ有効です。
コンソール内のキーが、コード内のバゲージキーと完全に一致していること (大文字と小文字を区別、英語のカンマを使用) を確認してください。
user_id/session_id は「収集対象の Baggage リスト」で設定する必要がありますか?
いいえ。これらはエントリースパンが作成される際に genai util によって自動的に処理および伝播され、デフォルトの収集範囲に含まれています。
もし context.detach(token) を呼び出し忘れた場合、どうなりますか?
バゲージが、トレース対象となるべきではない後続のリクエストに漏洩する可能性があります。デタッチを確実に行うために、常に try/finally またはコンテキストマネージャーを使用してください。
カラーリングされた属性が多すぎると、パフォーマンスやコストに影響しますか?
コンソールで明示的に宣言されたキーのみが収集されます。リストは簡潔に保ち、分析、トラブルシューティング、またはアラート機能で実際に使用されるビジネスディメンションのみをカラーリングしてください。大きなオブジェクトや、カーディナリティが高く分析価値の低いフィールドをバゲージに書き込むことは避けてください。