Mengamati NextPDF Connect dengan OpenTelemetry

Sekilas pandang

NextPDF menyertakan instrumentasi OpenTelemetry bawaan yang memancarkan span jejak dan metrik di sepanjang siklus hidup pembuatan Portable Document Format (PDF). Ketika Software Development Kit (SDK) OpenTelemetry tidak ada pada class path, instrumentasi tetap nonaktif: tidak ada penalti kinerja, tidak ada kegagalan autoload, dan tidak ada yang perlu dikonfigurasi. Halaman ini agnostik terhadap transport, sehingga instrumentasi yang sama berlaku untuk cara apa pun Anda membuat PDF: melalui panggilan in-process, sebuah tools/call Model Context Protocol (MCP), sebuah permintaan Representational State Transfer (REST), atau sebuah panggilan gRPC terhadap NextPDF Connect.

Perlakukan halaman ini sebagai penjelasan, bukan resep yang dapat dijalankan. Aplikasi host menyediakan SDK OpenTelemetry dan sebuah exporter. NextPDF tidak menyediakannya. Karena tidak ada contoh yang berdiri sendiri, halaman ini tidak menyematkan hash yang dapat direproduksi.

Pemasangan

Aplikasi host memilih dan memasang SDK OpenTelemetry serta satu exporter. NextPDF membaca tracer provider yang terdaftar secara global dan tidak menyertakan SDK-nya sendiri. Sebelum Anda mengandalkan jejak, jalankan probe ketersediaan bawaan untuk memastikan NextPDF dapat melihat SDK tersebut. Probe tersebut mengembalikan true hanya ketika Application Programming Interface (API) OpenTelemetry berada pada class path.

Gambaran konseptual

NextPDF memancarkan span untuk siklus hidup pembuatan dokumen serta sekumpulan kecil counter dan histogram. Span tersebut mencakup span build akar, resolusi fon, penguraian HyperText Markup Language (HTML), tata letak, dekode gambar, serialisasi, serta fase barcode, formulir, navigasi, dan lampiran yang opsional. Metrik tersebut mencakup durasi rendering, jumlah halaman, peringatan, memori puncak, ukuran keluaran, jumlah fon, dan jumlah gambar. Inventaris span dan metrik yang persis bergantung pada versi NextPDF yang terpasang, jadi perlakukan setiap jumlah tetap dalam teks yang lebih lama sebagai bergantung pada versi. Konfirmasikan pada build yang sedang berjalan, bukan dengan menghafal angka tertentu.

Ketika NextPDF Connect berjalan di balik framework web, sebuah panggilan Connect muncul sebagai anak dari jejak permintaan Hypertext Transfer Protocol (HTTP) yang masuk. Sebuah jejak terdistribusi tunggal kemudian membentang dari titik masuk HTTP, aplikasi, hingga build PDF.

Permukaan API

Halaman ini tidak menyatakan adanya tool Connect. Sebagai gantinya, halaman ini menjelaskan instrumentasi lintas-cakupan. Untuk permukaan tool, lihat /connect/tool-catalog/. Untuk transport, lihat /transports/mcp/, /transports/rest/, dan /transports/grpc/.

Contoh kode — Mulai cepat

Bangun dan daftarkan tracer provider secara global sebelum Anda membuat PDF apa pun, lalu buat PDF seperti biasa. Instrumentasi internal NextPDF memancarkan span dan metrik secara otomatis, tanpa kode per panggilan. Bersihkan (flush) provider saat proses dimatikan agar span yang tertahan di buffer tidak hilang. Aplikasi host memiliki perangkaian provider dan exporter yang konkret. Proyek OpenTelemetry PHP mendokumentasikan perangkaian tersebut, dan halaman ini tidak menyatakannya kembali secara verbatim.

Contoh kode — Produksi

Untuk collector yang mengekspor melalui HTTP, host menyediakan klien HTTP PSR-18. Perlakukan kegagalan transport dan status HTTP yang tidak sukses sebagai dua kasus terpisah. Klien PSR-18 melempar client exception bertipe hanya ketika klien sama sekali tidak dapat mengirim permintaan (PSR-18 §4). Sebaliknya, respons 4xx/5xx dikembalikan ke pemanggil secara normal dan bukan merupakan exception (PSR-18 §4). Jalur ekspor collector dan transport tool Connect bersifat independen, sehingga kegagalan ekspor collector tidak boleh menggagalkan pembuatan PDF itu sendiri.

Kasus tepi & jebakan

Provider didaftarkan setelah pembuatan pertama. Setiap span yang dibuat sebelum pendaftaran menggunakan tracer no-op dan tidak pernah mencapai backend. Daftarkan provider saat boot aplikasi.
Tidak ada flush saat shutdown. Sebuah batch processor menyangga (buffer) span, dan span tersebut hilang jika proses berhenti tanpa melakukan shutdown provider. Rangkaikan shutdown provider ke worker atau hook terminate kernel.
Ekspor gRPC memerlukan ekstensi PHP gRPC. Ekspor HTTP tidak memerlukan ekstensi apa pun, jadi pilih HTTP ketika ekstensi tersebut tidak tersedia.
Penyebaran W3C Trace Context. Ketika permintaan yang masuk membawa traceparent/tracestate, SDK secara otomatis menyebarkan konteks tersebut ke dalam span NextPDF, dan panggilan Connect bergabung dengan jejak pemanggil.

Kinerja

Overhead instrumentasi kecil dibandingkan dengan waktu pembuatan PDF. Anggaran front-matter adalah batas atas dokumentasi, bukan jaminan. Pada laju permintaan yang tinggi, gunakan sampling berbasis head atau di sisi collector untuk membatasi volume dan biaya exporter.

Catatan keamanan

Telemetri aman & pembersihan log

NextPDF menerapkan kebijakan data telemetri yang ketat dan tidak dapat dilewati. Allowlist atribut tetap hanya mengekspor metadata struktural dan metrik kinerja: jumlah halaman, fon, dan gambar, ukuran berkas, nama profil keluaran, flag boolean, durasi, memori, serta pengidentifikasi versi dan tier. NextPDF tidak pernah mengekspor konten dokumen, jalur berkas, byte stream mentah, payload base64, data pribadi, atau kredensial. NextPDF membuang setiap atribut di luar allowlist. NextPDF juga membuang setiap nilai yang cocok dengan pola payload, bahkan ketika kuncinya sendiri diizinkan. Perilaku ini memungkinkan jejak mengalir ke pipeline observabilitas bersama tanpa membocorkan data dokumen. Ini adalah perilaku pustaka, bukan jaminan di tingkat deployment untuk backend yang menerima jejak tersebut.

Kesesuaian

Klaim	Klausa	reference_id
Kegagalan transport adalah satu-satunya kasus client-exception PSR-18	PSR-18 §4
Respons 4xx/5xx adalah pengembalian normal, bukan exception	PSR-18 §4

Protokol OpenTelemetry dan format Trace Context dari World Wide Web Consortium (W3C) adalah spesifikasi eksternal, yang masing-masing dipelihara oleh badannya sendiri. Halaman ini tidak menyatakan kesesuaian terhadapnya dan tidak mereproduksi teksnya. Definisi otoritatif berada dalam spesifikasi OpenTelemetry yang diterbitkan (https://opentelemetry.io/docs/specs/otel/) dan W3C Trace Context Recommendation (https://www.w3.org/TR/trace-context/).

Konteks komersial

Tidak berlaku — instrumentasi merupakan kapabilitas inti dan tidak dibatasi.

Hal-hal khusus Connect

Ketersediaan transport (MCP / REST / gRPC)

Instrumentasi ini agnostik terhadap transport. Sebuah panggilan Connect melalui transport apa pun menghasilkan span siklus hidup build yang sama. Transport menambahkan span pembungkusnya sendiri ketika host menginstrumentasi lapisan transport.

Tingkat risiko HITL

Observabilitas terpisah dari model risiko. Memancarkan telemetri tidak mengubah tingkat risiko sebuah tool dan tidak pernah dibatasi oleh ConfirmationGate.

Amplop JSON confirmation gate

Tidak berlaku — pemancaran telemetri bukan merupakan pemanggilan tool, sehingga tidak melewati gate tersebut.

Lihat juga

/connect/tool-catalog/ — permukaan tool yang diamati.
/transports/mcp/ / /transports/rest/ / /transports/grpc/ — transport yang dapat menerima panggilan Connect yang terlacak.