Konfigurasi kolektor OpenTelemetry khusus untuk agen Office

Anda dapat mengarahkan telemetri audit lengkap dari agen Office ke kolektor OpenTelemetry (OTEL) Anda sendiri. Ini memberikan organisasi Anda kontrol penuh atas retensi, enkripsi, dan integrasi dengan platform SIEM atau observabilitas Anda.

Panduan ini mencakup cara mengaktifkan kolektor khusus, data apa yang akan Anda terima, dan referensi skema span lengkap.

Kolektor OTEL khusus tersedia untuk organisasi Claude Enterprise dan untuk penyebaran penyedia langsung (Amazon Bedrock, Google Vertex AI, atau gateway).

Apa yang akan Anda terima

Saat Anda mengonfigurasi kolektor khusus, agen Office mengirimkan data jejak yang mencakup setiap giliran pengguna. Setiap giliran menghasilkan pohon span yang menangkap prompt, panggilan model, eksekusi alat, unggahan file, dan peristiwa pemadatan konteks.

Kolektor Anda menerima semua atribut span, termasuk yang membawa konten yang dihasilkan pengguna (teks prompt, input dan output alat, URL dokumen, dan nama file). Tidak ada atribut yang dihapus atau disaring. Teks respons asisten tidak disertakan dalam data span yang dipancarkan. Organisasi Anda memiliki data ini.

Penting: Metrik tidak dikirim ke kolektor khusus. Namespace penghitung office_agent.* hanya mengarah ke Anthropic. Namun, setiap kenaikan penghitung juga muncul sebagai peristiwa span pada span aktif, sehingga sinyal yang sama tersedia dalam jejak Anda.

Telemetri dikirim melalui OTLP/HTTP ke titik akhir Anda di {your_url}/v1/traces. gRPC tidak didukung karena add-in berjalan di Office WebView.

Aktifkan kolektor khusus

Pengaturan berbeda tergantung pada cara organisasi Anda melakukan autentikasi dengan Claude.

Penting: Saat titik akhir khusus dikonfigurasi, telemetri hanya pergi ke kolektor Anda. Span tidak dikirim ganda ke Anthropic.

Organisasi Claude Enterprise (OAuth)

Administrator organisasi menetapkan titik akhir kolektor di konsol admin Claude.ai di bawah Pengaturan organisasi > Agen Office. Pengaturan berlaku di seluruh organisasi.

Pengaturan	Deskripsi
`otlp_endpoint`	URL dasar kolektor OTLP Anda. Add-in menambahkan /v1/traces. HTTPS sangat disarankan.
`otlp_headers`	Header autentikasi opsional, diformat sesuai spesifikasi OpenTelemetry: key1=value1,key2=value2

Protokol harus berbasis HTTP OTLP. gRPC ditolak pada waktu konfigurasi.

Penyebaran penyedia langsung (Amazon Bedrock, Google Vertex AI, gateway)

Untuk penyebaran yang melakukan autentikasi terhadap penyedia model Anda sendiri daripada Claude.ai, titik akhir kolektor disediakan melalui salah satu dari tiga saluran konfigurasi. Ketiga saluran menggunakan dua kunci yang sama.

Direkomendasikan: Gunakan plugin claude-in-office untuk Claude Code. Plugin ini memandu Anda dalam menghasilkan manifes, mendaftarkan atribut ekstensi Entra, dan menyiapkan titik akhir bootstrap dengan otlp_endpoint dan otlp_headers yang sudah terkabel. Tiga saluran di bawah didokumentasikan untuk referensi dan pengaturan manual.

Kunci	Format	Deskripsi
`otlp_endpoint`	URL HTTPS	URL dasar kolektor OTLP Anda. Add-in menghapus garis miring akhir apa pun dan menambahkan /v1/traces.
`otlp_headers`	key1=value1,key2=value2	Header autentikasi opsional. Format yang sama dengan variabel lingkungan OTEL_EXPORTER_OTLP_HEADERS OpenTelemetry.

Jika otlp_endpoint tidak diatur atau kosong, tidak ada kolektor khusus yang dikonfigurasi dan add-in kembali ke perilaku default.

Catatan: Saluran konfigurasi ini hanya berlaku untuk penyebaran Microsoft Office. Add-in Google Workspace dikonfigurasi secara terpisah.

Saluran 1: Parameter URL Manifes

Tambahkan kunci sebagai parameter string kueri ke URL taskpane di manifes add-in khusus Anda:

https://<addin-host>/taskpane.html?otlp_endpoint=https://otel-collector.your-domain.com&otlp_headers=Authorization=Bearer%20<token>

Enkode URL nilainya. Ini menerapkan konfigurasi ke setiap pengguna yang memasang manifes.

Saluran 2: Ekstensi direktori Azure Entra ID

Untuk konfigurasi per pengguna, daftarkan kunci sebagai atribut ekstensi direktori Entra ID dan tetapkan melalui Microsoft Graph. Add-in membacanya dari token ID pengguna menggunakan Nested App Authentication (NAA).

Nama klaim dalam token ID yang dikeluarkan mengikuti format ekstensi direktori Azure:

Klaim	Memetakan ke
`extn.otlp_endpoint`	otlp_endpoint
`extn.otlp_headers`	otlp_headers

Atur ini per pengguna dengan Graph PATCH terhadap objek pengguna. Azure mengenkode nilai ekstensi direktori sebagai array elemen tunggal dalam token ID; add-in membuka kemasannya secara otomatis. Saluran ini memerlukan entra_sso=1 dalam parameter URL manifes untuk mengaktifkan akuisisi token NAA.

Saluran 3: Respons titik akhir bootstrap

Jika penyebaran Anda menggunakan titik akhir bootstrap (titik akhir JSON yang dihosting organisasi Anda yang dipanggil add-in saat startup), sertakan kunci dalam badan respons:

{
  "otlp_endpoint": "https://otel-collector.your-domain.com",
  "otlp_headers": "Authorization=Bearer <token>"
}

URL titik akhir bootstrap itu sendiri dikonfigurasi melalui bootstrap_url dalam parameter URL manifes atau klaim Entra extn.bootstrap_url. Jika token ID Entra diperoleh, token tersebut diteruskan ke titik akhir bootstrap sebagai header otorisasi Bearer sehingga titik akhir Anda dapat mengautentikasi pengguna sebelum mengembalikan konfigurasi per pengguna.

Prioritas

Ketika beberapa saluran menyediakan nilai, saluran yang lebih baru menimpa yang lebih awal: parameter manifes dibaca terlebih dahulu, kemudian klaim Entra, kemudian respons bootstrap. Respons bootstrap menang.

Jika Anda belum melakukannya, jalur tercepat adalah plugin claude-in-office.

Mode penyebaran

Ekspor kolektor khusus tersedia di kedua mode penyebaran:

Claude.ai Enterprise (OAuth): jejak audit lengkap termasuk identitas pengguna (user.email, user.account_uuid, organization.id), metadata server MCP, dan catatan unggahan file.
Penyedia langsung (Bedrock, Vertex AI, gateway): jejak audit inti (prompt, input dan output alat, URL dokumen) tetapi tanpa identitas pengguna, tanpa metadata MCP, dan tanpa rentang unggahan file. Atribusi pengguna memerlukan korelasi session.id terhadap log penyedia identitas Anda sendiri.

Muatan audit inti identik di kedua mode. Penyebaran penyedia langsung kekurangan konteks akun Claude.ai, jadi atribut yang berasal dari profil pengguna atau organisasi Claude.ai tidak ada. Lihat tag [claude.ai-only] dalam skema rentang di bawah untuk daftar lengkap.

Label permukaan dan vendor

Setiap rentang mencakup dua label yang mengidentifikasi aplikasi Office dan platform mana yang menghasilkannya. Gunakan ini sebagai dimensi utama Anda untuk penyaringan dan dasbor.

Label	Nilai
`agent.surface`	sheet (Excel/Google Sheets), doc (Word), slide (PowerPoint)
`agent.vendor`	m (Microsoft)

Referensi rentang

Setiap giliran pengguna menghasilkan pohon induk/anak hingga lima jenis rentang. Atribut yang ditandai [content] membawa data yang dihasilkan pengguna; ini membentuk muatan audit Anda. Atribut yang ditandai [claude.ai-only] diisi hanya ketika pengguna masuk dengan akun Claude; mereka tidak ada pada penyebaran Bedrock, Vertex AI, dan gateway. Atribut yang tidak ada dihilangkan dari rentang sepenuhnya (tidak ada kunci dengan nilai null).

Rentang file.upload dan semua atribut mcp.* juga [claude.ai-only], karena unggahan file dan koneksi server MCP adalah fitur platform Claude.

Untuk penyebaran penyedia langsung, identitas pengguna harus dikorelasikan melalui session.id dan document.url, digabungkan dengan log sesi penyedia identitas Anda.

Atribut sumber daya

Atribut ini muncul di setiap rentang:

Atribut	Deskripsi
`service.name`	Nilai tetap: office-agent
`service.version`	Nilai tetap: 1.0.0
`git.sha`	Identifikasi komit build

agent.query (rentang akar)

Satu rentang per giliran pengguna. Ini adalah akar pohon rentang dan membawa identitas sesi, konteks dokumen, dan status server MCP. SpanKind: INTERNAL.

Atribut	Deskripsi
`agent.surface`	sheet \| doc \| slide
`agent.vendor`	m
`user.message [content]`	Prompt pengguna (4000 karakter pertama)
`session.id`	Identifikasi sesi buram
`user.email [claude.ai-only]`	Alamat email pengguna
`user.bucket [claude.ai-only]`	Bucket hash deterministik (SHA-256 email, mod 30)
`user.account_uuid [claude.ai-only]`	UUID akun Claude
`document.url [content]`	URL dokumen Office yang terbuka
`organization.id [claude.ai-only]`	UUID organisasi Claude
`org.rate_limit_tier [claude.ai-only]`	Tingkat langganan Claude
`org.type [claude.ai-only]`	Jenis organisasi Claude
`agent.selected_model`	Model yang dipilih pengguna untuk sesi ini
`office.platform`	PC \| Mac \| OfficeOnline \| iOS \| Android \| Universal
`office.version`	Nomor build Office
`mcp.configured_count [claude.ai-only]`	Jumlah server MCP yang dikonfigurasi
`mcp.connected_count [claude.ai-only]`	Jumlah server MCP yang berhasil terhubung
`mcp.failed_count [claude.ai-only]`	Jumlah server MCP yang gagal terhubung
`mcp.fetch_status [claude.ai-only]`	success \| error \| timeout \| no_auth \| not_attempted
`mcp.fetch_duration_ms [claude.ai-only]`	Durasi pengambilan registri MCP
`mcp.fetch_http_status [claude.ai-only]`	Kode status HTTP pengambilan registri MCP
`mcp.servers [content] [claude.ai-only]`	Detail server MCP terserialisasi (nama, jumlah alat, pesan kesalahan)
`file.upload.count [claude.ai-only]`	Jumlah file yang dilampirkan pada giliran ini
`file.upload.total_bytes [claude.ai-only]`	Total byte yang diunggah
`file.upload.image_count [claude.ai-only]`	Jumlah lampiran gambar
`file.upload.document_count [claude.ai-only]`	Jumlah lampiran dokumen
`file.upload.other_count [claude.ai-only]`	Jumlah lampiran lainnya
`error.name`	Nama kelas pengecualian (ada saat terjadi kegagalan)
`agent.query_phase`	Fase di mana kueri gagal (ada saat terjadi kegagalan)

agent.stream

Satu span per panggilan API ke Claude, sebagai anak dari span kueri. SpanKind: CLIENT.

Atribut	Deskripsi
`model`	ID model yang digunakan untuk panggilan ini
`max_tokens`	Token output maksimum yang diminta
`agent.message_count`	Jumlah pesan dalam percakapan saat aliran dimulai
`input_tokens`	Token input yang ditagih (dari respons API)
`output_tokens`	Token output yang ditagih (dari respons API)
`cache_read_tokens`	Token yang disajikan dari cache prompt
`cache_creation_tokens`	Token yang ditulis ke cache prompt
`stop_reason`	end_turn \| tool_use \| max_tokens \| dll.
`request_id`	Header request-id API Anthropic, dapat digunakan untuk korelasi dukungan

Catatan tentang caching prompt: Add-in meminta caching prompt tanpa syarat. Atribut cache_read_tokens dan cache_creation_tokens diatur dari respons API penyedia dan dihilangkan ketika respons tidak menyertakannya. Caching prompt tersedia untuk Platform Developer Claude; pada saat penulisan ini, Amazon Bedrock dan Google Vertex AI belum mengembalikan bidang ini melalui klien yang digunakan add-in. Ketika dukungan tersedia di penyedia Anda, atribut ini akan mulai muncul secara otomatis.

agent.tool_execution

Satu span per panggilan alat, sebagai anak dari span aliran. SpanKind: INTERNAL. Ini adalah catatan utama tentang tindakan apa yang diambil model terhadap dokumen.

Atribut	Deskripsi
`tool_name`	Pengenal alat (misalnya get_cell_ranges, execute_office_js, edit_slide_xml)
`tool.id`	ID unik dari pemanggilan alat ini
`tool.caller`	server \| client
`tool.owner`	first_party \| mcp \| server
`tool.read_write`	read \| write \| read_write
`tool.accept_decision`	manual \| auto_accept \| deferred
`tool.input [content]`	Input alat terserialisasi (4000 karakter pertama)
`tool.success`	Boolean
`tool.output [content]`	Output alat terserialisasi (4000 karakter pertama)
`tool.output_chars`	Panjang output penuh dalam karakter (gunakan untuk mendeteksi pemotongan)
`tool.error_type`	Klasifikasi kesalahan (ada saat kegagalan)
`sheet.cells_read`	Sel yang dibaca (hanya permukaan lembar)
`sheet.cells_written`	Sel yang ditulis (hanya permukaan lembar)
`sheet.cells_copied`	Sel yang disalin (hanya permukaan lembar)

Catatan: Atribut tool.accept_decision mencatat bagaimana keputusan izin dibuat: manual (pengguna menyetujui tindakan spesifik ini), auto_accept (pengguna sebelumnya telah memberikan persetujuan berdiri), atau deferred (tindakan antri untuk ditinjau nanti). Gunakan ini untuk mengaudit pola persetujuan di seluruh organisasi Anda.

agent.compaction

Satu span per percakapan auto-summarization, dipicu ketika konteks mendekati batas jendela. SpanKind: CLIENT.

Atribut	Deskripsi
`compaction.pre_tokens`	Jumlah token sebelum summarization
`compaction.post_tokens`	Jumlah token setelah summarization
`compaction.tokens_saved`	Delta
`compaction.success`	Boolean
`compaction.trigger`	Saat ini selalu reaktif

Span ini juga membawa agent.surface, agent.vendor, session.id, user.email [claude.ai-only], user.bucket [claude.ai-only], office.platform, dan office.version, diduplikasi dari root span sehingga Anda dapat menanyakan peristiwa compaction secara independen.

file.upload [claude.ai-only]

Satu span per unggahan file individual, sebagai anak dari query span. SpanKind: CLIENT. Jenis span ini hanya muncul ketika pengguna masuk dengan akun Claude.ai. Unggahan file tidak tersedia di penerapan penyedia langsung.

Atribut	Deskripsi
`file.upload.filename [content]`	Nama file asli
`file.upload.size_bytes`	Ukuran file
`file.upload.mime_type`	Tipe MIME
`file.upload.file_id`	Pengenal Anthropic Files API
`file.upload.success`	Boolean

Peristiwa span

Peristiwa span adalah penanda dengan stempel waktu yang terlampir pada span di atas. Mereka menangkap transisi siklus hidup dan sinyal setara penghitung.

agent.query: exception {exception.type}; file_upload {file_id, mime_type, content_category}
agent.stream: first_token; stream_complete; stream_error {exception.type}
agent.tool_execution: tool_init; tool_run; tool_result; tool_error {error_type}
agent.compaction: compaction_start; compaction_complete; compaction_error {exception.type}
file.upload: exception {exception.type}

Setiap penghitung produk internal juga mencatat peristiwa span dengan nama yang sama pada span yang sedang aktif, memberikan setara dengan aliran metrik dalam data jejak Anda. Peristiwa office_agent.token.usage dipancarkan pada setiap span agent.stream, sekali per jenis token bukan nol, dengan atribut {token_usage.type: input | output | cacheRead | cacheCreation, token_usage.model, token_usage.token_count}. Ini mencerminkan bentuk penghitung *.token.usage yang dipancarkan oleh produk Anthropic lainnya, sehingga satu kolektor dapat mengagregasi biaya token di seluruh produk dengan mengelompokkan pada service.name.

Perilaku spesifik permukaan

Skema telemetri konsisten di semua permukaan. Ini adalah perbedaannya:

Sheets (Excel): span agent.tool_execution mencakup atribut sheet.cells_read, sheet.cells_written, dan sheet.cells_copied. Peristiwa span office_agent.cell_edit_collision_total muncul ketika pengguna sedang mengedit sel sementara alat mencoba menulis.
Documents (Word): peristiwa corong edit dokumen melacak siklus hidup edit: office_agent.doc_edit_received_total, office_agent.doc_edit_parsed_total, office_agent.doc_edit_applied_total, office_agent.doc_proposed_edit_reviewed_total. Tidak ada atribut sheet.cells_*.
Slides (PowerPoint): tidak ada atribut atau peristiwa spesifik permukaan di luar skema umum.

Merekonstruksi sesi pengguna

Penerapan Claude.ai

Filter span berdasarkan user.email (atau user.account_uuid) dan session.id.
Urutkan span agent.query berdasarkan stempel waktu awal; masing-masing adalah satu giliran pengguna.
Untuk setiap giliran, user.message adalah prompt dan document.url adalah file yang sedang dikerjakan.
Span agent.tool_execution anak, diurutkan berdasarkan stempel waktu, adalah tindakan yang diambil: tool.input adalah apa yang dicoba, tool.output adalah hasilnya, tool.accept_decision mencatat apakah pengguna secara eksplisit menyetujui.

Penerapan penyedia langsung

Add-in tidak memiliki identitas pengguna Claude.ai dalam mode ini, jadi span tidak membawa user.email atau user.account_uuid. Untuk mengatribusikan aktivitas kepada pengguna:

Filter span berdasarkan session.id untuk mengisolasi satu sesi add-in berkelanjutan.
Gunakan document.url untuk mengidentifikasi file yang sedang dikerjakan.
Korelasikan sesi terhadap log penyedia identitas Anda: acara masuk Entra, log akses gateway, atau log permintaan endpoint bootstrap Anda (yang menerima token Entra ID pengguna sebagai header Bearer).
Setelah sesi dikaitkan dengan pengguna, rekonstruksi per-turn identik: agent.query diurutkan berdasarkan timestamp, dengan user.message, tool.input, tool.output, dan tool.accept_decision menyediakan jejak audit.

Ini menghasilkan transkrip lengkap dan terurut dari interaksi dalam kedua mode penyebaran.