以 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 呼叫可能抵達的傳輸層。