Наблюдаемость NextPDF Connect с помощью OpenTelemetry

Кратко

NextPDF содержит встроенную инструментацию OpenTelemetry, которая формирует спаны трассировки и метрики в течение всего жизненного цикла генерации Portable Document Format (PDF). Если в class path нет Software Development Kit (SDK) OpenTelemetry, инструментация остаётся неактивной: нет потерь производительности, сбоев автозагрузки и обязательной настройки. Описанное здесь не зависит от транспорта, поэтому одна и та же инструментация применяется независимо от способа генерации PDF: через внутрипроцессный вызов, вызов tools/call по Model Context Protocol (MCP), запрос Representational State Transfer (REST) или вызов gRPC к NextPDF Connect.

Воспринимайте эту страницу как пояснение, а не как готовый к запуску рецепт. Хост-приложение предоставляет SDK OpenTelemetry и экспортёр. NextPDF их не поставляет. Поскольку самодостаточного примера нет, эта страница не фиксирует воспроизводимый хеш.

Установка

Хост-приложение выбирает и устанавливает SDK OpenTelemetry и один экспортёр. NextPDF читает глобально зарегистрированный поставщик трассировщика и не включает собственный SDK. Прежде чем полагаться на трассировки, запустите встроенную проверку доступности и убедитесь, что NextPDF видит SDK. Проверка возвращает true только тогда, когда Application Programming Interface (API) OpenTelemetry находится в class path.

Концептуальный обзор

NextPDF формирует спаны для жизненного цикла сборки документа, а также небольшой набор счётчиков и гистограмм. Спаны охватывают корневой спан сборки, разрешение шрифтов, разбор HyperText Markup Language (HTML), построение макета, декодирование изображений, сериализацию, а также необязательные этапы штрихкодов, форм, навигации и вложений. Метрики охватывают длительность отрисовки, число страниц, предупреждения, пиковую память, размер вывода, число шрифтов и число изображений. Точный перечень спанов и метрик зависит от установленной версии NextPDF, поэтому считайте любое фиксированное число в более старых текстах зависящим от версии. Сверяйте его с работающей сборкой, а не полагайтесь на запомненное число.

Когда NextPDF Connect работает за веб-фреймворком, вызов Connect отображается как дочерний для трассировки входящего запроса Hypertext Transfer Protocol (HTTP). В результате единая распределённая трассировка охватывает точку входа HTTP, приложение и сборку PDF.

Поверхность API

Эта страница не объявляет инструмент Connect. Вместо этого она описывает сквозную инструментацию. Сведения о поверхности инструментов см. в /connect/tool-catalog/. Сведения о транспортах см. в /transports/mcp/, /transports/rest/ и /transports/grpc/.

Пример кода — быстрый старт

Создайте и глобально зарегистрируйте поставщик трассировщика, прежде чем генерировать любой PDF, а затем выполняйте генерацию как обычно. Внутренняя инструментация NextPDF автоматически формирует спаны и метрики без кода для каждого вызова. Сбрасывайте поставщик при завершении процесса, чтобы буферизованные спаны не были потеряны. За конкретную настройку поставщика и экспортёра отвечает хост-приложение. Проект OpenTelemetry PHP документирует эту настройку, и данная страница не воспроизводит её дословно.

Пример кода — продакшен

Для экспорта в коллектор по HTTP хост предоставляет HTTP-клиент PSR-18. Рассматривайте сбой транспорта и неуспешный статус HTTP как отдельные случаи. Клиент PSR-18 выбрасывает типизированное клиентское исключение только тогда, когда вообще не может отправить запрос (PSR-18 §4). Ответ 4xx/5xx, напротив, штатно возвращается вызывающей стороне и не является исключением (PSR-18 §4). Путь экспорта в коллектор и транспорт инструмента Connect не зависят друг от друга, поэтому неудачный экспорт в коллектор никогда не должен приводить к сбою самой генерации PDF.

Граничные случаи и подводные камни

Поставщик зарегистрирован после первой генерации. Любой спан, созданный до регистрации, использует трассировщик-заглушку и никогда не достигает бэкенда. Регистрируйте поставщик при запуске приложения.
Нет сброса при завершении. Пакетный обработчик буферизует спаны, и они теряются, если процесс завершается без остановки поставщика. Привяжите остановку поставщика к воркеру или к хуку завершения ядра.
Экспорт по gRPC требует расширения gRPC для PHP. Экспорт по HTTP не требует расширения, поэтому выбирайте HTTP, когда расширение недоступно.
Распространение W3C Trace Context. Когда входящий запрос содержит traceparent/tracestate, SDK автоматически распространяет этот контекст в спаны NextPDF, и вызов Connect присоединяется к трассировке вызывающей стороны.

Производительность

Накладные расходы инструментации малы по сравнению со временем генерации PDF. Бюджет, указанный во front-matter, — это документационный предел, а не гарантия. При высокой частоте запросов используйте сэмплирование на стороне источника или коллектора, чтобы ограничить объём и стоимость экспорта.

Примечания по безопасности

Безопасная телеметрия и очистка журналов

NextPDF применяет строгую политику телеметрических данных, которую нельзя обойти. Через фиксированный список разрешённых атрибутов экспортируются только структурные метаданные и метрики производительности: число страниц, шрифтов и изображений, размеры файлов, имена выходных профилей, булевы флаги, длительности, память, а также идентификаторы версии и уровня. NextPDF никогда не экспортирует содержимое документа, пути к файлам, необработанные байты потока, полезные данные base64, персональные данные или учётные данные. Он отбрасывает любой атрибут вне списка разрешённых. Он также отбрасывает любое значение, совпадающее с шаблоном полезных данных, даже если сам ключ разрешён. Такое поведение позволяет трассировкам поступать в общий конвейер наблюдаемости без утечки данных документа. Это поведение библиотеки, а не гарантия уровня развёртывания для бэкенда, который принимает трассировки.

Соответствие

Утверждение	Пункт	reference_id (идентификатор ссылки)
Сбой транспорта — единственный случай клиентского исключения PSR-18	PSR-18 §4
Ответ 4xx/5xx — это штатный возврат, а не исключение	PSR-18 §4

Протокол OpenTelemetry и формат Trace Context консорциума World Wide Web Consortium (W3C) — внешние спецификации, за каждую из которых отвечает соответствующая организация. Эта страница не заявляет о соответствии им и не воспроизводит их текст. Авторитетные определения находятся в опубликованной спецификации 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.