OpenTelemetry로 NextPDF Connect 관찰하기

한눈에 보기

NextPDF에는 PDF 생성 수명 주기 전반에서 트레이스 스팬과 메트릭을 방출하는 내장 OpenTelemetry 계측이 포함되어 있습니다. 클래스 경로에 OpenTelemetry SDK가 없으면 계측은 비활성 상태로 유지됩니다. 성능 저하도, 오토로드 실패도, 별도 구성도 없습니다. 이 페이지는 전송 방식에 구애받지 않는 개념 설명이므로, PDF가 어떤 방식으로 생성되든 동일한 계측이 적용됩니다. 인프로세스 호출, MCP tools/call, REST 요청, 또는 NextPDF Connect에 대한 gRPC 호출 어느 경우에도 마찬가지입니다.

이 페이지는 실행 가능한 레시피라기보다 설명 문서로 보십시오. OpenTelemetry SDK와 익스포터는 NextPDF가 아니라 호스트 애플리케이션이 제공하므로, 이 페이지에는 재현 가능한 해시를 고정할 수 있는 자체 완결형 예제가 없습니다.

설치

호스트 애플리케이션에서 OpenTelemetry SDK와 익스포터 하나를 선택해 설치합니다. NextPDF는 전역으로 등록된 트레이서 프로바이더를 읽으며, 자체 SDK를 번들로 포함하지 않습니다. 트레이스에 의존하기 전에 번들로 제공되는 가용성 프로브를 실행해 NextPDF가 SDK를 인식할 수 있는지 확인하십시오. 이 프로브는 OpenTelemetry API가 클래스 경로에 있을 때만 true를 반환합니다.

개념 개요

NextPDF는 문서 빌드 수명 주기에 대한 스팬과 소수의 카운터 및 히스토그램을 방출합니다. 스팬은 루트 빌드 스팬을 비롯해 폰트 해석, HTML 파싱, 레이아웃, 이미지 디코딩, 직렬화, 그리고 선택적인 바코드, 폼, 내비게이션, 첨부 단계를 포괄합니다. 메트릭은 렌더링 소요 시간, 페이지 수, 경고, 최대 메모리, 출력 크기, 폰트 수, 이미지 수를 포괄합니다. 정확한 스팬 및 메트릭 목록은 설치된 NextPDF 버전에 따라 달라지므로, 오래된 문구에 나오는 고정된 개수는 버전별로 달라질 수 있는 값으로 취급하십시오. 숫자를 외우기보다 실행 중인 빌드를 기준으로 확인하십시오.

NextPDF Connect가 웹 프레임워크 뒤에서 실행되면, Connect 호출은 들어오는 요청 트레이스의 자식으로 나타납니다. 그러면 단일 분산 트레이스가 HTTP 진입점, 애플리케이션, PDF 빌드에 걸쳐 이어집니다.

API 표면

이 페이지는 특정 Connect 도구를 단언하지 않습니다. 대신 횡단 관심사인 계측을 설명합니다. 도구 표면은 /connect/tool-catalog/를 참조하고, 전송 방식은 /transports/mcp/, /transports/rest/, /transports/grpc/를 참조하십시오.

코드 샘플 — 빠른 시작

PDF를 생성하기 전에 트레이서 프로바이더를 빌드해 전역으로 등록한 다음, 평소처럼 생성하십시오. NextPDF의 내부 계측은 호출별 코드 없이 스팬과 메트릭을 자동으로 방출합니다. 버퍼링된 스팬이 손실되지 않도록 프로세스 종료 시 프로바이더를 플러시하십시오. 구체적인 프로바이더 및 익스포터 연결 방식은 호스트 애플리케이션이 선택합니다. 이는 OpenTelemetry PHP 프로젝트에서 문서화하고 있으므로, 이 페이지에서는 그대로 반복하지 않습니다.

코드 샘플 — 프로덕션

HTTP로 내보내는 컬렉터의 경우, 호스트가 PSR-18 HTTP 클라이언트를 제공합니다. 전송 실패와 성공이 아닌 HTTP 상태를 서로 다른 경우로 취급하십시오. PSR-18 클라이언트는 요청을 아예 보낼 수 없을 때에만 타입이 지정된 클라이언트 예외를 발생시킵니다(PSR-18 §4). 반면 4xx/5xx 응답은 호출자에게 정상적으로 반환되며 예외가 아닙니다(PSR-18 §4). 컬렉터 내보내기 경로와 Connect 도구 전송은 서로 독립적이므로, 컬렉터 내보내기가 실패하더라도 PDF 생성 자체가 실패하도록 허용해서는 절대 안 됩니다.

엣지 케이스 및 함정

첫 생성 이후에 등록된 프로바이더. 등록 전에 생성된 스팬은 no-op 트레이서를 사용하며 백엔드에 결코 도달하지 않습니다. 애플리케이션 부팅 중에 프로바이더를 등록하십시오.
종료 시 플러시 없음. 배치 프로세서는 스팬을 버퍼링하므로, 프로바이더 종료 없이 프로세스가 종료되면 해당 스팬은 손실됩니다. 종료를 워커 또는 커널 terminate 훅에 연결하십시오.
gRPC 내보내기에는 gRPC PHP 확장이 필요합니다. HTTP 내보내기에는 확장이 필요 없으므로, 확장을 사용할 수 없을 때는 HTTP를 선택하십시오.
W3C Trace Context 전파. 들어오는 요청이 traceparent/tracestate를 포함하면, SDK는 그 컨텍스트를 NextPDF의 스팬으로 자동 전파하며, Connect 호출은 호출자의 트레이스에 합류합니다.

성능

계측 오버헤드는 PDF 생성 시간에 비해 작습니다. 프런트매터의 예산은 보장이 아니라 문서상의 상한입니다. 요청률이 높을 때는 익스포터 볼륨과 비용을 제한하기 위해 헤드 기반 샘플링이나 컬렉터 측 샘플링을 사용하십시오.

보안 참고 사항

안전한 텔레메트리 및 로그 스크러빙

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 호출이든 동일한 빌드 수명 주기 스팬을 생성하며, 호스트가 전송 계층을 계측하면 해당 전송을 감싸는 자체 스팬을 추가합니다.

HITL 위험 티어

가시성은 위험 모델과 직교합니다. 텔레메트리를 방출한다고 해서 도구의 위험 수준이 바뀌지 않으며, ConfirmationGate에 의해 결코 게이트로 제한되지 않습니다.

확인 게이트 JSON 엔벨로프

해당 없음 — 텔레메트리 방출은 도구 호출이 아니므로 게이트를 통과하지 않습니다.

함께 보기

/connect/tool-catalog/ — 관찰 대상 도구 표면입니다.
/transports/mcp/ / /transports/rest/ / /transports/grpc/ — 트레이스된 Connect 호출이 도착할 수 있는 전송 방식입니다.