使用 OpenTelemetry 观测 NextPDF Connect

概览

NextPDF 内置 OpenTelemetry 插桩，会在整个 PDF 生成生命周期中发出追踪 span 与指标。当 class path 上没有任何 OpenTelemetry SDK 时，插桩会保持静默：不会产生性能开销，不会发生 autoload 失败，也不需要配置任何项目。这是一篇与传输层无关的概念说明，因此无论 PDF 通过哪种方式生成——进程内调用、MCP tools/call、REST 请求，或发往 NextPDF Connect 的 gRPC 调用——都会应用同一套插桩。

请将本页视为说明文档，而不是可直接运行的示例。OpenTelemetry SDK 与导出器由主机应用程序提供，而非由 NextPDF 提供，因此本页没有可用于锁定可复现哈希值的自包含示例。

安装

由主机应用程序选择并安装 OpenTelemetry SDK 与一个导出器。NextPDF 会读取全局注册的 tracer provider，自身不捆绑 SDK。在你依赖追踪之前，请先运行内置的可用性探针，确认 NextPDF 能发现该 SDK。只有当 OpenTelemetry API 位于 class path 上时，探针才会返回 true。

概念总览

NextPDF 会为文档构建生命周期发出 span，并提供一小组计数器与直方图。这些 span 涵盖一个根构建 span，以及字体解析、HTML 解析、布局、图像解码、序列化，和可选的条码、表单、导航与附件等阶段。这些指标涵盖渲染时长、页数、警告数、峰值内存、输出大小、字体数量与图像数量。span 与指标的确切清单取决于所安装的 NextPDF 版本，因此请将旧文档中的任何固定数量视为随版本而定：请对照正在运行的构建加以确认，而不是死记这些数字。

当 NextPDF Connect 在 Web 框架后方运行时，一次 Connect 调用会作为传入请求追踪的子项呈现。这样，单个分布式追踪就会横跨 HTTP 入口点、应用程序与 PDF 构建。

API 接口

本页并不声明任何 Connect 工具。它描述的是横切式插桩。关于工具接口，请参见 /connect/tool-catalog/；关于传输层，请参见 /transports/mcp/、/transports/rest/ 与 /transports/grpc/.

代码示例——快速上手

在生成任何 PDF 之前，先全局创建并注册一个 tracer provider，然后照常生成 PDF。NextPDF 的内部插桩会自动发出 span 与指标，不需要逐次调用代码。在进程关闭时清空 provider，以免缓冲区中的 span 丢失。具体的 provider 与导出器连接方式由主机应用程序决定；OpenTelemetry PHP 项目已提供相关文档，本页不逐字重述。

代码示例——正式环境

对于通过 HTTP 导出的收集器，主机会提供一个 PSR-18 HTTP 客户端。请将传输失败与非成功 HTTP 状态视为两种不同情况。只有在完全无法发送请求时，PSR-18 客户端才会抛出带类型的客户端异常（PSR-18 §4）。相反，4xx/5xx 响应会正常返回给调用方，并非异常（PSR-18 §4）。收集器导出路径与 Connect 工具传输彼此独立，因此绝不可让导出至收集器失败导致 PDF 生成本身失败。

边界情况与陷阱

**在首次生成之后才注册 provider。**注册之前创建的任何 span 都会使用 no-op tracer，永远不会到达后端。请在应用程序启动期间注册 provider。
**关闭时未清空。**批处理器会缓冲 span；如果进程在未关闭 provider 的情况下结束，这些 span 就会丢失。请将关闭动作接入 worker 或 kernel 的 terminate 钩子。
**gRPC 导出需要 gRPC PHP 扩展。**HTTP 导出不需要任何扩展，因此在扩展不可用时请选择 HTTP。
**W3C Trace Context 传播。**当传入请求带有 traceparent/tracestate 时，SDK 会自动将该上下文传播到 NextPDF 的 span 中，且该 Connect 调用会并入调用方的追踪。

性能

相对于 PDF 生成时间，插桩带来的额外开销很小。front-matter 中的预算是文档级别的上限，而非保证值。在高请求速率下，请使用头部采样或收集器端采样，以限制导出器的数据量与成本。

安全注意事项

安全遥测与日志脱敏

NextPDF 会强制执行一套严格且无法绕过的遥测数据策略。固定的属性允许列表只会导出结构化元数据与性能指标：页数、字体数与图像数、文件大小、输出配置文件名称、布尔标志、时长、内存，以及版本与层级标识符。文件内容、文件路径、原始流字节、base64 载荷、个人数据与凭据一律不会导出。任何不在允许列表内的属性都会被丢弃；任何符合载荷模式的值同样会被丢弃，即使其键本身属于允许范围也是如此。正是这项特性让追踪能够流入共享的可观测性管线，而不会泄漏文件数据。这是库自身的行为，并不是对接收追踪的后端在部署层面作出的保证。

符合性

主张	条款	reference_id
传输失败是唯一的 PSR-18 客户端异常情况	PSR-18 §4
4xx/5xx 响应是正常返回，而非异常	PSR-18 §4

OpenTelemetry 通信协议与 W3C Trace Context 格式都是外部规范，分别由相应组织维护。本页并不主张符合这些规范，也不复述其文字内容。权威定义见已发布的 OpenTelemetry 规范（https://opentelemetry.io/docs/specs/otel/）与 W3C Trace Context 建议（https://www.w3.org/TR/trace-context/）。

商业脉络

不适用——此插桩是核心功能，不受任何闸控限制。

Connect 专属细节

传输可用性（MCP / REST / gRPC）

此插桩与传输层无关。通过任何传输层发出的 Connect 调用都会生成相同的构建生命周期 span；当主机对传输层进行插桩时，该传输层还会加上自身的外围 span。

HITL 风险层级

可观测性与风险模型彼此正交。发出遥测不会改变工具的风险等级，也绝不会受到 ConfirmationGate 闸控。

确认闸 JSON 封套

不适用——发出遥测并不是一次工具调用，因此不会经过该闸。

另请参阅

/connect/tool-catalog/ —— 受观测的工具接口。
/transports/mcp/ / /transports/rest/ / /transports/grpc/ —— 受追踪的 Connect 调用可能到达的传输层。