Monitore o NextPDF Connect com o OpenTelemetry

Visão geral

O NextPDF inclui instrumentação OpenTelemetry integrada que emite spans de trace e métricas ao longo de todo o ciclo de vida da geração de Portable Document Format (PDF). Quando nenhum Software Development Kit (SDK) do OpenTelemetry está no class path, a instrumentação permanece inativa: não há penalidade de desempenho, não há falha de autoload e não há nada a configurar. Esta página é independente do transporte, portanto a mesma instrumentação se aplica independentemente de como você gere um PDF: por meio de uma chamada in-process, de um tools/call do Model Context Protocol (MCP), de uma requisição Representational State Transfer (REST) ou de uma chamada gRPC ao NextPDF Connect.

Encare esta página como uma explicação, não como uma receita executável. A aplicação host fornece o SDK do OpenTelemetry e um exportador. O NextPDF não fornece nenhum dos dois. Como não há um exemplo autocontido, esta página não fixa um hash reproduzível.

Instalação

A aplicação host escolhe e instala o SDK do OpenTelemetry e um exportador. O NextPDF lê um tracer provider registrado globalmente e não inclui um SDK próprio. Antes de confiar nos traces, execute a sonda de disponibilidade integrada para confirmar que o NextPDF consegue ver o SDK. A sonda retorna true somente quando a Application Programming Interface (API) do OpenTelemetry está no class path.

Visão conceitual

O NextPDF emite spans para o ciclo de vida de construção do documento e um pequeno conjunto de contadores e histogramas. Os spans cobrem um span raiz de construção, resolução de fontes, parse de HyperText Markup Language (HTML), layout, decodificação de imagens, serialização e as fases opcionais de código de barras, formulário, navegação e anexos. As métricas cobrem duração da renderização, contagem de páginas, avisos, pico de memória, tamanho da saída, contagem de fontes e contagem de imagens. O inventário exato de spans e métricas depende da versão do NextPDF instalada, portanto trate qualquer contagem fixa em textos mais antigos como dependente da versão. Confirme isso em relação ao build em execução, em vez de memorizar um número.

Quando o NextPDF Connect roda atrás de um framework web, uma chamada do Connect aparece como filha do trace da requisição Hypertext Transfer Protocol (HTTP) recebida. Assim, um único trace distribuído abrange a entrada HTTP, a aplicação e o build do PDF.

Superfície da API

Esta página não declara uma ferramenta do Connect. Em vez disso, descreve uma instrumentação transversal. Para a superfície de ferramentas, consulte /connect/tool-catalog/. Para os transportes, consulte /transports/mcp/, /transports/rest/ e /transports/grpc/.

Exemplo de código — Início rápido

Construa e registre um tracer provider globalmente antes de gerar qualquer PDF e, em seguida, gere normalmente. A instrumentação interna do NextPDF emite os spans e as métricas automaticamente, sem código em cada chamada. Faça o flush do provider no encerramento do processo para que os spans em buffer não sejam perdidos. A aplicação host é responsável pela configuração concreta do provider e do exportador. O projeto OpenTelemetry PHP documenta essa configuração, e esta página não a reproduz literalmente.

Exemplo de código — Produção

Para um coletor que exporta via HTTP, o host fornece um cliente HTTP PSR-18. Trate uma falha de transporte e um status HTTP sem sucesso como casos distintos. Um cliente PSR-18 lança uma exceção de cliente tipada somente quando não consegue enviar a requisição de forma alguma (PSR-18 §4). Uma resposta 4xx/5xx, por outro lado, retorna ao chamador normalmente e não é uma exceção (PSR-18 §4). O caminho de exportação do coletor e o transporte da ferramenta do Connect são independentes, portanto uma exportação do coletor com falha nunca deve fazer a própria geração do PDF falhar.

Casos extremos e pegadinhas

Provider registrado após a primeira geração. Qualquer span criado antes do registro usa um tracer no-op e nunca chega ao backend. Registre o provider durante a inicialização da aplicação.
Sem flush no encerramento. Um processador em lote armazena spans em buffer, e esses spans são perdidos se o processo terminar sem um shutdown do provider. Associe o shutdown do provider ao worker ou ao hook terminate do kernel.
A exportação por gRPC precisa da extensão PHP gRPC. A exportação por HTTP não exige extensão, portanto escolha HTTP quando a extensão estiver indisponível.
Propagação do W3C Trace Context. Quando a requisição recebida carrega traceparent/tracestate, o SDK propaga automaticamente esse contexto para os spans do NextPDF, e a chamada do Connect entra no trace do chamador.

Desempenho

A sobrecarga da instrumentação é pequena em comparação com o tempo de geração do PDF. O orçamento do front-matter é um limite de documentação, não uma garantia. Em taxas elevadas de requisições, use amostragem head-based ou no lado do coletor para limitar o volume e o custo do exportador.

Notas de segurança

Telemetria segura e limpeza de logs

O NextPDF aplica uma política de dados de telemetria estrita e não contornável. Uma allowlist fixa de atributos exporta apenas metadados estruturais e métricas de desempenho: contagens de páginas, fontes e imagens, tamanhos de arquivo, nomes de perfis de saída, flags booleanas, durações, memória e identificadores de versão e tier. O NextPDF nunca exporta conteúdo de documento, caminhos de arquivo, bytes brutos de stream, payloads base64, dados pessoais ou credenciais. Ele descarta qualquer atributo fora da allowlist. Também descarta qualquer valor que corresponda a um padrão de payload, mesmo quando a própria chave é permitida. Esse comportamento permite que os traces fluam para um pipeline de observabilidade compartilhado sem vazar dados do documento. É um comportamento da biblioteca, não uma garantia no nível de deployment sobre o backend que recebe os traces.

Conformidade

Afirmação	Cláusula	reference_id
Falha de transporte é o único caso de exceção de cliente do PSR-18	PSR-18 §4
Uma resposta 4xx/5xx é um retorno normal, não uma exceção	PSR-18 §4

O protocolo OpenTelemetry e o formato Trace Context do World Wide Web Consortium (W3C) são especificações externas, cada uma mantida por seu respectivo órgão. Esta página não declara conformidade com elas nem reproduz seus textos. As definições autoritativas estão na especificação OpenTelemetry publicada (https://opentelemetry.io/docs/specs/otel/) e na Recomendação W3C Trace Context (https://www.w3.org/TR/trace-context/).

Contexto comercial

Não se aplica — a instrumentação é um recurso do core e não é restrita.

Especificidades do Connect

Disponibilidade de transporte (MCP / REST / gRPC)

A instrumentação é independente do transporte. Uma chamada do Connect sobre qualquer transporte produz os mesmos spans do ciclo de vida do build. O transporte adiciona seu próprio span envolvente quando o host instrumenta a camada de transporte.

Nível de risco HITL

A observabilidade é separada do modelo de risco. Emitir telemetria não altera o nível de risco de uma ferramenta e nunca fica restrita pelo ConfirmationGate.

Envelope JSON do confirmation gate

Não se aplica — a emissão de telemetria não é uma invocação de ferramenta, portanto não passa pelo gate.

Veja também

/connect/tool-catalog/ — a superfície de ferramentas observada.
/transports/mcp/ / /transports/rest/ / /transports/grpc/ — os transportes que podem receber uma chamada do Connect com trace.