Observar NextPDF Connect con OpenTelemetry

De un vistazo

NextPDF incluye instrumentación integrada de OpenTelemetry que emite tramos de traza y métricas durante todo el ciclo de vida de la generación de PDF. Si no hay ningún SDK de OpenTelemetry en la ruta de clases, la instrumentación queda inactiva: no hay penalización de rendimiento, fallos de autocarga ni configuración necesaria. Esta página es conceptual e independiente del transporte, por lo que la misma instrumentación se aplica con independencia de cómo se genere el PDF: mediante una llamada en proceso, un tools/call de MCP, una solicitud REST o una llamada gRPC contra NextPDF Connect.

Esta página debe leerse como una explicación, no como una receta ejecutable. La aplicación anfitriona proporciona el SDK de OpenTelemetry y un exportador, no NextPDF; por eso aquí no hay ningún ejemplo autónomo al que esta página pueda asociar un hash reproducible.

Instalación

La aplicación anfitriona elige e instala el SDK de OpenTelemetry y un exportador. NextPDF lee un proveedor de trazadores registrado globalmente y no incluye un SDK propio. Antes de confiar en las trazas, conviene confirmar que NextPDF puede ver el SDK ejecutando la sonda de disponibilidad incluida. La sonda devuelve true solo cuando la API de OpenTelemetry está en la ruta de clases.

Visión conceptual general

NextPDF emite tramos que cubren el ciclo de vida de la construcción del documento, además de un pequeño conjunto de contadores e histogramas. Los tramos abarcan un tramo de construcción raíz, la resolución de fuentes, el análisis de HTML, el diseño, la decodificación de imágenes, la serialización y las fases opcionales de código de barras, formulario, navegación y adjuntos. Las métricas abarcan la duración del renderizado, el número de páginas, las advertencias, la memoria máxima, el tamaño de la salida, el número de fuentes y el número de imágenes. El inventario exacto de tramos y métricas depende de la versión instalada de NextPDF, por lo que cualquier recuento fijo de documentación anterior debe tratarse como dependiente de la versión: se debe confirmar con la compilación en ejecución en lugar de memorizar un número.

Cuando NextPDF Connect se ejecuta detrás de un framework web, una llamada de Connect aparece como hija de la traza de la solicitud entrante. Una única traza distribuida cubre entonces la entrada HTTP, la aplicación y la construcción del PDF.

Superficie de la API

Esta página no declara ninguna herramienta de Connect. Describe, en cambio, instrumentación transversal. Para la superficie de herramientas, véase /connect/tool-catalog/; para los transportes, véanse /transports/mcp/, /transports/rest/ y /transports/grpc/.

Ejemplo de código — Inicio rápido

Se debe construir y registrar un proveedor de trazadores global antes de generar cualquier PDF y, después, generar con normalidad. La instrumentación interna de NextPDF emite los tramos y las métricas automáticamente, sin añadir código en cada llamada. Se debe vaciar el proveedor al apagar el proceso para que no se pierdan los tramos almacenados en el búfer. La configuración concreta del proveedor y del exportador queda a criterio de la aplicación anfitriona; el proyecto OpenTelemetry PHP la documenta, y esta página no la reproduce textualmente.

Ejemplo de código — Producción

Para un recolector que exporta por HTTP, el anfitrión proporciona un cliente HTTP PSR-18. Hay que tratar un fallo de transporte y un estado HTTP no satisfactorio como dos casos distintos. Un cliente PSR-18 lanza una excepción de cliente tipada solo cuando no puede enviar la solicitud en absoluto (PSR-18 §4). Una respuesta 4xx/5xx, en cambio, se devuelve al llamador con normalidad y no es una excepción (PSR-18 §4). La ruta de exportación hacia el recolector y el transporte de la herramienta de Connect son independientes, por lo que nunca debe permitirse que un fallo en la exportación del recolector haga fallar la propia generación del PDF.

Casos límite y trampas

Proveedor registrado después de la primera generación. Cualquier tramo creado antes del registro usa un trazador inoperante y nunca llega al backend. El proveedor debe registrarse durante el arranque de la aplicación.
Sin vaciado al apagar. Un procesador por lotes almacena los tramos en un búfer, y esos tramos se pierden si el proceso termina sin apagar el proveedor. El apagado debe vincularse al worker o al hook terminate del kernel.
La exportación por gRPC necesita la extensión PHP de gRPC. La exportación por HTTP no necesita ninguna extensión, por lo que conviene elegir HTTP cuando la extensión no esté disponible.
Propagación del W3C Trace Context. Cuando la solicitud entrante incluye traceparent/tracestate, el SDK propaga ese contexto a los tramos de NextPDF automáticamente, y la llamada de Connect se une a la traza del llamador.

Rendimiento

La sobrecarga de la instrumentación es pequeña en relación con el tiempo de generación del PDF. El presupuesto del front-matter es un límite de documentación, no una garantía. Con tasas de solicitudes altas, se debe usar muestreo basado en la cabecera o en el lado del recolector para acotar el volumen y el coste del exportador.

Notas de seguridad

Telemetría segura y depuración de registros

NextPDF impone una política de datos de telemetría estricta e ineludible. Una lista fija de atributos permitidos exporta únicamente metadatos estructurales y métricas de rendimiento: el número de páginas, fuentes e imágenes, los tamaños de archivo, los nombres de perfil de salida, los indicadores booleanos, las duraciones, la memoria y los identificadores de versión y de nivel. El contenido de los documentos, las rutas de archivo, los bytes de flujo sin procesar, las cargas útiles en base64, los datos personales y las credenciales nunca se exportan. Cualquier atributo fuera de la lista de atributos permitidos se descarta, igual que cualquier valor que coincida con un patrón de carga útil, incluso cuando la propia clave está permitida. Esta propiedad permite que las trazas fluyan hacia un canal de observabilidad compartido sin que se filtren datos de los documentos. Es un comportamiento de la biblioteca, no una garantía de despliegue sobre el backend que recibe las trazas.

Conformidad

Afirmación	Cláusula	reference_id
El fallo de transporte es el único caso de excepción de cliente de PSR-18	PSR-18 §4
Una respuesta 4xx/5xx es un retorno normal, no una excepción	PSR-18 §4

El protocolo de OpenTelemetry y el formato W3C Trace Context son especificaciones externas, cada una mantenida por su organismo correspondiente. Esta página no declara conformidad con ellas ni reproduce su texto. Las definiciones autoritativas residen en la especificación publicada de OpenTelemetry (https://opentelemetry.io/docs/specs/otel/) y en la Recomendación W3C Trace Context (https://www.w3.org/TR/trace-context/).

Contexto comercial

No aplicable: la instrumentación es una capacidad básica y no está restringida.

Aspectos específicos de Connect

Disponibilidad de transportes (MCP / REST / gRPC)

La instrumentación es independiente del transporte. Una llamada de Connect a través de cualquier transporte produce los mismos tramos del ciclo de vida de construcción, y el transporte añade su propio tramo envolvente cuando el anfitrión instrumenta la capa de transporte.

Nivel de riesgo HITL

La observabilidad es ortogonal al modelo de riesgo. Emitir telemetría no cambia el nivel de riesgo de una herramienta, y la emisión de telemetría nunca está sujeta a la ConfirmationGate.

JSON de la puerta de confirmación

No aplicable: la emisión de telemetría no es una invocación de herramienta, por lo que no pasa por la puerta.

Véase también

/connect/tool-catalog/ — la superficie de herramientas observada.
/transports/mcp/ / /transports/rest/ / /transports/grpc/ — los transportes a través de los cuales puede llegar una llamada de Connect con traza.