สังเกตการณ์ NextPDF Connect ด้วย OpenTelemetry

ภาพรวมโดยสังเขป

NextPDF มีอินสตรูเมนเทชัน OpenTelemetry ในตัวที่ปล่อย trace span และ metric ตลอดวงจรชีวิตการสร้าง Portable Document Format (PDF) เมื่อไม่มี OpenTelemetry Software Development Kit (SDK) อยู่ใน class path อินสตรูเมนเทชันจะไม่ทำงานต่อไป: ไม่ทำให้ประสิทธิภาพลดลง ไม่มีความล้มเหลวในการ autoload และไม่มีอะไรต้องกำหนดค่า หน้านี้ไม่ขึ้นกับ transport ดังนั้นอินสตรูเมนเทชันเดียวกันจึงใช้ได้ไม่ว่าจะสร้าง PDF ด้วยวิธีใดก็ตาม: ผ่านการเรียกแบบ in-process การเรียก Model Context Protocol (MCP) tools/call คำขอ Representational State Transfer (REST) หรือการเรียก gRPC ไปยัง NextPDF Connect

ให้ถือว่าหน้านี้เป็นคำอธิบาย ไม่ใช่สูตรที่รันได้ แอปพลิเคชันโฮสต์เป็นผู้จัดเตรียม OpenTelemetry SDK และ exporter ส่วน NextPDF ไม่ได้จัดเตรียมเอง เนื่องจากไม่มีตัวอย่างที่สมบูรณ์ในตัวเอง หน้านี้จึงไม่ได้ตรึงแฮชที่ทำซ้ำได้

การติดตั้ง

แอปพลิเคชันโฮสต์เป็นผู้เลือกและติดตั้ง OpenTelemetry SDK พร้อม exporter หนึ่งตัว NextPDF อ่าน tracer provider ที่ลงทะเบียนไว้แบบ global และไม่ได้รวม SDK ของตนเองมาด้วย ก่อนพึ่งพา trace ให้รัน availability probe ที่จัดมาให้เพื่อยืนยันว่า NextPDF มองเห็น SDK โดย probe จะคืนค่า true ก็ต่อเมื่อ OpenTelemetry Application Programming Interface (API) อยู่ใน class path เท่านั้น

ภาพรวมเชิงแนวคิด

NextPDF ปล่อย span สำหรับวงจรชีวิตการสร้างเอกสาร รวมถึง counter และ histogram จำนวนหนึ่ง span เหล่านี้ครอบคลุม root build span การ resolve ฟอนต์ การ parse HyperText Markup Language (HTML) เค้าโครง การ decode รูปภาพ การ serialize รวมถึงเฟส barcode form navigation และ attachment ที่เป็นทางเลือก metric เหล่านี้ครอบคลุมระยะเวลาการเรนเดอร์ จำนวนหน้า คำเตือน หน่วยความจำสูงสุด ขนาดเอาต์พุต จำนวนฟอนต์ และจำนวนรูปภาพ รายการ span และ metric ที่แน่นอนขึ้นอยู่กับเวอร์ชัน NextPDF ที่ติดตั้งไว้ ดังนั้นจำนวนคงที่ใดๆ ในเนื้อหารุ่นเก่าให้ถือว่าขึ้นอยู่กับเวอร์ชัน โปรดยืนยันกับ build ที่กำลังทำงานอยู่แทนการจำตัวเลขตายตัว

เมื่อ NextPDF Connect ทำงานอยู่หลัง web framework การเรียก Connect จะปรากฏเป็น child ของ trace สำหรับคำขอ Hypertext Transfer Protocol (HTTP) ขาเข้า distributed trace เดียวจึงครอบคลุมจุดเข้า HTTP แอปพลิเคชัน และการ build PDF

พื้นผิว API

หน้านี้ไม่ได้กล่าวอ้างเกี่ยวกับ Connect tool ใดโดยเฉพาะ แต่อธิบายอินสตรูเมนเทชันแบบ cross-cutting แทน สำหรับพื้นผิว tool ดูที่ /connect/tool-catalog/ สำหรับ transport ดูที่ /transports/mcp/ /transports/rest/ และ /transports/grpc/

ตัวอย่างโค้ด — เริ่มต้นใช้งานอย่างรวดเร็ว

สร้างและลงทะเบียน tracer provider แบบ global ก่อนสร้าง PDF ใดๆ จากนั้นจึงสร้างเอกสารตามปกติ อินสตรูเมนเทชันภายในของ NextPDF จะปล่อย span และ metric โดยอัตโนมัติ โดยไม่ต้องเขียนโค้ดแยกสำหรับการเรียกแต่ละครั้ง ให้ flush provider เมื่อปิดโปรเซสเพื่อไม่ให้ span ที่บัฟเฟอร์ไว้สูญหาย แอปพลิเคชันโฮสต์เป็นเจ้าของการเชื่อมต่อกับ provider และ exporter จริง โครงการ OpenTelemetry PHP มีเอกสารอธิบายการเชื่อมต่อดังกล่าวแล้ว หน้านี้จึงไม่กล่าวซ้ำแบบคำต่อคำ

ตัวอย่างโค้ด — โปรดักชัน

สำหรับ collector ที่ export ผ่าน HTTP โฮสต์เป็นผู้จัดเตรียม PSR-18 HTTP client ให้ถือว่าความล้มเหลวของ transport และสถานะ HTTP ที่ไม่สำเร็จเป็นคนละกรณีกัน PSR-18 client จะ raise typed client exception ก็ต่อเมื่อไม่สามารถส่งคำขอได้เลยเท่านั้น (PSR-18 §4) ในทางตรงกันข้าม การตอบกลับ 4xx/5xx จะถูกส่งคืนให้ผู้เรียกตามปกติ และไม่ใช่ exception (PSR-18 §4) เส้นทางการ export ของ collector และ transport ของ Connect tool เป็นอิสระต่อกัน ดังนั้นการ export ของ collector ที่ล้มเหลวต้องไม่ทำให้การสร้าง PDF ล้มเหลวโดยเด็ดขาด

กรณีขอบและข้อควรระวัง

ลงทะเบียน provider หลังการสร้างครั้งแรก span ใดๆ ที่สร้างขึ้นก่อนการลงทะเบียนจะใช้ no-op tracer และจะไม่ไปถึง backend ลงทะเบียน provider ระหว่างการ boot ของแอปพลิเคชัน
ไม่มีการ flush เมื่อปิดระบบ batch processor จะบัฟเฟอร์ span ไว้ และ span เหล่านั้นจะสูญหายหากโปรเซสจบลงโดยไม่มีการ shutdown provider ให้ผูกการ shutdown provider เข้ากับ worker หรือ kernel terminate hook
การ export ผ่าน gRPC ต้องใช้ gRPC PHP extension การ export ผ่าน HTTP ไม่ต้องใช้ extension ดังนั้นให้เลือก HTTP เมื่อไม่มี extension ดังกล่าว
การเผยแพร่ W3C Trace Context เมื่อคำขอขาเข้ามี traceparent/tracestate SDK จะเผยแพร่ context นั้นไปยัง span ของ NextPDF โดยอัตโนมัติ และการเรียก Connect จะเข้าร่วม trace ของผู้เรียก

ประสิทธิภาพ

overhead ของอินสตรูเมนเทชันมีขนาดเล็กเมื่อเทียบกับเวลาในการสร้าง PDF budget ใน front-matter เป็นเพดานที่ระบุในเอกสาร ไม่ใช่การรับประกัน เมื่ออัตราคำขอสูง ให้ใช้ head-based sampling หรือ sampling ฝั่ง collector เพื่อจำกัดปริมาณและต้นทุนของ exporter

หมายเหตุด้านความปลอดภัย

เทเลเมทรีที่ปลอดภัยและการ scrub ล็อก

NextPDF บังคับใช้นโยบายข้อมูลเทเลเมทรีที่เข้มงวดและข้ามไม่ได้ allowlist ของแอตทริบิวต์แบบตายตัวจะ export เฉพาะ metadata เชิงโครงสร้างและ metric ด้านประสิทธิภาพเท่านั้น ได้แก่ จำนวนหน้า ฟอนต์ และรูปภาพ ขนาดไฟล์ ชื่อ output profile boolean flag ระยะเวลา หน่วยความจำ และตัวระบุเวอร์ชันกับ tier NextPDF จะไม่ export เนื้อหาเอกสาร เส้นทางไฟล์ raw stream byte base64 payload ข้อมูลส่วนบุคคล หรือ credential โดยเด็ดขาด โดยจะตัดแอตทริบิวต์ใดๆ ที่อยู่นอก allowlist ทิ้ง นอกจากนี้ยังตัดค่าใดๆ ที่ตรงกับรูปแบบ payload ทิ้งด้วย แม้ว่าตัว key เองจะได้รับอนุญาตก็ตาม พฤติกรรมนี้ช่วยให้ trace ไหลเข้าสู่ observability pipeline ที่ใช้ร่วมกันได้โดยไม่ทำให้ข้อมูลเอกสารรั่วไหล ทั้งหมดนี้เป็นพฤติกรรมของไลบรารี ไม่ใช่การรับประกันระดับการ deploy สำหรับ backend ที่รับ trace

ความสอดคล้อง

ข้อกล่าวอ้าง	ข้อกำหนด	reference_id (ตัวระบุอ้างอิง)
ความล้มเหลวของ transport เป็นกรณีเดียวที่ PSR-18 client จะเกิด exception	PSR-18 §4
การตอบกลับ 4xx/5xx เป็นการคืนค่าตามปกติ ไม่ใช่ exception	PSR-18 §4

โปรโตคอล OpenTelemetry และรูปแบบ World Wide Web Consortium (W3C) Trace Context เป็นข้อกำหนดภายนอกที่หน่วยงานที่เกี่ยวข้องดูแลแยกกัน หน้านี้ไม่ได้ยืนยันความสอดคล้องกับข้อกำหนดเหล่านั้น และไม่ได้คัดลอกข้อความจากข้อกำหนดดังกล่าว คำนิยามที่เป็นทางการอยู่ในข้อกำหนด OpenTelemetry ที่เผยแพร่แล้ว (https://opentelemetry.io/docs/specs/otel/) และ W3C Trace Context Recommendation (https://www.w3.org/TR/trace-context/)

บริบทเชิงพาณิชย์

ไม่เกี่ยวข้อง — อินสตรูเมนเทชันเป็นความสามารถหลักและไม่ได้ถูกจำกัดการเข้าถึง

รายละเอียดเฉพาะของ Connect

ความพร้อมใช้งานของ transport (MCP / REST / gRPC)

อินสตรูเมนเทชันไม่ขึ้นกับ transport การเรียก Connect ผ่าน transport ใดก็ตามจะสร้าง build-lifecycle span ชุดเดียวกัน transport จะเพิ่ม span ของตัวเองที่ครอบอยู่ด้านนอกเมื่อโฮสต์ทำอินสตรูเมนเทชันให้กับชั้น transport

ระดับความเสี่ยง HITL

observability แยกออกจากแบบจำลองความเสี่ยง การปล่อยเทเลเมทรีไม่ได้เปลี่ยนระดับความเสี่ยงของ tool และไม่เคยถูกจำกัดโดย ConfirmationGate

JSON envelope ของ confirmation gate

ไม่เกี่ยวข้อง — การปล่อยเทเลเมทรีไม่ใช่การเรียกใช้ tool จึงไม่ผ่าน gate

ดูเพิ่มเติม

/connect/tool-catalog/ — พื้นผิว tool ที่ถูกสังเกตการณ์
/transports/mcp/ / /transports/rest/ / /transports/grpc/ — transport ที่สามารถรับการเรียก Connect ที่ถูก trace ได้