Quan sát NextPDF Connect bằng OpenTelemetry

Tổng quan nhanh

NextPDF có sẵn công cụ đo lường OpenTelemetry tích hợp, phát ra trace span và metric trong suốt vòng đời tạo Portable Document Format (PDF). Khi không có Software Development Kit (SDK) OpenTelemetry nào trên class path, công cụ đo lường này ở trạng thái không hoạt động: không phát sinh chi phí hiệu năng, không gây lỗi autoload, và không cần cấu hình. Trang này không phụ thuộc vào transport, nên cùng một công cụ đo lường áp dụng cho mọi cách tạo PDF: thông qua một lệnh gọi in-process, một tools/call của Model Context Protocol (MCP), một yêu cầu Representational State Transfer (REST), hoặc một lệnh gọi gRPC đến NextPDF Connect.

Hãy xem trang này là phần giải thích, không phải công thức có thể chạy trực tiếp. Ứng dụng máy chủ cung cấp OpenTelemetry SDK và một exporter; NextPDF không cung cấp các thành phần đó. Vì không có ví dụ khép kín, trang này không ghim hash có thể tái lập.

Cài đặt

Ứng dụng máy chủ chọn và cài đặt OpenTelemetry SDK cùng một exporter. NextPDF đọc tracer provider đã đăng ký toàn cục và không đóng gói SDK riêng. Trước khi dựa vào trace, hãy chạy probe kiểm tra tính khả dụng đi kèm để xác nhận rằng NextPDF có thể thấy SDK. Probe chỉ trả về true khi Application Programming Interface (API) của OpenTelemetry có trên class path.

Tổng quan khái niệm

NextPDF phát ra span cho vòng đời dựng tài liệu và một tập nhỏ các counter và histogram. Các span bao gồm span dựng gốc, phân giải phông chữ, phân tích cú pháp HyperText Markup Language (HTML), bố cục, giải mã hình ảnh, tuần tự hóa, cùng các giai đoạn tùy chọn như barcode, biểu mẫu, điều hướng và tệp đính kèm. Các metric bao gồm thời lượng kết xuất, số trang, cảnh báo, bộ nhớ đỉnh, kích thước đầu ra, số phông chữ và số hình ảnh. Danh mục span và metric chính xác phụ thuộc vào phiên bản NextPDF đã cài đặt, nên hãy coi mọi con số cố định trong tài liệu cũ là phụ thuộc phiên bản. Hãy xác nhận trên bản dựng đang chạy thay vì ghi nhớ một con số.

Khi NextPDF Connect chạy phía sau một web framework, span của lệnh gọi Connect xuất hiện như span con trong trace của yêu cầu Hypertext Transfer Protocol (HTTP) đến. Khi đó, một trace phân tán duy nhất trải dài qua điểm vào HTTP, ứng dụng và bản dựng PDF.

Bề mặt API

Trang này không nêu một công cụ Connect cụ thể. Thay vào đó, trang mô tả công cụ đo lường xuyên suốt. Về bề mặt công cụ, xem /connect/tool-catalog/. Về transport, xem /transports/mcp/, /transports/rest/, và /transports/grpc/.

Mẫu mã — bắt đầu nhanh

Hãy thiết lập và đăng ký một tracer provider ở phạm vi toàn cục trước khi bạn tạo bất kỳ PDF nào, sau đó tạo PDF như bình thường. Công cụ đo lường nội bộ của NextPDF tự động phát ra các span và metric, không cần thêm mã cho từng lệnh gọi. Hãy xả provider khi tiến trình tắt để các span được đệm không bị mất. Ứng dụng máy chủ sở hữu việc đấu nối provider và exporter cụ thể. Dự án OpenTelemetry PHP có tài liệu về cách đấu nối đó, và trang này không nhắc lại nguyên văn.

Mẫu mã — Production

Với collector xuất qua HTTP, máy chủ cung cấp một HTTP client PSR-18. Hãy xem lỗi transport và trạng thái HTTP không thành công là hai trường hợp riêng biệt. Một client PSR-18 chỉ ném typed client exception khi hoàn toàn không thể gửi yêu cầu (PSR-18 §4). Ngược lại, phản hồi 4xx/5xx được trả về cho bên gọi như bình thường và không phải là exception (PSR-18 §4). Đường xuất của collector độc lập với transport của công cụ Connect, nên một lần xuất collector thất bại không bao giờ được khiến chính việc tạo PDF thất bại.

Trường hợp biên & điểm cần lưu ý

Provider được đăng ký sau lần tạo đầu tiên. Bất kỳ span nào được tạo trước khi đăng ký đều dùng tracer no-op và không bao giờ đến được backend. Hãy đăng ký provider trong quá trình khởi động ứng dụng.
Không xả khi tắt. Batch processor đệm các span, và các span đó sẽ mất nếu tiến trình thoát mà không tắt provider. Hãy đấu nối việc tắt provider vào worker hoặc hook terminate của kernel.
Xuất qua gRPC cần extension PHP gRPC. Xuất qua HTTP không cần extension nào, nên hãy chọn HTTP khi extension không khả dụng.
Lan truyền W3C Trace Context. Khi yêu cầu đến mang theo traceparent/tracestate, SDK tự động lan truyền context đó vào các span của NextPDF, và lệnh gọi Connect tham gia vào trace của bên gọi.

Hiệu năng

Chi phí của công cụ đo lường là nhỏ so với thời gian tạo PDF. Ngân sách trong front-matter là giới hạn tài liệu, không phải bảo đảm. Với tốc độ yêu cầu cao, hãy dùng head-based sampling hoặc sampling phía collector để giới hạn khối lượng và chi phí của exporter.

Ghi chú bảo mật

Telemetry an toàn & làm sạch log

NextPDF thực thi một chính sách dữ liệu telemetry nghiêm ngặt, không thể bỏ qua. Một allowlist thuộc tính cố định chỉ xuất metadata có cấu trúc và metric hiệu năng: số trang, số phông chữ và số hình ảnh, kích thước tệp, tên output profile, cờ boolean, thời lượng, bộ nhớ, cùng định danh phiên bản và bậc. NextPDF không bao giờ xuất nội dung tài liệu, đường dẫn tệp, byte luồng thô, payload base64, dữ liệu cá nhân, hay thông tin đăng nhập. Nó loại bỏ mọi thuộc tính nằm ngoài allowlist. Nó cũng loại bỏ mọi giá trị khớp với một mẫu payload, ngay cả khi chính khóa đó được cho phép. Hành vi này cho phép trace đi vào pipeline quan sát dùng chung mà không rò rỉ dữ liệu tài liệu. Đây là hành vi ở cấp thư viện, không phải bảo đảm ở cấp triển khai về backend nhận các trace.

Tuân thủ

Tuyên bố	Điều khoản	reference_id
Lỗi transport là trường hợp client-exception PSR-18 duy nhất	PSR-18 §4
Một phản hồi 4xx/5xx là một giá trị trả về bình thường, không phải một exception	PSR-18 §4

Giao thức OpenTelemetry và định dạng Trace Context của World Wide Web Consortium (W3C) là các đặc tả bên ngoài, do tổ chức tương ứng duy trì. Trang này không khẳng định mức độ tuân thủ các đặc tả đó và không tái tạo văn bản của chúng. Các định nghĩa có thẩm quyền nằm trong đặc tả OpenTelemetry đã xuất bản (https://opentelemetry.io/docs/specs/otel/) và Khuyến nghị W3C Trace Context (https://www.w3.org/TR/trace-context/).

Bối cảnh thương mại

Không áp dụng — công cụ đo lường là khả năng cốt lõi và không bị giới hạn.

Chi tiết riêng của Connect

Tính khả dụng của transport (MCP / REST / gRPC)

Công cụ đo lường không phụ thuộc vào transport. Một lệnh gọi Connect qua bất kỳ transport nào đều tạo ra cùng các span của vòng đời dựng. Transport thêm span bao quanh riêng khi máy chủ đo lường lớp transport.

Bậc rủi ro HITL

Khả năng quan sát tách biệt với mô hình rủi ro. Việc phát ra telemetry không thay đổi mức rủi ro của một công cụ, và không bao giờ bị ConfirmationGate giới hạn.

JSON envelope của confirmation gate

Không áp dụng — việc phát ra telemetry không phải là một lệnh gọi công cụ, nên nó không đi qua gate.

Xem thêm

/connect/tool-catalog/ — bề mặt công cụ được quan sát.
/transports/mcp/ / /transports/rest/ / /transports/grpc/ — các transport có thể tiếp nhận lệnh gọi Connect được trace.