Obserwacja NextPDF Connect za pomocą OpenTelemetry

W skrócie

NextPDF zawiera wbudowaną instrumentację OpenTelemetry, która emituje rozpiętości śladu i metryki w całym cyklu życia generowania dokumentu Portable Document Format (PDF). Gdy na ścieżce klas nie ma zestawu Software Development Kit (SDK) OpenTelemetry, instrumentacja pozostaje nieaktywna: nie powoduje spadku wydajności, nie wywołuje błędu autoładowania i nie wymaga konfiguracji. Ta strona jest niezależna od transportu, więc ta sama instrumentacja działa niezależnie od sposobu generowania pliku PDF: przez wywołanie wewnątrzprocesowe, wywołanie tools/call protokołu Model Context Protocol (MCP), żądanie Representational State Transfer (REST) lub wywołanie gRPC do NextPDF Connect.

Traktuj tę stronę jako wyjaśnienie, a nie przepis gotowy do uruchomienia. Aplikacja hosta dostarcza SDK OpenTelemetry oraz eksporter. NextPDF tego nie robi. Ponieważ nie ma samodzielnego przykładu, ta strona nie zawiera odtwarzalnego skrótu.

Instalacja

Aplikacja hosta wybiera i instaluje SDK OpenTelemetry oraz jeden eksporter. NextPDF odczytuje globalnie zarejestrowanego dostawcę śledzenia i nie dołącza własnego SDK. Zanim zaczniesz polegać na śladach, uruchom dołączoną sondę dostępności, aby potwierdzić, że NextPDF widzi SDK. Sonda zwraca wartość true tylko wtedy, gdy interfejs Application Programming Interface (API) OpenTelemetry jest dostępny na ścieżce klas.

Przegląd koncepcyjny

NextPDF emituje rozpiętości dla cyklu życia budowania dokumentu oraz niewielki zestaw liczników i histogramów. Rozpiętości obejmują główną rozpiętość budowania, rozwiązywanie czcionek, parsowanie HyperText Markup Language (HTML), układ, dekodowanie obrazów, serializację oraz opcjonalne fazy kodów kreskowych, formularzy, nawigacji i załączników. Metryki obejmują czas renderowania, liczbę stron, ostrzeżenia, szczytowe użycie pamięci, rozmiar danych wyjściowych, liczbę czcionek oraz liczbę obrazów. Dokładny wykaz rozpiętości i metryk zależy od zainstalowanej wersji NextPDF, więc każdą stałą liczbę podaną w starszym tekście traktuj jako zależną od wersji. Weryfikuj ją w działającej kompilacji, zamiast polegać na zapamiętanej wartości.

Gdy NextPDF Connect działa za frameworkiem webowym, wywołanie Connect pojawia się jako element podrzędny śladu przychodzącego żądania Hypertext Transfer Protocol (HTTP). Pojedynczy ślad rozproszony obejmuje wtedy punkt wejścia HTTP, aplikację oraz budowanie pliku PDF.

Powierzchnia API

Ta strona nie deklaruje narzędzia Connect. Opisuje instrumentację przekrojową. Powierzchnia narzędzi jest opisana w /connect/tool-catalog/. Transporty są opisane w /transports/mcp/, /transports/rest/ oraz /transports/grpc/.

Przykład kodu — szybki start

Utwórz dostawcę śledzenia i zarejestruj go globalnie, zanim wygenerujesz jakikolwiek plik PDF, a następnie generuj jak zwykle. Wewnętrzna instrumentacja NextPDF emituje rozpiętości i metryki automatycznie, bez kodu dla poszczególnych wywołań. Opróżnij dostawcę przy zamykaniu procesu, aby buforowane rozpiętości nie zostały utracone. Aplikacja hosta odpowiada za konkretne powiązanie dostawcy z eksporterem. Projekt OpenTelemetry PHP dokumentuje to powiązanie, a ta strona nie powtarza go dosłownie.

Przykład kodu — produkcja

W przypadku eksportu do kolektora przez HTTP host dostarcza klienta HTTP zgodnego z PSR-18. Rozróżniaj awarię transportu i status HTTP oznaczający błąd jako odrębne przypadki. Klient PSR-18 zgłasza typowany wyjątek klienta tylko wtedy, gdy w ogóle nie może wysłać żądania (PSR-18 §4). Odpowiedź 4xx/5xx wraca natomiast do wywołującego normalnie i nie jest wyjątkiem (PSR-18 §4). Ścieżka eksportu do kolektora oraz transport narzędzia Connect są niezależne, więc niepowodzenie eksportu do kolektora nigdy nie może spowodować niepowodzenia samego generowania pliku PDF.

Przypadki brzegowe i pułapki

Dostawca zarejestrowany po pierwszym generowaniu. Każda rozpiętość utworzona przed rejestracją korzysta z pustego mechanizmu śledzenia i nigdy nie dociera do backendu. Zarejestruj dostawcę podczas rozruchu aplikacji.
Brak opróżnienia przy zamknięciu. Procesor wsadowy buforuje rozpiętości, które zostaną utracone, jeśli proces zakończy się bez zamknięcia dostawcy. Podłącz zamknięcie dostawcy do procesu roboczego lub do haka kernel terminate.
Eksport gRPC wymaga rozszerzenia PHP gRPC. Eksport HTTP nie wymaga rozszerzenia, więc wybierz HTTP, gdy rozszerzenie jest niedostępne.
Propagacja W3C Trace Context. Gdy przychodzące żądanie zawiera traceparent/tracestate, SDK automatycznie propaguje ten kontekst do rozpiętości NextPDF, a wywołanie Connect dołącza do śladu wywołującego.

Wydajność

Narzut instrumentacji jest niewielki w porównaniu z czasem generowania pliku PDF. Budżet z front-matter jest limitem dokumentacyjnym, a nie gwarancją. Przy dużej częstotliwości żądań stosuj próbkowanie head-based lub po stronie kolektora, aby ograniczyć wolumen eksportowanych danych i koszt.

Uwagi dotyczące bezpieczeństwa

Bezpieczna telemetria i oczyszczanie dzienników

NextPDF wymusza rygorystyczne, niemożliwe do obejścia zasady dotyczące danych telemetrycznych. Stała lista dozwolonych atrybutów pozwala eksportować tylko metadane strukturalne i metryki wydajności: liczbę stron, czcionek i obrazów, rozmiary plików, nazwy profili wyjściowych, flagi logiczne, czasy trwania, pamięć oraz identyfikatory wersji i poziomu. NextPDF nigdy nie eksportuje treści dokumentu, ścieżek plików, surowych bajtów strumienia, ładunków base64, danych osobowych ani poświadczeń. Odrzuca każdy atrybut spoza listy dozwolonych. Odrzuca również każdą wartość pasującą do wzorca ładunku, nawet gdy sam klucz jest dozwolony. Takie zachowanie pozwala śladom przepływać do współdzielonego potoku obserwowalności bez wycieku danych dokumentu. Jest to zachowanie biblioteki, a nie gwarancja na poziomie wdrożenia dotycząca backendu, który odbiera ślady.

Zgodność

Twierdzenie	Klauzula	reference_id
Awaria transportu jest jedynym przypadkiem wyjątku klienta PSR-18	PSR-18 §4
Odpowiedź 4xx/5xx jest normalnym zwrotem, a nie wyjątkiem	PSR-18 §4

Protokół OpenTelemetry oraz format Trace Context organizacji World Wide Web Consortium (W3C) są specyfikacjami zewnętrznymi, z których każda jest utrzymywana przez odpowiednią organizację. Ta strona nie deklaruje zgodności z nimi i nie odtwarza ich tekstu. Wiążące definicje znajdują się w opublikowanej specyfikacji OpenTelemetry (https://opentelemetry.io/docs/specs/otel/) oraz w rekomendacji W3C Trace Context (https://www.w3.org/TR/trace-context/).

Kontekst komercyjny

Nie dotyczy — instrumentacja jest funkcją podstawową i nie jest objęta bramkowaniem.

Szczegóły dotyczące Connect

Dostępność transportu (MCP / REST / gRPC)

Instrumentacja jest niezależna od transportu. Wywołanie Connect przez dowolny transport tworzy te same rozpiętości cyklu życia budowania. Transport dodaje własną rozpiętość otaczającą, gdy host instrumentuje warstwę transportu.

Poziom ryzyka HITL

Obserwowalność jest oddzielona od modelu ryzyka. Emitowanie telemetrii nie zmienia poziomu ryzyka narzędzia i nigdy nie jest bramkowane przez ConfirmationGate.

Koperta JSON bramki potwierdzenia

Nie dotyczy — emisja telemetrii nie jest wywołaniem narzędzia, więc nie przechodzi przez bramkę.

Zobacz też

/connect/tool-catalog/ — powierzchnia narzędzi objęta obserwowalnością.
/transports/mcp/ / /transports/rest/ / /transports/grpc/ — transporty, które mogą obsłużyć śledzone wywołanie Connect.