# OpenTelemetry GenAI Semantic Conventions: Span Agent di Tempo

> Cara OpenTelemetry GenAI semantic conventions memodelkan satu run AI agent, beserta trace processor OpenAI Agents SDK yang mengekspor span invoke_workflow, invoke_agent, chat dan execute_tool ke stack Grafana Tempo self-hosted.

URL: https://www.matthewswong.com/id/blog/opentelemetry-genai-agent-spans-tracing/

- Author: Matthews Wong (https://www.matthewswong.com/id/about/)
- Published: 2026-10-01
- Updated: 2026-10-01
- Category: DevOps

> **Key takeaway:** OpenTelemetry GenAI semantic conventions memodelkan satu run agent sebagai span invoke_workflow atau invoke_agent, dengan span chat dan execute_tool sebagai sibling di bawahnya. TracingProcessor kustom di OpenAI Agents SDK bisa mengirim bentuk itu ke Grafana Tempo, tetapi isi pesan bersifat opt-in, dan secara default Tempo memotong nilai atribut di atas 2048 byte.

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.

Entry point yang dihadapi pengguna dan mengoordinasikan beberapa agent atau GenAI call, misalnya run dengan handoff. Bukan untuk agent tunggal.

Satu pemanggilan agent. INTERNAL bila agent berjalan di proses Anda, CLIENT bila agent itu hosted dan remote.

Membuat resource hosted agent di provider, misalnya agent Bedrock.

Hanya bila instrumentasi bisa membedakan tahap planning dari inference biasa secara andal.

Setiap model call. Didefinisikan di dokumen model spans, yang diperluas oleh dokumen agent.

Setiap eksekusi tool. Load dan read Agent Skills adalah refinement dari span ini, bukan span terpisah.

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.

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.

Nama trace adalah RunConfig.workflow_name, yang default-nya string literal Agent workflow, jadi isilah. group_id menjadi gen_ai.conversation.id.

AgentSpanData berisi name, handoffs, tools dan output_type. Hanya name yang punya padanan atribut konvensi.

Model Responses API default menghasilkan ResponseSpanData berisi objek Response dan usage; model Chat Completions menghasilkan GenerationSpanData berisi model dan usage.

FunctionSpanData menyimpan nama tool beserta input dan output, yang kosong bila capture data sensitif dimatikan.

Tidak didefinisikan

Dikirim sebagai span biasa dengan atribut ber-prefix vendor, agar backend yang paham GenAI tidak salah membacanya.

Dilewati

Versi SDK terbaru menambahkan span task dan turn di sekitar setiap run dan setiap giliran model. Keduanya tidak punya konvensi, jadi child-nya dipindahkan ke ancestor terdekat yang dipetakan.

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.

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.

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.

> Pilih antara add_trace_processor dan set_trace_processors dengan sengaja. add_trace_processor menambahkan processor Anda di samping exporter default, sehingga setiap trace tetap terkirim ke dashboard trace hosted milik OpenAI selain ke Tempo. set_trace_processors mengganti daftar default, dan itulah yang Anda butuhkan bila trace harus tetap di server sendiri. Selain itu, dokumentasi SDK menyatakan tracing tidak tersedia bagi organisasi yang memakai API OpenAI dengan kebijakan Zero Data Retention, jadi periksa hal itu sebelum merancang di atasnya.

## 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.

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.

> Metric tempo_distributor_attributes_truncated_total membawa label scope, dan distributor juga mencatat log contoh setiap atribut yang terpotong dengan rate limit. Pasang alert pada metric itu untuk scope span setelah capture dinyalakan, sehingga Anda tahu soal pemotongan dari grafik, bukan dari engineer yang membaca setengah hasil tool.

## 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.

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.

Span model call

Dikirim dari ResponseSpanData dan GenerationSpanData di processor yang sama.

Tidak dikirim; memasang opentelemetry-instrumentation-genai-openai di sampingnya yang menyediakannya.

Konten pesan

Hanya argumen dan hasil tool; konversi input item SDK ke schema messages diserahkan ke Anda.

Diatur lewat environment variable, dengan completion hook upload untuk storage eksternal.

Mengikuti perubahan spec

Manual. Setiap rename di spec berstatus Development harus Anda edit sendiri.

Mengikuti konvensi lewat release paket, saat ini masih beta.

Handoff, guardrail, penamaan

Sepenuhnya di tangan Anda, termasuk atribut vendor dan span yang dilewati.

Ditentukan paket; nama span workflow diambil dari workflow_name.

> Saat tulisan ini dibuat, paket opentelemetry-instrumentation-genai-openai-agents di PyPI berada di versi 1.2b0. Secara default paket ini tetap mengaktifkan upload SDK ke tracing hosted milik OpenAI di samping OpenTelemetry, dan disable_openai_trace_export=True membuat trace hanya dikirim lewat OpenTelemetry.

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.

## Sumber

- OpenTelemetry GenAI semantic conventions: span agent dan framework
- OpenTelemetry GenAI semantic conventions: span model dan capture konten
- Dokumentasi OpenAI Agents SDK: tracing
- PyPI: opentelemetry-instrumentation-genai-openai-agents
- Dokumentasi Grafana Tempo: troubleshooting error out-of-memory

## Source links

- https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-agent-spans.md
- https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-spans.md
- https://openai.github.io/openai-agents-python/tracing/
- https://pypi.org/project/opentelemetry-instrumentation-genai-openai-agents/
- https://grafana.com/docs/tempo/latest/troubleshooting/out-of-memory-errors/

## FAQ

### Apa itu OpenTelemetry GenAI semantic conventions?

Ini adalah aturan penamaan OpenTelemetry untuk span, metric dan event dari aplikasi generative AI, mencakup model call, agent, tool dan MCP. Konvensinya kini berada di repository open-telemetry/semantic-conventions-genai. Semua dokumen di sana masih berstatus Development, jadi nama atribut bisa berubah antar-release.

### Apa beda span invoke_agent dan invoke_workflow?

invoke_agent mewakili satu pemanggilan agent, dengan kind INTERNAL untuk agent di dalam proses dan CLIENT untuk agent hosted yang remote. invoke_workflow mewakili run yang dihadapi pengguna dan mengoordinasikan beberapa agent atau GenAI call, misalnya run OpenAI Agents dengan handoff. Spec menyatakan pemanggilan agent tunggal sebaiknya tidak dilaporkan sebagai workflow.

### Apakah span execute_tool harus menjadi child dari span chat?

Tidak. Model call selesai saat mengembalikan permintaan tool call, dan tool baru berjalan sesudahnya. Konvensi menggambarkan span tool sebagai sibling di bawah span invoke_agent yang sama. Menaruhnya di bawah span chat membuat durasi span chat membengkak dan menyembunyikan latency tool di dalam latency model.

### Bagaimana cara mengirim trace OpenAI Agents SDK ke Grafana Tempo?

Daftarkan TracingProcessor yang mengubah span SDK menjadi span OpenTelemetry dan mengekspornya lewat OTLP ke collector seperti Alloy yang meneruskan ke Tempo. add_trace_processor tetap mempertahankan upload default ke dashboard trace OpenAI, sedangkan set_trace_processors menggantinya. Paket resmi opentelemetry-instrumentation-genai-openai-agents bisa dipakai sebagai alternatif menulis processor sendiri.

### Apakah OpenTelemetry merekam prompt dan output model secara default?

Tidak. Atribut seperti gen_ai.input.messages, gen_ai.output.messages dan gen_ai.tool.call.arguments berstatus Opt-In, dan konvensi menyatakan instrumentasi sebaiknya tidak merekamnya secara default. Untuk production, spec menyarankan mengunggah konten ke storage eksternal dan mencatat referensinya di span. Bila Anda merekam konten di span pada Tempo, max_attribute_bytes default 2048 akan memotong nilai yang lebih panjang.

---

- HTML version: https://www.matthewswong.com/id/blog/opentelemetry-genai-agent-spans-tracing/
- English: https://www.matthewswong.com/en/blog/opentelemetry-genai-agent-spans-tracing/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
