Observe NextPDF Connect with OpenTelemetry

Observe NextPDF Connect with OpenTelemetry

At a glance

NextPDF includes built-in OpenTelemetry instrumentation that emits trace spans and metrics across the Portable Document Format (PDF) generation lifecycle. When no OpenTelemetry Software Development Kit (SDK) is on the class path, the instrumentation stays inactive: there is no performance penalty, no autoload failure, and nothing to configure. This page is transport-agnostic, so the same instrumentation applies however you generate a PDF: through an in-process call, a Model Context Protocol (MCP) tools/call, a Representational State Transfer (REST) request, or a gRPC call against NextPDF Connect.

Think of this page as an explanation, not a runnable recipe. The host application supplies the OpenTelemetry SDK and an exporter. NextPDF does not. Because there is no self-contained example, this page does not pin a reproducible hash.

Install

The host application chooses and installs the OpenTelemetry SDK and one exporter. NextPDF reads a globally registered tracer provider and does not bundle its own SDK. Before you rely on traces, run the bundled availability probe to confirm that NextPDF can see the SDK. The probe returns true only when the OpenTelemetry Application Programming Interface (API) is on the class path.

Conceptual overview

NextPDF emits spans for the document build lifecycle and a small set of counters and histograms. The spans cover a root build span, font resolution, HyperText Markup Language (HTML) parse, layout, image decode, serialization, and the optional barcode, form, navigation, and attachment phases. The metrics cover render duration, page count, warnings, peak memory, output size, font count, and image count. The exact span and metric inventory depends on the installed NextPDF version, so treat any fixed count in older prose as version-dependent. Confirm it against the running build instead of memorizing a number.

When NextPDF Connect runs behind a web framework, a Connect call appears as a child of the incoming Hypertext Transfer Protocol (HTTP) request trace. A single distributed trace then spans the HTTP entry, the application, and the PDF build.

API surface

This page does not assert a Connect tool. It describes cross-cutting instrumentation instead. For the tool surface, see /connect/tool-catalog/. For transports, see /transports/mcp/, /transports/rest/, and /transports/grpc/.

Code sample — Quick start

Build and register a tracer provider globally before you generate any PDF, then generate as usual. NextPDF’s internal instrumentation emits the spans and metrics automatically, with no per-call code. Flush the provider on process shutdown so buffered spans are not lost. The host application owns the concrete provider and exporter wiring. The OpenTelemetry PHP project documents that wiring, and this page does not restate it verbatim.

Code sample — Production

For an HTTP-exporting collector, the host supplies a PSR-18 HTTP client. Treat a transport failure and a non-success HTTP status as separate cases. A PSR-18 client raises a typed client exception only when it cannot send the request at all (PSR-18 §4). A 4xx/5xx response, by contrast, returns to the caller normally and is not an exception (PSR-18 §4). The collector export path and the Connect tool transport are independent, so a failed collector export must never fail the PDF generation itself.

Edge cases & gotchas

• Provider registered after the first generation. Any span created before registration uses a no-op tracer and never reaches the backend. Register the provider during application boot.
• No shutdown flush. A batch processor buffers spans, and those spans are lost if the process exits without a provider shutdown. Wire provider shutdown into the worker or the kernel terminate hook.
• gRPC export needs the gRPC PHP extension. HTTP export needs no extension, so choose HTTP when the extension is unavailable.
• W3C Trace Context propagation. When the incoming request carries traceparent/tracestate, the SDK automatically propagates that context into NextPDF’s spans, and the Connect call joins the caller’s trace.

Performance

The instrumentation overhead is small compared with PDF generation time. The front-matter budget is a documentation cap, not a guarantee. At high request rates, use head-based or collector-side sampling to bound exporter volume and cost.

Security notes

Safe Telemetry & Log Scrubbing

NextPDF enforces a strict, non-bypassable telemetry data policy. A fixed attribute allowlist exports only structural metadata and performance metrics: page, font, and image counts, file sizes, output profile names, boolean flags, durations, memory, and version and tier identifiers. NextPDF never exports document content, file paths, raw stream bytes, base64 payloads, personal data, or credentials. It drops any attribute outside the allowlist. It also drops any value that matches a payload pattern, even when the key itself is allowed. This behavior lets traces flow into a shared observability pipeline without leaking document data. It is a library behavior, not a deployment-level guarantee about the backend that receives the traces.

Conformance

Claim	Clause	reference_id
Transport failure is the only PSR-18 client-exception case	PSR-18 §4
A 4xx/5xx response is a normal return, not an exception	PSR-18 §4

The OpenTelemetry protocol and the World Wide Web Consortium (W3C) Trace Context format are external specifications, each maintained by its respective body. This page does not assert conformance to them and does not reproduce their text. The authoritative definitions live in the published OpenTelemetry specification (https://opentelemetry.io/docs/specs/otel/) and the W3C Trace Context Recommendation (https://www.w3.org/TR/trace-context/).

Commercial context

Not applicable — instrumentation is a core capability, and it is not gated.

Connect specifics

Transport availability (MCP / REST / gRPC)

The instrumentation is transport-agnostic. A Connect call over any transport produces the same build-lifecycle spans. The transport adds its own surrounding span when the host instruments the transport layer.

HITL risk tier

Observability is separate from the risk model. Emitting telemetry does not change a tool’s risk level, and it is never gated by the ConfirmationGate.

Confirmation gate JSON envelope

Not applicable — telemetry emission is not a tool invocation, so it does not pass through the gate.

See also

• /connect/tool-catalog/ — the observed tool surface.
• /transports/mcp/ / /transports/rest/ / /transports/grpc/ — the transports that can receive a traced Connect call.