Osservabilità di NextPDF Connect con OpenTelemetry

In sintesi

NextPDF include una strumentazione OpenTelemetry integrata che emette span di traccia e metriche lungo l’intero ciclo di vita della generazione del PDF. Quando nel class path non è presente alcun SDK OpenTelemetry, la strumentazione resta inerte: nessun impatto sulle prestazioni, nessun errore di autoload e nulla da configurare. Questa è una pagina concettuale indipendente dal trasporto, quindi la stessa strumentazione si applica qualunque sia il modo in cui viene generato un PDF — tramite una chiamata in-process, un tools/call MCP, una richiesta REST o una chiamata gRPC verso NextPDF Connect.

Considerare questa pagina una spiegazione, non una ricetta eseguibile. È l’applicazione host a fornire l’SDK OpenTelemetry e un exporter, non NextPDF; di conseguenza, qui non esiste un esempio autonomo a cui ancorare un hash riproducibile.

Installazione

Spetta all’applicazione host scegliere e installare l’SDK OpenTelemetry e un exporter. NextPDF legge un tracer provider registrato globalmente e non include un proprio SDK. Prima di affidarsi alle tracce, verificare che NextPDF riesca a vedere l’SDK eseguendo la sonda di disponibilità inclusa. La sonda restituisce true solo quando l’API OpenTelemetry è presente nel class path.

Panoramica concettuale

NextPDF emette span per il ciclo di vita di costruzione del documento e un piccolo insieme di contatori e istogrammi. Gli span includono uno span radice della build, oltre alla risoluzione dei font, al parsing dell’HTML, al layout, alla decodifica delle immagini, alla serializzazione e alle fasi opzionali di barcode, form, navigazione e allegati. Le metriche coprono la durata del rendering, il numero di pagine, gli avvisi, il picco di memoria, la dimensione dell’output, il numero di font e il numero di immagini. L’inventario esatto di span e metriche dipende dalla versione di NextPDF installata, quindi considerare qualsiasi conteggio fisso in testi meno recenti come dipendente dalla versione: verificarlo rispetto alla build in esecuzione anziché memorizzare un numero.

Quando NextPDF Connect viene eseguito dietro un framework web, una chiamata Connect compare come figlia della traccia della richiesta in ingresso. Un’unica traccia distribuita copre quindi l’ingresso HTTP, l’applicazione e la build del PDF.

Superficie API

Questa pagina non dichiara alcuno strumento Connect. Descrive invece una strumentazione trasversale. Per la superficie degli strumenti consultare /connect/tool-catalog/; per i trasporti consultare /transports/mcp/, /transports/rest/ e /transports/grpc/.

Esempio di codice — Avvio rapido

Costruire e registrare globalmente un tracer provider prima che venga generato qualsiasi PDF, quindi procedere con la generazione normale. La strumentazione interna di NextPDF emette automaticamente gli span e le metriche, senza codice specifico per ogni chiamata. Eseguire il flush del provider all’arresto del processo, in modo che gli span bufferizzati non vadano persi. La configurazione concreta di provider ed exporter è una scelta dell’applicazione host; il progetto OpenTelemetry PHP la documenta e questa pagina non ne riproduce il contenuto.

Esempio di codice — Produzione

Per esportare verso un collector via HTTP, l’host fornisce un client HTTP PSR-18. Trattare un errore di trasporto e uno stato HTTP non di successo come due casi distinti. Un client PSR-18 solleva un’eccezione client tipizzata solo quando non riesce affatto a inviare la richiesta (PSR-18 §4). Una risposta 4xx/5xx, al contrario, viene restituita normalmente al chiamante e non è un’eccezione (PSR-18 §4). Il percorso di esportazione verso il collector e il trasporto dello strumento Connect sono indipendenti, quindi un fallimento dell’esportazione verso il collector non deve mai poter far fallire la generazione stessa del PDF.

Casi limite e insidie

Provider registrato dopo la prima generazione. Qualsiasi span creato prima della registrazione utilizza un tracer no-op e non raggiunge mai il backend. Registrare il provider durante l’avvio dell’applicazione.
Nessun flush all’arresto. Un batch processor bufferizza gli span, che vengono persi se il processo termina senza un arresto del provider. Collegare l’arresto al worker o all’hook terminate del kernel.
L’esportazione gRPC richiede l’estensione PHP gRPC. L’esportazione HTTP non richiede alcuna estensione, perciò scegliere HTTP quando l’estensione non è disponibile.
Propagazione del W3C Trace Context. Quando la richiesta in ingresso trasporta traceparent/tracestate, l’SDK propaga automaticamente tale contesto negli span di NextPDF e la chiamata Connect si unisce alla traccia del chiamante.

Prestazioni

L’overhead della strumentazione è ridotto rispetto al tempo di generazione del PDF. Il budget nel front-matter è un limite documentale, non una garanzia. Con frequenze di richiesta elevate, usare il campionamento head-based o lato collector per limitare il volume e il costo dell’exporter.

Note di sicurezza

Telemetria sicura e sanitizzazione dei log

NextPDF applica una politica rigorosa e non aggirabile per i dati di telemetria. Un’allowlist fissa di attributi esporta solo metadati strutturali e metriche di prestazione: conteggi di pagine, font e immagini, dimensioni dei file, nomi dei profili di output, flag booleani, durate, memoria e identificatori di versione e livello. Il contenuto del documento, i percorsi dei file, i byte grezzi dei flussi, i payload base64, i dati personali e le credenziali non vengono mai esportati. Qualsiasi attributo al di fuori dell’allowlist viene scartato, così come qualsiasi valore che corrisponda a un pattern di payload, anche quando la chiave stessa è consentita. Questa proprietà permette alle tracce di confluire in una pipeline di osservabilità condivisa senza divulgare i dati del documento. È un comportamento della libreria, non una garanzia del deployment sul backend che riceve le tracce.

Conformità

Dichiarazione	Clausola	reference_id
L’errore di trasporto è l’unico caso di eccezione client PSR-18	PSR-18 §4
Una risposta 4xx/5xx è un ritorno normale, non un’eccezione	PSR-18 §4

Il protocollo OpenTelemetry e il formato W3C Trace Context sono specifiche esterne, ciascuna mantenuta dal rispettivo ente. Questa pagina non dichiara conformità a tali specifiche e non ne riproduce il testo. Le definizioni autorevoli risiedono nella specifica OpenTelemetry pubblicata (https://opentelemetry.io/docs/specs/otel/) e nella Raccomandazione W3C Trace Context (https://www.w3.org/TR/trace-context/).

Contesto commerciale

Non applicabile — la strumentazione è una funzionalità core e non è soggetta a gating.

Specifiche di Connect

Disponibilità dei trasporti (MCP / REST / gRPC)

La strumentazione è indipendente dal trasporto. Una chiamata Connect su qualsiasi trasporto produce gli stessi span del ciclo di vita di build; il trasporto aggiunge il proprio span avvolgente quando l’host strumenta il livello di trasporto.

Livello di rischio HITL

L’osservabilità è ortogonale al modello di rischio. L’emissione di telemetria non modifica il livello di rischio di uno strumento e non è mai soggetta al gating della ConfirmationGate.

Envelope JSON della confirmation gate

Non applicabile — l’emissione di telemetria non è un’invocazione di strumento, quindi non attraversa la gate.

Vedere anche

/connect/tool-catalog/ — la superficie degli strumenti osservabile.
/transports/mcp/ / /transports/rest/ / /transports/grpc/ — i trasporti sui quali può arrivare una chiamata Connect tracciata.