OpenTelemetry GenAI Semantic Conventions: Span Agent di Tempo

Bayangkan helpdesk ERP tempat agent sengketa invoice menerima tiket dari agent triase, lalu menyerahkannya ke agent pencocokan accounts payable yang memanggil tiga tool ke modul purchasing. Seorang pengguna melapor bahwa agent butuh empat puluh detik dan memberi jawaban yang salah. Trace layanan di Tempo hanya menampilkan satu HTTP request panjang dan sederet query database: tidak ada agent, tidak ada model call, tidak ada tool, sehingga tidak bisa diketahui apakah waktunya habis di model, di tool yang berulang, atau di handoff yang seharusnya tidak terjadi.

OpenTelemetry GenAI semantic conventions dibuat untuk mengisi celah itu. Tulisan ini membahas apa yang didefinisikan konvensi span agent saat ini, bentuk pohon span yang seharusnya dihasilkan satu run agent, trace processor Python lengkap yang memetakan span OpenAI Agents SDK ke konvensi tersebut dan mengekspornya lewat OTLP, cara menangani capture pesan tanpa membocorkan data ERP, serta query TraceQL yang membuat hasilnya berguna. Setiap nama atribut dan requirement level di bawah diambil langsung dari repository konvensinya, yang masih menandai semuanya berstatus Development.

Apa yang didefinisikan OpenTelemetry GenAI semantic conventions untuk agent

Konvensi GenAI kini berada di repository tersendiri, open-telemetry/semantic-conventions-genai, dan halaman lama di opentelemetry.io mengarah ke sana dengan catatan bahwa halaman itu tidak lagi dipelihara. Semua dokumen di dalamnya berstatus Development, artinya nama atribut masih bisa berubah antar-release. Di dalamnya, dokumen agent mendefinisikan enam operasi, masing-masing diidentifikasi oleh gen_ai.operation.name dan nama span yang dibentuk darinya.

Requirement level lebih penting daripada namanya. Di semua span ini hanya gen_ai.operation.name yang Required, ditambah gen_ai.provider.name pada span yang memanggil provider. Nama agent, deskripsi, versi dan conversation id berstatus Conditionally Required, artinya diisi bila datanya ada. Jumlah token dan parameter request berstatus Recommended. Semua yang membawa konten, dari gen_ai.input.messages sampai gen_ai.tool.call.arguments, berstatus Opt-In, dan dokumen model spans menyatakan instrumentasi sebaiknya tidak merekamnya secara default.

Pohon span yang seharusnya dihasilkan satu run agent

Untuk contoh sengketa invoice, konvensi mengarah ke pohon seperti di bawah. Root-nya invoke_workflow karena run ini melibatkan handoff, dan spec menyebut Runner.run di OpenAI Agents dengan handoff, sub-agent atau agents-as-tools sebagai contoh workflow. Agent tunggal tanpa delegasi memakai invoke_agent sebagai root.

invoke_workflow invoice_dispute              INTERNAL  gen_ai.conversation.id=TCK-2026-10-0193
├─ invoke_agent Triage                        INTERNAL  gen_ai.agent.name=Triage
│  ├─ chat <model>                            CLIENT    gen_ai.usage.input_tokens=1840
│  └─ agent.handoff                           INTERNAL  (no GenAI operation exists for this)
└─ invoke_agent AP Matcher                    INTERNAL  gen_ai.agent.name=AP Matcher
   ├─ chat <model>                            CLIENT    finish: tool call
   ├─ execute_tool get_purchase_order         INTERNAL  sibling of the chat span, not its child
   ├─ execute_tool get_goods_receipt          INTERNAL
   └─ chat <model>                            CLIENT    final answer

# Wrong: execute_tool nested under the chat span that requested it.
# The model call has already returned when the tool runs; nesting it there
# inflates the chat span's duration and hides tool latency inside model latency.

Aturan struktur yang paling sering salah adalah letak span tool. Model call mengembalikan permintaan tool call lalu selesai; framework kemudian menjalankan tool, dan model call berikutnya dimulai setelahnya. Deskripsi plan span di konvensi menegaskan bentuk yang dimaksud: span tool atau task biasanya menjadi operasi sibling di bawah span invoke_agent yang sama. Menaruh execute_tool di bawah span chat yang memintanya membuat span chat terlihat selama tool berjalan, dan itu merusak semua dashboard latency yang dibangun dari span chat.

Handoff sama sekali tidak punya operasi GenAI. Nilai well-known mencakup chat, embeddings, retrieval, operasi memory, create_agent, invoke_agent, invoke_workflow, plan dan execute_tool, tetapi tidak ada untuk pemindahan kendali antar-agent. Span invoke_agent kedua sudah menunjukkan bahwa perpindahan terjadi; span handoff dipertahankan sebagai span INTERNAL biasa agar momen perpindahannya tetap terlihat, tanpa berpura-pura termasuk dalam konvensi.

Memetakan span OpenAI Agents SDK ke operasi GenAI

OpenAI Agents SDK men-trace setiap run secara default dan meneruskan setiap trace dan span ke processor yang terdaftar lewat empat callback: on_trace_start, on_trace_end, on_span_start dan on_span_end. Setiap span membawa span_id, parent_id, timestamp, error opsional, dan objek span_data bertipe. Pemetaannya sebagian besar satu-satu, dengan dua pengecualian yang perlu diputuskan sejak awal.

Melewati span task dan turn adalah keputusan desain, bukan kewajiban. Mempertahankannya menambah dua level antara agent dan model call-nya, dan query struktural TraceQL seperti span agent yang langsung diikuti span tool akan berhenti cocok. Bila pengelompokan per giliran penting bagi Anda, kirim keduanya sebagai span INTERNAL biasa dan tulis query dengan operator descendant, bukan operator child.

Menulis trace processor kustom

Processor di bawah adalah subclass TracingProcessor, menyimpan dictionary dari id SDK ke span OpenTelemetry, dan memulai setiap span OpenTelemetry dengan parent context eksplisit yang diambil dari dictionary itu. Bagian terakhir itulah intinya: SDK melacak span aktifnya sendiri di contextvar Python, sehingga mengandalkan current context OpenTelemetry akan menempelkan span ke HTTP request span yang kebetulan aktif, atau tidak ke mana pun.

# genai_processor.py
# pip install openai-agents opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
import threading
from typing import Any

from agents.tracing import (
    AgentSpanData, FunctionSpanData, GenerationSpanData, GuardrailSpanData,
    HandoffSpanData, ResponseSpanData, Span, Trace, TracingProcessor,
)
from opentelemetry import trace as otel_trace
from opentelemetry.trace import SpanKind, Status, StatusCode


class GenAISemconvProcessor(TracingProcessor):
    """Re-emit Agents SDK traces as OpenTelemetry GenAI spans (semconv status: Development)."""

    def __init__(self, tracer_provider, capture_content: bool = False):
        self._provider = tracer_provider
        self._tracer = otel_trace.get_tracer("erp.agents.genai", tracer_provider=tracer_provider)
        self._capture = capture_content
        self._otel: dict[str, otel_trace.Span] = {}  # SDK trace_id / span_id -> OTel span
        self._alias: dict[str, str] = {}             # skipped SDK span -> nearest mapped ancestor
        self._agent: dict[str, str] = {}             # mapped key -> agent name, for tool spans
        self._lock = threading.Lock()                # callbacks arrive from concurrent runs

    # -- trace -> invoke_workflow root ---------------------------------------------
    def on_trace_start(self, trace: Trace) -> None:
        attrs = {"gen_ai.operation.name": "invoke_workflow", "gen_ai.workflow.name": trace.name}
        group_id = getattr(trace, "group_id", None)
        if group_id:  # a real ticket/session id only -- the spec forbids inventing one
            attrs["gen_ai.conversation.id"] = group_id
        root = self._tracer.start_span(
            f"invoke_workflow {trace.name}", kind=SpanKind.INTERNAL, attributes=attrs)
        with self._lock:
            self._otel[trace.trace_id] = root

    def on_trace_end(self, trace: Trace) -> None:
        with self._lock:
            root = self._otel.pop(trace.trace_id, None)
        if root is not None:
            root.end()

    # -- spans ---------------------------------------------------------------------
    def on_span_start(self, span: Span[Any]) -> None:
        data = span.span_data
        with self._lock:
            parent_key = span.parent_id or span.trace_id
            parent_key = self._alias.get(parent_key, parent_key)
            described = self._describe(data, self._agent.get(parent_key))
            if described is None:
                # task/turn spans: re-parent their children onto the nearest mapped
                # ancestor, so Tempo shows agent > chat, not agent > turn > chat.
                self._alias[span.span_id] = parent_key
                return
            name, kind, attrs = described
            parent = self._otel.get(parent_key)
            ctx = otel_trace.set_span_in_context(parent) if parent is not None else None
            self._otel[span.span_id] = self._tracer.start_span(
                name, context=ctx, kind=kind, attributes=attrs)  # sampling sees these
            self._agent[span.span_id] = (
                data.name if isinstance(data, AgentSpanData) else self._agent.get(parent_key, ""))

    def _describe(self, data, agent_name):
        if isinstance(data, AgentSpanData):
            return (f"invoke_agent {data.name}", SpanKind.INTERNAL,
                    {"gen_ai.operation.name": "invoke_agent", "gen_ai.agent.name": data.name})
        if isinstance(data, (ResponseSpanData, GenerationSpanData)):
            api = "responses" if isinstance(data, ResponseSpanData) else "chat_completions"
            return ("chat", SpanKind.CLIENT,  # renamed in on_span_end once the model is known
                    {"gen_ai.operation.name": "chat", "gen_ai.provider.name": "openai",
                     "openai.api.type": api})
        if isinstance(data, FunctionSpanData):
            attrs = {"gen_ai.operation.name": "execute_tool", "gen_ai.tool.name": data.name,
                     "gen_ai.tool.type": "function"}
            if agent_name:
                attrs["gen_ai.agent.name"] = agent_name
            return (f"execute_tool {data.name}", SpanKind.INTERNAL, attrs)
        if isinstance(data, HandoffSpanData):
            return ("agent.handoff", SpanKind.INTERNAL, {})   # no GenAI operation: no gen_ai.*
        if isinstance(data, GuardrailSpanData):
            return (f"guardrail {data.name}", SpanKind.INTERNAL, {})
        return None

    def on_span_end(self, span: Span[Any]) -> None:
        with self._lock:
            self._alias.pop(span.span_id, None)
            self._agent.pop(span.span_id, None)
            out = self._otel.pop(span.span_id, None)
        if out is None:
            return
        data = span.span_data
        if isinstance(data, ResponseSpanData):
            if data.response is not None:
                # The response echoes the model that answered, so this is response.model;
                # the request-side name never reaches this span type.
                out.update_name(f"chat {data.response.model}")
                out.set_attribute("gen_ai.response.model", data.response.model)
                out.set_attribute("gen_ai.response.id", data.response.id)
            self._usage(out, data.usage)
        elif isinstance(data, GenerationSpanData):
            if data.model:
                out.update_name(f"chat {data.model}")
                out.set_attribute("gen_ai.request.model", data.model)
            self._usage(out, data.usage)
        elif isinstance(data, FunctionSpanData) and self._capture:
            # Opt-In attributes. Both are None when trace_include_sensitive_data=False.
            if data.input:
                out.set_attribute("gen_ai.tool.call.arguments", data.input)
            if data.output is not None:
                out.set_attribute("gen_ai.tool.call.result", str(data.output))
        elif isinstance(data, HandoffSpanData):
            out.set_attribute("openai_agents.handoff.from", data.from_agent or "")
            out.set_attribute("openai_agents.handoff.to", data.to_agent or "")
        elif isinstance(data, GuardrailSpanData):
            out.set_attribute("openai_agents.guardrail.triggered", data.triggered)

        if span.error:
            # SpanError is a message plus a dict, not an exception class, so there is
            # no low-cardinality error name to report: fall back to the spec's _OTHER.
            out.set_attribute("error.type", "_OTHER")
            out.set_status(Status(StatusCode.ERROR, span.error.get("message", "")))
        out.end()

    @staticmethod
    def _usage(out, usage):
        if not usage:
            return
        out.set_attribute("gen_ai.usage.input_tokens", usage.get("input_tokens", 0))
        out.set_attribute("gen_ai.usage.output_tokens", usage.get("output_tokens", 0))
        cached = (usage.get("input_tokens_details") or {}).get("cached_tokens", 0)
        if cached:  # already included in input_tokens, per the spec
            out.set_attribute("gen_ai.usage.cache_read.input_tokens", cached)

    def shutdown(self) -> None:
        self._provider.shutdown()

    def force_flush(self) -> None:
        self._provider.force_flush()

Dua detail di dalamnya mengikuti konvensi dengan cermat. Atribut yang menurut spec sebaiknya diberikan saat span dibuat, seperti nama operasi, nama tool dan nama agent, dikirim ke start_span agar sampler bisa memakainya. Span chat diganti namanya setelah response tiba, karena nama model belum diketahui saat span dimulai. Pemasangannya cukup dengan tracer provider, OTLP exporter yang diarahkan ke collector yang sudah meneruskan ke Tempo, dan satu pemanggilan registrasi.

# telemetry.py -- call configure_tracing() once, at process start
from agents import add_trace_processor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

from genai_processor import GenAISemconvProcessor


def configure_tracing() -> None:
    provider = TracerProvider(resource=Resource.create({
        "service.name": "erp-invoice-agent",
        "deployment.environment.name": "staging",
    }))
    # Alloy or the OTel Collector on the same Docker network, forwarding to Tempo.
    provider.add_span_processor(
        BatchSpanProcessor(OTLPSpanExporter(endpoint="http://alloy:4318/v1/traces")))

    # add_trace_processor KEEPS the default exporter to OpenAI's trace dashboard.
    # set_trace_processors([...]) REPLACES it -- use that when traces must stay on your VPS.
    add_trace_processor(GenAISemconvProcessor(provider, capture_content=False))


# agent_run.py
from agents import RunConfig, Runner

result = await Runner.run(
    triage_agent,
    "Why is the invoice for PO-2026-0412 blocked?",
    run_config=RunConfig(
        workflow_name="invoice_dispute",      # becomes gen_ai.workflow.name
        group_id=ticket.number,                # becomes gen_ai.conversation.id
        trace_include_sensitive_data=False,    # tool inputs/outputs never leave the SDK
    ),
)

Worker yang berjalan lama butuh satu baris lagi. SDK mengekspor dalam batch di background, dan dokumentasinya menyarankan memanggil flush_traces setelah satu unit kerja di Celery atau background task FastAPI agar trace langsung diekspor. Dengan processor di atas, force_flush juga mem-flush batch processor OpenTelemetry, sehingga span sampai di Tempo sebelum worker didaur ulang.

Atribut yang harus benar

Sebagian besar manfaat konvensi datang dari segelintir atribut yang konsisten di semua layanan yang mengirimnya. Berikut atribut yang tuntutan spesifiknya mudah terlewat.

• gen_ai.conversation.id harus berupa identifier nyata dari framework atau backend, misalnya session atau nomor tiket helpdesk yang dikirim sebagai group_id. Spec menyatakan instrumentasi sebaiknya tidak mengisinya dengan UUID baru, trace id, atau hash bila conversation id memang tidak ada.
• gen_ai.request.model di span agent sebaiknya hanya diisi bila library hanya mengizinkan satu model per agent. Untuk agent yang bisa berganti model, kosongkan di span agent dan baca model dari setiap span chat.
• gen_ai.usage.cache_read.input_tokens sudah termasuk dalam gen_ai.usage.input_tokens. Menjumlahkan keduanya menghitung prompt yang di-cache dua kali, dan itu berpengaruh bila total token dipakai untuk dashboard biaya.
• error.type sebaiknya low-cardinality. SpanError di SDK berupa string pesan dan dictionary data, bukan class exception, jadi processor mencatat nilai fallback dari spec, _OTHER, dan menyimpan pesannya di deskripsi status span.
• openai.api.type, dari dokumen provider OpenAI, membedakan responses dari chat_completions. Atribut ini Recommended dan murah untuk diisi, serta memisahkan dua jalur kode bila tim memakai keduanya.

Resource attribute menyelesaikan sisanya. service.name menunjukkan dari layanan agent mana sebuah trace berasal, dan atribut environment menjaga trace staging agar tidak masuk dashboard production. Keduanya tidak khusus GenAI, dan justru karena itu trace agent bisa berada di instance Tempo yang sama dengan bagian platform lainnya serta digabungkan dengan span HTTP dan database di sekitarnya.

Capture pesan opt-in tanpa membocorkan data ERP

Prompt, output model, dan hasil tool di agent ERP berisi nama supplier, nilai invoice, dan kadang data pribadi. Dokumen model spans dengan tegas menyebut konten ini sensitif, sering berukuran besar, dan sebaiknya tidak direkam secara default. Dokumen itu menjabarkan tiga pola pemakaian, berurutan dari yang paling sederhana hingga yang paling matang secara operasional.

1. Default: tidak merekam instruksi, input maupun output. Jumlah token, durasi dan nama tool biasanya sudah cukup untuk menemukan agent yang berulang atau model call yang lambat.
2. Merekam konten di span sebagai gen_ai.system_instructions, gen_ai.input.messages dan gen_ai.output.messages, yang disarankan spec terutama untuk pre-production atau storage yang sudah memenuhi kewajiban privasi Anda.
3. Mengunggah konten ke storage eksternal dan hanya mencatat referensinya di span, yang direkomendasikan spec untuk production karena storage tersebut bisa punya access control sendiri.

Di sisi SDK, RunConfig.trace_include_sensitive_data default-nya true, dan environment variable OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA bisa mengubah default itu. Menyetelnya ke false mengosongkan field input dan output sebelum processor mana pun melihatnya, dan itu lebih aman daripada mengandalkan processor Anda sendiri untuk membuangnya. Processor di atas menambah gerbang kedua, capture_content, sehingga menyalakan capture menjadi perubahan yang disengaja di dua tempat. Bila Anda menyalakannya di stack self-hosted, Tempo punya batasnya sendiri yang perlu diantisipasi.

# tempo.yaml -- the default silently cuts long attribute values
distributor:
  # Default 2048 bytes. A tool result holding a 40-line purchase order, or any
  # gen_ai.input.messages value, is truncated before it is stored -- the span
  # still arrives, so nothing looks broken until someone reads it.
  max_attribute_bytes: 16384

# Watch for it instead of guessing:
#   sum by (scope) (rate(tempo_distributor_attributes_truncated_total[5m]))

Menaikkan batas itu adalah kompromi, bukan perbaikan. Panduan troubleshooting Tempo mendokumentasikan max_attribute_bytes justru karena atribut besar menjadi salah satu penyebab querier kehabisan memori, dan default 2048 byte ada untuk melindungi cluster. Naikkan hanya sebesar konten yang memang Anda pilih untuk direkam, dan utamakan pola storage eksternal begitu capture pesan lebih dari sekadar alat debugging.

Query trace agent di Grafana Tempo dengan TraceQL

Begitu span mengikuti konvensi, query TraceQL bisa ditulis berdasarkan makna, bukan nama span khusus tiap layanan. Atribut span memakai prefix span. , intrinsic seperti status dan duration memakai span: dengan titik dua, dan operator struktural memilih child, descendant dan sibling. Berikut query yang menjawab pertanyaan dari contoh di awal.

// Every failed tool call, with the agent that made it
{ span.gen_ai.operation.name = "execute_tool" && span:status = error }
  | select(span.gen_ai.tool.name, span.gen_ai.agent.name)

// Runs where one agent called the same tool more than five times -- a looping agent
{ span.gen_ai.operation.name = "invoke_agent" }
  > { span.gen_ai.tool.name = "get_purchase_order" } | count() > 5

// Slow model calls inside the dispute workflow only
{ span.gen_ai.workflow.name = "invoice_dispute" }
  >> { span.gen_ai.operation.name = "chat" && span:duration > 8s }

// Every trace for one helpdesk ticket, across retries and follow-up messages
{ span.gen_ai.conversation.id = "TCK-2026-10-0193" }

// Failed spans that sit beside a handoff under the same agent
{ span:name = "agent.handoff" } ~ { span:status = error }

Query kedua adalah yang membuat seluruh upaya ini sepadan. Agent yang berulang tidak terlihat di metric layanan, karena setiap tool call adalah request yang cepat dan sukses, padahal itulah cara paling umum agent menghabiskan token tanpa menghasilkan jawaban. Operator child hanya berfungsi karena processor membuang span turn; bila span itu tetap ada, query yang sama perlu operator descendant.

Processor kustom atau paket instrumentasi resmi?

Processor kustom bukan satu-satunya jalan. OpenTelemetry kini menerbitkan opentelemetry-instrumentation-genai-openai-agents, yang mendaftarkan tracing processor ke SDK dan menghasilkan span workflow, agent dan tool. Paket ini melanjutkan paket sebelumnya, opentelemetry-instrumentation-openai-agents-v2, yang kini hanya menerima security patch. Kedua pendekatan berbeda dalam hal-hal yang menentukan pilihan.

# pip install opentelemetry-instrumentation-genai-openai-agents \
#             opentelemetry-instrumentation-genai-openai     # the chat spans come from this one
from opentelemetry.instrumentation.genai.openai_agents import OpenAIAgentsInstrumentor

# Default keeps uploading to OpenAI's hosted tracing as well; this routes only to OTel.
OpenAIAgentsInstrumentor().instrument(disable_openai_trace_export=True)

# Message capture is an environment switch, off unless you set it:
#   OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=...
# or ship content to storage instead of span attributes:
#   OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK=upload
#   OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH=...

Pembagian yang masuk akal adalah memulai dengan paket resmi untuk bentuk standar, lalu beralih ke processor kustom hanya bila Anda butuh sesuatu yang tidak disediakannya, misalnya aturan redaksi per tool atau atribut khusus ERP di setiap span agent. Processor kustom di tulisan ini cukup pendek untuk dipelihara, tetapi konsekuensinya Anda harus membaca changelog konvensi, karena spec berstatus Development boleh mengganti nama atribut yang menjadi dasar dashboard Anda.

Trace agent menjadi berguna ketika mengikuti bentuk bersama: root berupa workflow atau agent, model call dan tool call sebagai sibling di bawahnya, nama atribut yang sama di setiap layanan, dan konten yang tidak direkam kecuali ada yang sengaja memutuskannya. Kunci versi konvensi yang Anda implementasikan, isi conversation id yang nyata, jangan taruh tool di bawah span chat, dan periksa apa yang dipotong backend Anda sebelum memercayai apa yang ditampilkannya.