Observer NextPDF Connect avec OpenTelemetry

En bref

NextPDF intègre une instrumentation OpenTelemetry qui émet des spans de trace et des métriques tout au long du cycle de vie de génération du PDF. Lorsqu’aucun SDK OpenTelemetry n’est présent sur le class path, l’instrumentation reste inactive : il n’y a aucune pénalité de performance, aucun échec d’autoload et rien à configurer. Cette page conceptuelle est indépendante du transport : la même instrumentation s’applique, quelle que soit la manière dont un PDF est généré — via un appel in-process, un tools/call MCP, une requête REST ou un appel gRPC vers NextPDF Connect.

Considère cette page comme une explication, pas comme une recette exécutable. C’est l’application hôte qui fournit le SDK OpenTelemetry et un exporteur, pas NextPDF ; il n’y a donc pas d’exemple autonome ici auquel cette page pourrait rattacher un hash reproductible.

Installation

C’est l’application hôte qui choisit et installe le SDK OpenTelemetry ainsi qu’un exporteur. NextPDF lit un tracer provider enregistré globalement et n’embarque aucun SDK propre. Avant de te fier aux traces, confirme que NextPDF voit bien le SDK en exécutant la sonde de disponibilité fournie. La sonde renvoie true uniquement lorsque l’API OpenTelemetry est présente sur le class path.

Vue d’ensemble conceptuelle

NextPDF émet des spans pour le cycle de vie de construction du document, ainsi qu’un petit ensemble de compteurs et d’histogrammes. Les spans couvrent un span de construction racine, la résolution des polices, l’analyse HTML, la mise en page, le décodage des images, la sérialisation, ainsi que les phases optionnelles de code-barres, de formulaire, de navigation et de pièce jointe. Les métriques couvrent la durée de rendu, le nombre de pages, les avertissements, le pic de mémoire, la taille de sortie, le nombre de polices et le nombre d’images. L’inventaire exact des spans et des métriques dépend de la version de NextPDF installée ; considère donc tout nombre figé dans une prose plus ancienne comme dépendant de la version : confirme-le sur la build en cours d’exécution plutôt que de mémoriser un nombre.

Lorsque NextPDF Connect s’exécute derrière un framework web, un appel Connect apparaît comme un enfant de la trace de la requête entrante. Une seule trace distribuée couvre alors l’entrée HTTP, l’application et la construction du PDF.

Surface d’API

Cette page ne décrit aucun outil Connect en particulier. Elle présente plutôt une instrumentation transversale. Pour la surface des outils, voir /connect/tool-catalog/ ; pour les transports, voir /transports/mcp/, /transports/rest/ et /transports/grpc/.

Exemple de code — Démarrage rapide

Construis et enregistre un tracer provider global avant toute génération de PDF, puis génère normalement. L’instrumentation interne de NextPDF émet automatiquement les spans et les métriques, sans code spécifique par appel. Vide le provider lors de l’arrêt du processus afin que les spans mis en mémoire tampon ne soient pas perdus. Le câblage concret du provider et de l’exporteur relève du choix de l’application hôte ; la documentation du projet OpenTelemetry PHP le décrit, et cette page ne le reproduit pas mot pour mot.

Exemple de code — Production

Pour un collecteur qui exporte en HTTP, l’hôte fournit un client HTTP PSR-18. Traite un échec de transport et un statut HTTP non réussi comme deux cas distincts. Un client PSR-18 lève une exception client typée uniquement lorsqu’il ne peut pas envoyer la requête du tout (PSR-18 §4). Une réponse 4xx/5xx, en revanche, est renvoyée normalement à l’appelant et ne constitue pas une exception (PSR-18 §4). Le chemin d’export du collecteur et le transport de l’outil Connect sont indépendants : un échec d’export vers le collecteur ne doit donc jamais être autorisé à faire échouer la génération du PDF elle-même.

Cas limites & pièges

Provider enregistré après la première génération. Tout span créé avant l’enregistrement utilise un tracer no-op et n’atteint jamais le backend. Enregistre le provider au démarrage de l’application.
Pas de flush à l’arrêt. Un processeur par lots met les spans en mémoire tampon, et ces spans sont perdus si le processus se termine sans arrêt du provider. Câble l’arrêt dans le worker ou dans le hook terminate du kernel.
L’export gRPC nécessite l’extension PHP gRPC. L’export HTTP ne nécessite aucune extension : choisis donc HTTP lorsque l’extension n’est pas disponible.
Propagation du W3C Trace Context. Lorsque la requête entrante porte traceparent/tracestate, le SDK propage automatiquement ce contexte dans les spans de NextPDF, et l’appel Connect rejoint la trace de l’appelant.

Performance

Le surcoût de l’instrumentation est faible par rapport au temps de génération du PDF. Le budget du front-matter est un plafond documentaire plutôt qu’une garantie. À des débits de requêtes élevés, utilise un échantillonnage en tête (head-based) ou côté collecteur pour plafonner le volume et le coût de l’exporteur.

Notes de sécurité

Télémétrie sûre & nettoyage des journaux

NextPDF applique une politique stricte et non contournable sur les données de télémétrie. Une liste d’autorisation d’attributs figée n’exporte que des métadonnées structurelles et des métriques de performance : nombres de pages, de polices et d’images, tailles de fichiers, noms de profils de sortie, indicateurs booléens, durées, mémoire, ainsi que les identifiants de version et de palier. Le contenu des documents, les chemins de fichiers, les octets bruts des flux, les charges utiles base64, les données personnelles et les identifiants de connexion ne sont jamais exportés. Tout attribut en dehors de la liste d’autorisation est supprimé, de même que toute valeur correspondant à un motif de charge utile, même lorsque la clé elle-même est autorisée. C’est cette propriété qui permet aux traces de circuler dans un pipeline d’observabilité partagé sans fuite de données de document. Il s’agit d’un comportement de la bibliothèque, et non d’une garantie de déploiement concernant le backend qui reçoit les traces.

Conformité

Affirmation	Clause	reference_id
L’échec de transport est le seul cas d’exception client PSR-18	PSR-18 §4
Une réponse 4xx/5xx est un retour normal, pas une exception	PSR-18 §4

Le protocole OpenTelemetry et le format W3C Trace Context sont des spécifications externes, chacune maintenue par l’organisme correspondant. Cette page n’affirme pas de conformité à celles-ci et ne reproduit pas leur texte. Les définitions faisant autorité se trouvent dans la spécification OpenTelemetry publiée (https://opentelemetry.io/docs/specs/otel/) et dans la Recommandation W3C Trace Context (https://www.w3.org/TR/trace-context/).

Contexte commercial

Sans objet — l’instrumentation est une capacité du cœur et elle n’est pas restreinte.

Spécificités de Connect

Disponibilité des transports (MCP / REST / gRPC)

L’instrumentation est indépendante du transport. Un appel Connect sur n’importe quel transport produit les mêmes spans de cycle de vie de construction, et le transport ajoute son propre span englobant lorsque l’hôte instrumente la couche de transport.

Palier de risque HITL

L’observabilité est orthogonale au modèle de risque. Émettre de la télémétrie ne change pas le niveau de risque d’un outil, et cela n’est jamais soumis au ConfirmationGate.

Enveloppe JSON de la barrière de confirmation

Sans objet — l’émission de télémétrie n’est pas une invocation d’outil ; elle ne passe donc pas par la barrière.

Voir aussi

/connect/tool-catalog/ — la surface des outils observés.
/transports/mcp/ / /transports/rest/ / /transports/grpc/ — les transports par lesquels un appel Connect tracé peut arriver.