MLflow の OpenTelemetry スパン属性を設定します

カスタムのOpenTelemetry計測（OTel）アプリケーションからDatabricks MLflowにトレースを送信する場合、MLflowのUIでトレースデータを正しく表示するために、特定のスパン属性を設定する必要があります。このページでは、設定すべきOpenTelemetry GenAIセマンティック規約属性について説明します。

Langfuseなどの既製の統合機能を使用する場合、その統合機能によってこれらの属性が自動的に設定されます。このページは、OTel社製のカスタム計測機器を使用するアプリケーション向けです。

注記

Databricksが管理するMLflowの属性は、オープンソースのMLflowとは異なります。OSS MLflowの属性マッピングについては、 MLflowのドキュメントを参照してください。

要件

始める前に、以下のものを用意してください。

• OTel トレース プレビューが有効になっているDatabricksワークスペース
• OTLPエクスポーターは、トレースをワークスペースに送信するように設定されています。Unity Catalogテーブルへのログトレースを参照してください。
• OpenTelemetry SDKで計測されたアプリケーション

スパンタイプを設定します

トレース内の各スパンにはタイプラベルが必要です。そうすることで、MLflowはそれがどのような種類の操作を表しているかを識別できます。span.set_attribute("gen_ai.operation.name", "<value>")を呼び出すことで、 gen_ai.operation.name次の表のいずれかの値に設定します。MLflowはこの属性を読み取り、対応するMLflowスパンタイプをトレースUIに表示します。

OTel gen_ai.operation.name値	MLflow スパンタイプ
chat	CHAT_MODEL
text_completion	LLM
generate_content	LLM
response	LLM
embeddings	EMBEDDING
execute_tool	TOOL
create_agent	AGENT
invoke_agent	AGENT

Python

span.set_attribute("gen_ai.operation.name", "chat")

入力と出力を設定する

入力と出力を表示する各スパンにgen_ai.input.messagesとgen_ai.output.messagesを設定してください。これらを ルートスパン に設定すると、トレースレベルのリクエストとレスポンスのプレビューにも情報が表示されます。

OTel属性	MLflow属性
gen_ai.input.messages	mlflow.spanInputs
gen_ai.output.messages	mlflow.spanOutputs

値は、 プレーンな文字列 または JSONシリアル化された文字列 のいずれかです。roleとcontentフィールドを持つメッセージオブジェクトのJSON配列を使用すると、MLflow UIでよりリッチなレンダリングが可能になります（たとえば、「ユーザー」と「アシスタント」というラベルの付いた吹き出しなど）。

Python

import json

# Plain string — displays as-is in the UI
span.set_attribute("gen_ai.input.messages", "What is the weather today?")

# JSON message array — renders with role labels in the UI
span.set_attribute("gen_ai.input.messages", json.dumps([
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the weather today?"}
]))
span.set_attribute("gen_ai.output.messages", json.dumps([
    {"role": "assistant", "content": "It is sunny and 72°F in San Francisco."}
]))

トークンの使用状況を設定する

UIトレースサマリーにトークン数を表示するには、ルートスパンでspan.set_attribute()を呼び出してgen_ai.usage.input_tokensとgen_ai.usage.output_tokensを設定します。MLflowは、トレースレベルでカウントを集計するため、これらの値をルートスパンから読み取ります。

OTel gen_ai.usage.*属性	MLflowフィールド
gen_ai.usage.input_tokens	入力トークン数
gen_ai.usage.output_tokens	出力トークン数
（未設定 — 自動計算）	トークンの総数

Python

root.set_attribute("gen_ai.usage.input_tokens", 150)
root.set_attribute("gen_ai.usage.output_tokens", 42)

完全な例：Pythonエージェントを計測する

次の例では、3つの属性カテゴリすべてを、LLM子スパンを持つシンプルなエージェントにまとめて配置しています。これは、OTLPエクスポーターが既にDatabricksにトレースを送信するように設定済みであることを前提としています。

Python

import json
from opentelemetry import trace

tracer = trace.get_tracer("my-agent")

def run_agent(query: str) -> str:
    with tracer.start_as_current_span("agent-run") as root:
        # Child LLM span — set gen_ai attributes for this individual call
        with tracer.start_as_current_span("chat") as llm:
            llm.set_attribute("gen_ai.operation.name", "chat")
            messages = [
                {"role": "system", "content": "You are a helpful assistant."},
                {"role": "user", "content": query}
            ]
            response = call_llm(messages)
            llm.set_attribute("gen_ai.input.messages", json.dumps(messages))
            llm.set_attribute("gen_ai.output.messages", json.dumps([
                {"role": "assistant", "content": response}
            ]))
            llm.set_attribute("gen_ai.usage.input_tokens", 150)
            llm.set_attribute("gen_ai.usage.output_tokens", 42)

        # Root span — MLflow reads inputs, outputs, and token usage from the
        # root span to populate the trace summary in the UI.
        root.set_attribute("gen_ai.operation.name", "chat")
        root.set_attribute("gen_ai.input.messages", json.dumps([
            {"role": "user", "content": query}
        ]))
        root.set_attribute("gen_ai.output.messages", json.dumps([
            {"role": "assistant", "content": response}
        ]))
        root.set_attribute("gen_ai.usage.input_tokens", 150)
        root.set_attribute("gen_ai.usage.output_tokens", 42)
        return response

MLflow UIで確認する

run_agent()を呼び出した後、エクスペリメントでMLflow Traces] タブを開きます。 正しく計測されたトレースは次のことを示しています。

• スパンタイプ : 各スパンは、タイプラベル(例: chat )の代わりに、 UNKNOWN
• リクエストとレスポンス ：ルートスパンには入力メッセージと出力メッセージが表示されます。
• VPN の使用法 : トレースの概要には、入力、出力、および合計カウントが表示されます。