NextPDF Connect mit OpenTelemetry überwachen

Auf einen Blick

NextPDF enthält eine integrierte OpenTelemetry-Instrumentierung, die Trace-Spans und Metriken über den gesamten Lebenszyklus der PDF-Generierung ausgibt. Liegt kein OpenTelemetry-SDK auf dem Class Path, bleibt die Instrumentierung inaktiv: Es entstehen keine Performance-Einbußen, kein Autoload-Fehler und kein Konfigurationsaufwand. Die Seite ist transportunabhängig angelegt; dieselbe Instrumentierung gilt also unabhängig davon, wie ein PDF generiert wird: per In-Process-Aufruf, über einen MCP-tools/call, per REST-Anfrage oder per gRPC-Aufruf an NextPDF Connect.

Verstehen Sie diese Seite eher als Erklärung denn als ausführbares Rezept. Die Host-Anwendung stellt das OpenTelemetry-SDK und einen Exporter bereit, nicht NextPDF. Daher gibt es hier kein in sich geschlossenes Beispiel, für das diese Seite einen reproduzierbaren Hash ausweisen könnte.

Installation

Die Host-Anwendung wählt das OpenTelemetry-SDK und einen Exporter aus und installiert beides. NextPDF liest einen global registrierten Tracer Provider und bringt kein eigenes SDK mit. Bevor Sie sich auf Traces verlassen, prüfen Sie mit dem mitgelieferten Verfügbarkeits-Check, ob NextPDF das SDK sieht. Der Check liefert nur dann true, wenn die OpenTelemetry-API auf dem Class Path liegt.

Konzeptioneller Überblick

NextPDF gibt Spans für den Lebenszyklus des Dokumentaufbaus sowie einen kleinen Satz von Countern und Histogrammen aus. Die Spans umfassen einen Root-Build-Span sowie Fontauflösung, HTML-Parsing, Layout, Bilddekodierung, Serialisierung und die optionalen Phasen für Barcode, Formular, Navigation und Anhänge. Die Metriken umfassen Renderingdauer, Seitenzahl, Warnungen, Speicherspitze, Ausgabegröße, Fontanzahl und Bildanzahl. Da das genaue Inventar der Spans und Metriken von der installierten NextPDF-Version abhängt, sollten Sie jede feste Anzahl in älterem Text als versionsabhängig behandeln: Bestätigen Sie sie anhand des laufenden Builds, statt eine Zahl auswendig zu lernen.

Wenn NextPDF Connect hinter einem Web-Framework läuft, erscheint ein Connect-Aufruf als Kind des eingehenden Request-Traces. Ein einzelner verteilter Trace umspannt dann den HTTP-Eingang, die Anwendung und den PDF-Aufbau.

API-Oberfläche

Diese Seite beschreibt kein Connect-Tool. Sie beschreibt stattdessen die querschnittliche Instrumentierung. Zur Tool-Oberfläche siehe /connect/tool-catalog/; zu den Transporten siehe /transports/mcp/, /transports/rest/ und /transports/grpc/.

Codebeispiel – Schnellstart

Erstellen und registrieren Sie global einen Tracer Provider, bevor ein PDF generiert wird; anschließend generieren Sie wie gewohnt. Die interne Instrumentierung von NextPDF gibt Spans und Metriken automatisch aus, ohne zusätzlichen Code pro Aufruf. Führen Sie beim Prozess-Shutdown einen Flush des Providers aus, damit gepufferte Spans nicht verloren gehen. Die konkrete Verdrahtung von Provider und Exporter liegt bei der Host-Anwendung; das OpenTelemetry-PHP-Projekt dokumentiert sie, diese Seite gibt sie nicht wörtlich wieder.

Codebeispiel – Produktion

Für den Export zu einem Collector über HTTP stellt der Host einen PSR-18-HTTP-Client bereit. Behandeln Sie einen Transportfehler und einen nicht erfolgreichen HTTP-Status als zwei getrennte Fälle. Ein PSR-18-Client wirft nur dann eine typisierte Client-Exception, wenn er die Anfrage überhaupt nicht senden kann (PSR-18 §4). Eine 4xx/5xx-Antwort hingegen gibt er normal an den Aufrufer zurück; sie ist keine Exception (PSR-18 §4). Der Collector-Exportpfad und der Connect-Tool-Transport sind voneinander unabhängig; deshalb darf ein fehlschlagender Collector-Export niemals dazu führen, dass die PDF-Generierung selbst scheitert.

Edge Cases & Fallstricke

Provider erst nach der ersten Generierung registriert. Jeder vor der Registrierung erzeugte Span verwendet einen No-op-Tracer und erreicht das Backend nie. Registrieren Sie den Provider während des Anwendungsstarts.
Kein Shutdown-Flush. Ein Batch-Prozessor puffert Spans; diese gehen verloren, wenn der Prozess ohne Provider-Shutdown beendet wird. Binden Sie den Shutdown in den Worker oder den Kernel-Terminate-Hook ein.
gRPC-Export benötigt die gRPC-PHP-Erweiterung. HTTP-Export benötigt keine Erweiterung; wählen Sie daher HTTP, wenn die Erweiterung nicht verfügbar ist.
W3C-Trace-Context-Fortpflanzung. Wenn die eingehende Anfrage traceparent/tracestate enthält, pflanzt das SDK diesen Kontext automatisch in die Spans von NextPDF fort; der Connect-Aufruf reiht sich in den Trace des Aufrufers ein.

Performance

Der Instrumentierungs-Overhead ist im Verhältnis zur PDF-Generierungszeit gering. Das Budget im Front Matter ist eine Dokumentationsobergrenze, keine Garantie. Nutzen Sie bei hohen Anfrageraten Head-based- oder Collector-seitiges Sampling, um Exportvolumen und Kosten zu begrenzen.

Sicherheitshinweise

Sichere Telemetrie & Log-Scrubbing

NextPDF erzwingt eine strikte, nicht umgehbare Telemetrie-Datenrichtlinie. Eine feste Attribut-Allowlist exportiert ausschließlich strukturelle Metadaten und Performancemetriken: Seiten-, Font- und Bildzahlen, Dateigrößen, Namen von Ausgabeprofilen, boolesche Flags, Dauern, Speicher sowie Versions- und Tier-Bezeichner. Dokumentinhalte, Dateipfade, rohe Stream-Bytes, Base64-Payloads, personenbezogene Daten und Anmeldedaten werden niemals exportiert. Jedes Attribut außerhalb der Allowlist wird verworfen; dasselbe gilt für jeden Wert, der einem Payload-Muster entspricht, selbst wenn der Schlüssel selbst erlaubt ist. Diese Eigenschaft lässt Traces in eine gemeinsame Observability-Pipeline fließen, ohne dass Dokumentdaten nach außen gelangen. Es handelt sich um ein Verhalten der Bibliothek, nicht um eine deploymentweite Garantie für das Backend, das die Traces empfängt.

Konformität

Aussage	Klausel	reference_id
Ein Transportfehler ist der einzige Fall einer PSR-18-Client-Exception	PSR-18 §4
Eine 4xx/5xx-Antwort ist eine normale Rückgabe, keine Exception	PSR-18 §4

Das OpenTelemetry-Protokoll und das W3C-Trace-Context-Format sind externe Spezifikationen, die jeweils von ihrem zuständigen Gremium gepflegt werden. Diese Seite behauptet keine Konformität mit ihnen und gibt ihren Text nicht wieder. Maßgeblich sind die Definitionen in der veröffentlichten OpenTelemetry-Spezifikation (https://opentelemetry.io/docs/specs/otel/) und in der W3C Trace Context Recommendation (https://www.w3.org/TR/trace-context/).

Kommerzieller Kontext

Nicht zutreffend – die Instrumentierung ist eine Kernfunktion und nicht eingeschränkt.

Connect-Besonderheiten

Transportverfügbarkeit (MCP / REST / gRPC)

Die Instrumentierung ist transportunabhängig. Ein Connect-Aufruf über einen beliebigen Transport erzeugt dieselben Build-Lebenszyklus-Spans; wenn der Host die Transportschicht instrumentiert, ergänzt der Transport seinen eigenen umgebenden Span.

HITL-Risikostufe

Observability steht orthogonal zum Risikomodell. Das Ausgeben von Telemetrie ändert die Risikostufe eines Tools nicht und wird niemals durch ConfirmationGate eingeschränkt.

JSON-Envelope der Confirmation Gate

Nicht zutreffend – die Telemetrie-Ausgabe ist kein Tool-Aufruf und passiert daher nicht das Gate.

Siehe auch

/connect/tool-catalog/ – die beobachtbare Tool-Oberfläche.
/transports/mcp/ / /transports/rest/ / /transports/grpc/ – die Transporte, über die ein Connect-Aufruf mit Trace-Kontext eintreffen kann.