Трассировки OpenTelemetry из браузера

JavaScript SDK OpenTelemetry для браузеров состоит из нескольких пакетов: @opentelemetry/sdk-trace-web предоставляет основную реализацию трассировки, @opentelemetry/instrumentation-fetch автоматически создаёт отрезки для всех вызовов fetch API, а @opentelemetry/exporter-trace-otlp-http отправляет отрезки сборщику.

TracerProvider — центральный объект конфигурации в OpenTelemetry. Он содержит список SpanProcessors, определяющих, что происходит с завершёнными отрезками, ресурс с описанием приложения (именем и версией сервиса), а также настройки выборки.

BatchSpanProcessor собирает завершённые отрезки в памяти и экспортирует их пакетами, а не отправляет каждый отрезок отдельно. Это значительно сокращает количество HTTP-запросов к сборщику, повышает производительность браузера и уменьшает нагрузку на конечную точку сборщика OTel.

OTLPTraceExporter отправляет пакетные отрезки совместимому с OpenTelemetry сборщику по HTTP в формате JSON или protobuf. Вы задаёте адрес сборщика (например, конечную точку прокси OTel Collector), а экспортёр автоматически выполняет сериализацию и повторные попытки.

Отрезок представляет собой отдельную единицу работы внутри трассировки: монтирование компонента, вызов сервера или действие пользователя. У отрезков есть имя, время начала, время окончания, состояние (OK или ERROR) и набор атрибутов «ключ — значение». Связанные отрезки объединяются общим ID трассировки и отношениями «родитель — потомок».

Создайте трассировщик с помощью provider.getTracer('react-app') и запускайте отрезки с помощью tracer.startSpan('component-mount'). После завершения работы вызовите span.end(), чтобы записать время окончания. Всегда завершайте отрезки: оставленные без завершения отрезки расходуют память и создают неполные данные в вашей системе наблюдаемости.

Атрибуты обогащают отрезки контекстными данными: span.setAttribute('user.id', userId) или span.setAttribute('route', location.pathname). По атрибутам можно выполнять поиск в вашей системе наблюдаемости, что позволяет формировать запросы вроде «показать все медленные отрезки для пользователя 42» или «показать все ошибки на маршруте /checkout».

@opentelemetry/instrumentation-fetch изменяет глобальную функцию fetch, чтобы автоматически создавать отрезки для каждого исходящего HTTP-запроса. Отрезок фиксирует адрес, метод, код состояния HTTP и длительность без каких-либо изменений в существующих вызовах fetch.

Когда инструментирование fetch создаёт интервал для исходящего запроса, оно внедряет заголовок traceparent W3C TraceContext в запрос. Получающий сервер читает этот заголовок и продолжает ту же трассировку, создавая связанную трассировку, охватывающую браузер и сервер.

Инициализация OpenTelemetry должна выполняться до монтирования любых компонентов — обычно во входном файле приложения (main.tsx), до вызова ReactDOM.createRoot. Создайте провайдер, зарегистрируйте процессоры и экспортёры и вызовите provider.register(), чтобы сделать его глобальным TracerProvider.

Запись каждого взаимодействия пользователя в приложениях с высокой нагрузкой создаёт огромный объём данных трассировки. Настройте механизм выборки TraceIdRatioBased в TracerProvider, например отбирайте 10% трассировок, чтобы уменьшить объём данных. Всегда отбирайте 100% трассировок с ошибками с помощью механизма выборки ParentBased, чтобы ни одна ошибка не осталась незамеченной.

Почему в браузерных приложениях используется BatchSpanProcessor, а не SimpleSpanProcessor?

JavaScript SDK OpenTelemetry инструментирует браузеры с помощью TracerProvider, BatchSpanProcessor и OTLPTraceExporter. Интервалы представляют единицы работы, дополненные атрибутами. Инструментирование fetch автоматически создаёт интервалы для вызовов программного интерфейса и внедряет заголовки W3C TraceContext для сквозной распределённой трассировки. Инициализируйте систему заранее, правильно настраивайте выборку и всегда завершайте интервалы, чтобы сохранять чистые данные трассировки.