NextPDF Connect observeren met OpenTelemetry

In één oogopslag

NextPDF bevat ingebouwde OpenTelemetry-instrumentatie die trace-spans en metrische gegevens uitstuurt tijdens de volledige levenscyclus van het genereren van een Portable Document Format (PDF)-document. Wanneer er geen OpenTelemetry Software Development Kit (SDK) op het klassenpad staat, blijft de instrumentatie inactief: er is geen prestatieverlies, geen autoload-fout en niets om te configureren. Deze pagina is transport-onafhankelijk, dus dezelfde instrumentatie geldt ongeacht hoe je een PDF genereert: via een in-procesaanroep, een Model Context Protocol (MCP) tools/call, een Representational State Transfer (REST)-verzoek of een gRPC-aanroep naar NextPDF Connect.

Zie deze pagina als uitleg, niet als een uitvoerbaar recipe. De hosttoepassing levert de OpenTelemetry-SDK en een exporter. NextPDF doet dat niet. Omdat er geen op zichzelf staand voorbeeld is, legt deze pagina geen reproduceerbare hash vast.

Installeren

De hosttoepassing kiest en installeert de OpenTelemetry-SDK en één exporter. NextPDF leest een globaal geregistreerde tracer-provider en bundelt geen eigen SDK. Voordat je op traces vertrouwt, voer je de meegeleverde beschikbaarheidsprobe uit om te bevestigen dat NextPDF de SDK kan zien. De probe retourneert alleen true wanneer de OpenTelemetry Application Programming Interface (API) op het klassenpad staat.

Conceptueel overzicht

NextPDF zendt spans uit voor de levenscyclus van de documentopbouw en voor een kleine set tellers en histogrammen. De spans omvatten een root-build-span, lettertype-resolutie, het parsen van HyperText Markup Language (HTML), lay-out, het decoderen van afbeeldingen, serialisatie en de optionele fasen voor barcode, formulier, navigatie en bijlage. De metrische gegevens omvatten de weergaveduur, het aantal pagina’s, waarschuwingen, piekgeheugen, uitvoergrootte, het aantal lettertypen en het aantal afbeeldingen. De exacte lijst met spans en metrische gegevens hangt af van de geïnstalleerde NextPDF-versie, dus beschouw elk vast aantal in oudere tekst als versie-afhankelijk. Controleer dit aan de hand van de build die draait, in plaats van een getal te onthouden.

Wanneer NextPDF Connect achter een webframework draait, verschijnt een Connect-aanroep als onderliggend element van de trace van het binnenkomende Hypertext Transfer Protocol (HTTP)-verzoek. Eén gedistribueerde trace omvat dan het HTTP-instappunt, de toepassing en de PDF-build.

API-oppervlak

Deze pagina definieert geen Connect-tool. In plaats daarvan beschrijft zij overkoepelende instrumentatie. Zie voor het tooloppervlak /connect/tool-catalog/. Zie voor transporten /transports/mcp/, /transports/rest/ en /transports/grpc/.

Codevoorbeeld — Snel aan de slag

Bouw en registreer globaal een tracer-provider voordat je een PDF genereert en genereer daarna zoals gebruikelijk. De interne instrumentatie van NextPDF zendt de spans en metrische gegevens automatisch uit, zonder code per aanroep. Leeg de provider bij het afsluiten van het proces, zodat gebufferde spans niet verloren gaan. De hosttoepassing is eigenaar van de concrete koppeling tussen provider en exporter. Het OpenTelemetry PHP-project documenteert die koppeling; deze pagina herhaalt die niet woordelijk.

Codevoorbeeld — Productie

Voor een collector die via HTTP exporteert, levert de host een PSR-18 HTTP-client. Behandel een transportfout en een niet-geslaagde HTTP-status als afzonderlijke gevallen. Een PSR-18-client genereert alleen een getypeerde clientuitzondering wanneer die het verzoek helemaal niet kan verzenden (PSR-18 §4). Een 4xx/5xx-respons daarentegen wordt normaal aan de aanroeper teruggegeven en is geen uitzondering (PSR-18 §4). Het exportpad van de collector en het transport van de Connect-tool zijn onafhankelijk van elkaar, dus een mislukte collector-export mag de PDF-generatie zelf nooit laten mislukken.

Randgevallen en valkuilen

Provider geregistreerd na de eerste PDF-generatie. Elke span die vóór de registratie wordt aangemaakt, gebruikt een no-op-tracer en bereikt nooit de backend. Registreer de provider tijdens het opstarten van de toepassing.
Geen leegmaken bij afsluiten. Een batchprocessor buffert spans, en die gaan verloren als het proces stopt zonder de provider af te sluiten. Koppel het afsluiten van de provider aan de worker of aan de kernel-terminate-hook.
gRPC-export vereist de gRPC PHP-extensie. HTTP-export vereist geen extensie, dus kies HTTP wanneer de extensie niet beschikbaar is.
W3C Trace Context-propagatie. Wanneer het binnenkomende verzoek traceparent/tracestate bevat, propageert de SDK die context automatisch naar de spans van NextPDF, en sluit de Connect-aanroep zich aan bij de trace van de aanroeper.

Prestaties

De overhead van de instrumentatie is klein vergeleken met de tijd die PDF-generatie kost. Het budget in de front matter is een documentatielimiet, geen garantie. Gebruik bij hoge verzoeksnelheden head-based of collector-zijdige sampling om het exportervolume en de kosten te begrenzen.

Beveiligingsopmerkingen

Veilige telemetrie en het opschonen van logs

NextPDF dwingt een strikt, niet te omzeilen beleid voor telemetriegegevens af. Een vaste allowlist van attributen exporteert alleen structurele metagegevens en prestatiegegevens: aantallen pagina’s, lettertypen en afbeeldingen, bestandsgroottes, namen van uitvoerprofielen, booleaanse vlaggen, looptijden, geheugen en identificatoren voor versie en niveau. NextPDF exporteert nooit documentinhoud, bestandspaden, ruwe stream-bytes, base64-payloads, persoonsgegevens of inloggegevens. Het verwijdert elk attribuut dat buiten de allowlist valt. Het verwijdert ook elke waarde die overeenkomt met een payloadpatroon, zelfs wanneer de sleutel zelf is toegestaan. Daardoor kunnen traces door een gedeelde observability-pijplijn stromen zonder dat er documentgegevens lekken. Dit is gedrag van de bibliotheek, geen garantie op deploymentniveau over de backend die de traces ontvangt.

Conformiteit

Bewering	Clausule	reference_id
Een transportfout is het enige geval van een PSR-18 clientuitzondering	PSR-18 §4
Een 4xx/5xx-respons is een normale terugkeer, geen uitzondering	PSR-18 §4

Het OpenTelemetry-protocol en het Trace Context-formaat van het World Wide Web Consortium (W3C) zijn externe specificaties die elk door hun eigen organisatie worden onderhouden. Deze pagina beweert geen conformiteit met deze specificaties en geeft hun tekst niet weer. De gezaghebbende definities staan in de gepubliceerde OpenTelemetry-specificatie (https://opentelemetry.io/docs/specs/otel/) en de W3C Trace Context Recommendation (https://www.w3.org/TR/trace-context/).

Commerciële context

Niet van toepassing — instrumentatie is een kernfunctionaliteit en is niet afgeschermd.

Connect-bijzonderheden

Beschikbaarheid van transporten (MCP / REST / gRPC)

De instrumentatie is transport-onafhankelijk. Een Connect-aanroep via welk transport dan ook produceert dezelfde spans voor de build-levenscyclus. Het transport voegt zijn eigen omsluitende span toe wanneer de host de transportlaag instrumenteert.

HITL-risiconiveau

Observability staat los van het risicomodel. Het uitsturen van telemetrie verandert het risiconiveau van een tool niet en wordt nooit afgeschermd door de ConfirmationGate.

JSON-envelop van de bevestigingspoort

Niet van toepassing — het uitsturen van telemetrie is geen toolaanroep en loopt dus niet via de poort.

Zie ook

/connect/tool-catalog/ — het geobserveerde tooloppervlak.
/transports/mcp/ / /transports/rest/ / /transports/grpc/ — de transporten die een getracede Connect-aanroep kunnen ontvangen.