Понимание и Использование Заголовка X-dynaTrace в Dynatrace

Как Dynatrace Обеспечивает Сквозную Трассировку Транзакций

Заголовок X-dynaTrace является ключевым элементом в работе Dynatrace, обеспечивая сквозную трассировку транзакций и корреляцию данных по всей вашей распределенной системе. Он играет фундаментальную роль в том, как Dynatrace OneAgent собирает и связывает информацию о производительности, позволяя вам видеть полный путь запроса от пользовательского интерфейса до глубоких бэкенд-сервисов.

Ключевые Особенности Заголовка X-dynaTrace

Автоматическая Корреляция:
Dynatrace OneAgent автоматически добавляет заголовок X-dynaTrace к HTTP-запросам, что позволяет связывать части одной транзакции, проходящие через различные сервисы и компоненты. Это особенно важно в микросервисной архитектуре, где запрос может пересекать множество границ сервисов.
Приоритет в Среде Dynatrace:
Внутри одной среды Dynatrace заголовок X-dynaTrace имеет более высокий приоритет для сшивания транзакций по сравнению с заголовками W3C Trace Context (traceparent и tracestate). Это гарантирует, что Dynatrace использует свой собственный механизм для оптимальной корреляции в своей экосистеме.
Предотвращение Разрыва Трассировок:
Если заголовок X-dynaTrace теряется (например, из-за блокировки брандмауэром или некорректной конфигурации сетевых компонентов), контекст трассировки прерывается, и Dynatrace OneAgent начнет новую трассировку. Это подчеркивает критическую важность обеспечения его беспрепятственного прохождения через все сетевые устройства.

Назначение Заголовка X-dynaTrace

Как Заголовок X-dynaTrace Обеспечивает Глубокий Мониторинг

Заголовок X-dynaTrace служит нескольким критически важным целям в платформе мониторинга Dynatrace. Его основная функция — обеспечить непрерывную и подробную трассировку распределенных транзакций, что является основой для выявления и диагностики проблем производительности и доступности.

Трассировка Распределенных Транзакций (PurePath)

Центральная концепция Dynatrace - это PurePath, которая предоставляет полную, сквозную видимость каждой транзакции от ее начала до завершения. Заголовок X-dynaTrace является неотъемлемой частью этой технологии. Когда запрос инициируется (например, пользователем в веб-приложении или мобильном приложении), Dynatrace OneAgent добавляет этот заголовок с уникальным идентификатором. По мере того как запрос передается от одного сервиса к другому, OneAgent на каждом последующем сервисе читает этот заголовок и использует его для связывания текущей операции с исходной транзакцией. Это позволяет Dynatrace построить полный граф зависимостей и временные рамки для каждого шага транзакции, даже если она проходит через множество микросервисов, баз данных и других компонентов.

Мобильные OneAgent'ы, в частности, активно используют заголовок x-dynatrace для тегирования HTTP-запросов, обеспечивая корреляцию мобильной части веб-трафика. Это позволяет связать действия пользователя в мобильном приложении с соответствующими серверными операциями и получить полное представление о пользовательском опыте.

Корреляция Веб-Запросов и Действий Пользователей

В контексте мониторинга реальных пользователей (RUM) и мобильных приложений, заголовок X-dynaTrace используется для корреляции веб-запросов с действиями пользователей. Когда пользователь взаимодействует с веб-сайтом или мобильным приложением, OneAgent для мобильных устройств или JavaScript-инжектор для веб-приложений добавляет этот заголовок к исходящим HTTP-запросам. Это позволяет Dynatrace связать конкретные действия пользователя с последующими запросами к бэкенду, предоставляя ценную информацию о влиянии производительности бэкенда на пользовательский опыт.

Dynatrace Custom HTTP Header for WebHooks

Настройка пользовательских HTTP-заголовков для интеграции WebHook в Dynatrace

Интеграция с Инструментами Тестирования

Заголовок X-dynaTrace также играет важную роль при интеграции Dynatrace с инструментами нагрузочного тестирования, такими как JMeter и Gatling. Эти инструменты могут быть настроены на добавление специального заголовка X-Dynatrace-Test с набором пар ключ/значение. Это позволяет Dynatrace связывать результаты нагрузочных тестов с конкретными сессиями и запросами в системе мониторинга, что облегчает анализ производительности под нагрузкой и выявление узких мест.

Интеграция Dynatrace с JMeter для анализа нагрузочного тестирования

Видео ниже демонстрирует, как интегрировать Dynatrace с JMeter для углубленного анализа производительности.

Интеграция Dynatrace с JMeter для анализа нагрузочного тестирования

Расширение Контекста Трассировки

Заголовок X-dynaTrace содержит информацию о текущей трассировке/сегменте и передается от сервиса к сервису для поддержания дальнейших трассировок в том же контексте. Это предотвращает создание новых, несвязанных трассировок и гарантирует, что вся распределенная транзакция отслеживается как единое целое. Это особенно важно в сложных системах с множеством взаимодействующих компонентов.

Механизм Добавления Заголовка

Как Dynatrace Инжектирует X-dynaTrace

Добавление заголовка X-dynaTrace происходит в основном автоматически благодаря технологии Dynatrace OneAgent. OneAgent - это легкий компонент, который устанавливается на хостах и автоматически обнаруживает и инструментирует приложения и сервисы, работающие на этих хостах.

Автоматическая Инструментация OneAgent

Когда OneAgent обнаруживает процесс, генерирующий HTTP-запросы, он автоматически инжектирует свой код в этот процесс. Этот инжектированный код перехватывает исходящие HTTP-запросы и добавляет к ним заголовок X-dynaTrace. Этот процесс полностью автоматизирован и не требует ручной настройки или изменения кода приложения. Для мобильных приложений OneAgent for Mobile или OneAgent SDK для iOS/Android также добавляют этот заголовок для корреляции мобильных запросов.

OneAgent SDK

Для случаев, когда автоматическая инструментация невозможна или требуется более тонкий контроль, Dynatrace предоставляет OneAgent SDK. Разработчики могут использовать SDK для ручного добавления заголовка X-dynaTrace к исходящим веб-запросам. Например, в Java SDK есть метод, который, основываясь на конфигурации, добавляет заголовок X-dynaTrace и/или заголовки W3C Trace Context (traceparent и tracestate).


        // Пример кода (псевдокод) с использованием OneAgent SDK
        // Получение трассера исходящего веб-запроса
        OutgoingWebRequestTracer tracer = oneAgentSdk.traceOutgoingWebRequest(...);

        // Получение Dynatrace-тега для включения в заголовок
        String dynatraceTag = tracer.getDynatraceStringTag();

        // Добавление заголовка X-dynaTrace к запросу
        httpRequest.addHeader("X-dynaTrace", dynatraceTag);

        // Начало трассировки
        tracer.start();

        // Выполнение HTTP-запроса
        response = httpClient.execute(httpRequest);

        // Конец трассировки
        tracer.end();

Это позволяет обеспечить трассировку даже в тех компонентах, которые не поддерживаются автоматической инструментацией OneAgent напрямую, или в сценариях, где требуется пользовательская логика трассировки.

Конфигурация HTTP-мониторов

При настройке HTTP-мониторов в Dynatrace, вы можете вручную добавлять HTTP-заголовки, включая X-dynaTrace, а также X-Dynatrace-Tenant и X-Dynatrace-Test для внутренних административных целей. Это особенно полезно для синтетического мониторинга, где вы хотите имитировать пользовательские запросы с определенным контекстом трассировки.

Проблемы и Решения, Связанные с X-dynaTrace

Устранение Препятствий для Эффективной Трассировки

Хотя заголовок X-dynaTrace является мощным инструментом, его использование может столкнуться с определенными проблемами, особенно в сложных сетевых средах или при взаимодействии с устаревшими системами.

Блокировка Брандмауэрами и API-шлюзами

Одной из наиболее распространенных проблем является блокировка или удаление заголовка X-dynaTrace сетевыми компонентами, такими как брандмауэры, прокси-серверы или API-шлюзы (например, Axway API Gateway). Если эти компоненты настроены на удаление неизвестных заголовков или имеют строгие политики безопасности, они могут непреднамеренно препятствовать прохождению заголовка Dynatrace, что приводит к разрыву трассировок.

Решение: Необходимо настроить сетевые компоненты (брандмауэры, прокси, API-шлюзы) так, чтобы они разрешали прохождение заголовка X-dynaTrace. Это часто включает добавление правил регулярных выражений для явного разрешения этого заголовка.

Проблемы с Расширением Заголовка

В некоторых редких случаях заголовок X-dynaTrace может чрезмерно расширяться, что приводит к отклонению запросов Opentelemetry Collector из-за превышения размера заголовка. Это может быть связано с некорректным повторным использованием объектов метаданных gRPC или пользовательскими настройками заголовков.

Решение: Рекомендуется обратиться в службу поддержки Dynatrace для расследования таких случаев. Временные обходные пути могут включать проверку того, не используются ли объекты GRPC Metadata повторно для разных вызовов, и нет ли пользовательских функций установки заголовков, которые постоянно добавляют заголовок.

Нечитаемый Формат Заголовка в Kafka

Заголовок X-dynaTrace, передаваемый в сообщениях Kafka, не предназначен для ручного чтения или декодирования вне Dynatrace. Он представляет собой байтовый массив, который кажется "тарабарщиной" при попытке преобразования в строку.

Решение: Dynatrace не предоставляет официального способа декодирования этого заголовка вне своей платформы. Цель состоит в том, чтобы сохранить контекст трассировки внутри экосистемы Dynatrace для автоматической корреляции. Если вам нужна информация о трассировке для внешних систем, рассмотрите использование W3C Trace Context, который является стандартизированным и предназначен для интероперабельности.

Конфликты с W3C Trace Context

Dynatrace поддерживает как свой собственный заголовок X-dynaTrace, так и стандарты W3C Trace Context (traceparent и tracestate). Внутри одной среды Dynatrace заголовок X-dynaTrace имеет приоритет для сшивания транзакций. Однако для сквозной трассировки между различными средами Dynatrace или системами, использующими OpenTelemetry/другие инструменты трассировки, рекомендуются заголовки W3C.

Решение: При развертывании в гетерогенных средах или при необходимости обмена данными трассировки с другими инструментами, используйте W3C Trace Context. Dynatrace может интерпретировать и использовать эти заголовки для расширения трассировок за пределы своей собственной среды.

Отключение Добавления Заголовка

В некоторых случаях может потребоваться предотвратить добавление заголовка X-dynaTrace к определенным запросам. Это может быть вызвано требованиями безопасности, совместимости с устаревшими системами или желанием сократить накладные расходы.

Решение: Полностью отключить добавление заголовка X-dynaTrace на уровне процесса или сервиса без отключения функций OneAgent в целом затруднительно. Исключение URL-путей через "URL-based sampling" не предотвращает добавление заголовка, а лишь отфильтровывает запросы из кластера Dynatrace. Если требуется полное отключение для конкретных запросов, возможно, потребуется отключить мониторинг для соответствующего сервиса или рассмотреть индивидуальную настройку через OneAgent SDK, где это применимо.

Сравнение X-dynaTrace и W3C Trace Context

Различия в Подходах к Распределенной Трассировке

Важно понимать разницу между проприетарным заголовком Dynatrace X-dynaTrace и стандартизированными заголовками W3C Trace Context (traceparent и tracestate). Оба служат для распределенной трассировки, но имеют разные области применения и приоритеты.

Приведенная выше радарная диаграмма визуально сравнивает ключевые аспекты заголовков X-dynaTrace и W3C Trace Context. Она иллюстрирует их относительные сильные стороны в таких областях, как автоматическая инструментация, приоритет в рамках экосистемы Dynatrace, интероперабельность со сторонними системами, уровень стандартизации, расширяемость и глубина детализации трассировки. Как видно, X-dynaTrace превосходит в аспектах, ориентированных на Dynatrace, в то время как W3C Trace Context лидирует в интероперабельности и стандартизации.

Основное различие заключается в их предназначенной области применения:

X-dynaTrace: Этот заголовок используется исключительно в пределах одной среды Dynatrace. Он обеспечивает сквозное сшивание транзакций между сервисами, мониторируемыми Dynatrace OneAgent. В контексте Dynatrace он имеет более высокий приоритет.
W3C Trace Context: Эти заголовки (traceparent и tracestate) являются частью международного стандарта W3C для распределенной трассировки. Они предназначены для обеспечения интероперабельности между различными инструментами мониторинга и системами. Если вам нужно отслеживать PurePaths из одной среды Dynatrace в другую или интегрироваться с другими инструментами трассировки (например, OpenTelemetry), используются заголовки W3C.

Dynatrace автоматически поддерживает оба стандарта. Это позволяет пользователям получать преимущества от глубокой, детализированной трассировки внутри Dynatrace (с использованием X-dynaTrace) и в то же время обеспечивать совместимость с более широкой экосистемой распределенной трассировки через W3C Trace Context.

Расширенное Использование Заголовков в Dynatrace

Помимо X-dynaTrace: Другие Заголовки и Возможности

Помимо заголовка X-dynaTrace, Dynatrace использует и позволяет настраивать другие HTTP-заголовки для различных целей, таких как безопасность, интеграция и кастомизация мониторинга.

Пользовательские HTTP-заголовки для WebHooks

Dynatrace позволяет настраивать пользовательские HTTP-заголовки для уведомлений о проблемах через WebHooks. Это чрезвычайно полезно для интеграции с внешними системами, которые требуют определенные заголовки для аутентификации (например, Authorization) или для определения типа контента (Content-Type). Эта функция делает интеграцию WebHook более гибкой, позволяя отправлять любой тип полезной нагрузки, а не только JSON.

Custom Dynatrace Problem Notification Integration

Конфигурация пользовательской интеграции уведомлений о проблемах в Dynatrace

Заголовки для Синтетического Мониторинга

При настройке HTTP-мониторов для синтетического мониторинга, Dynatrace позволяет добавлять пользовательские HTTP-заголовки. Это может быть использовано для имитации различных сценариев, таких как автоматизация процесса входа в систему для сайтов, защищенных паролем, путем автоматической генерации заголовка Authorization.

Заголовки Приватности и Конфиденциальности

Dynatrace поддерживает функции приватности данных, включая обработку заголовка DNT (Do Not Track). Если пользователь включает эту функцию в своем браузере, Dynatrace захватывает данные RUM, но исключает всю личную информацию, которая может привести к идентификации пользователя. Кроме того, Dynatrace может маскировать личные данные в URI, строках запроса, заголовках и сообщениях об исключениях, заменяя их на <masked>.

Заголовки `X-dtreferer`, `X-dynatrace-application`, `X-dynatrace-origin-Url`

Эти заголовки также используются Dynatrace для различных внутренних целей мониторинга и корреляции. Например, x-dtreferer может быть связан с проблемами безопасности, так как некоторые брандмауэры могут блокировать его как потенциально вредоносный. X-dynatrace-application и X-dynatrace-origin-Url используются для идентификации приложения и исходного URL в контексте мониторинга реальных пользователей (RUM).

В следующей таблице приведено краткое изложение различных заголовков, используемых или поддерживаемых Dynatrace, с их основным назначением и контекстом применения.

Заголовок	Назначение	Контекст Использования
`X-dynaTrace`	Основной заголовок для сквозной трассировки транзакций (PurePath) внутри одной среды Dynatrace. Обеспечивает корреляцию запросов.	HTTP-запросы (клиент-сервер, сервис-сервис), мобильные приложения, веб-приложения, нагрузочное тестирование.
`traceparent` / `tracestate`	Стандартизированные заголовки W3C Trace Context для распределенной трассировки. Используются для интероперабельности между разными инструментами и средами мониторинга.	HTTP-запросы в мультиоблачных/гетерогенных средах, интеграция с OpenTelemetry.
`X-Dynatrace-Test`	Добавляет контекстную информацию к запросам при нагрузочном тестировании, позволяя Dynatrace связывать результаты тестов.	Инструменты нагрузочного тестирования (JMeter, Gatling).
`Authorization`	Используется для аутентификации запросов. Может быть автоматически сгенерирован Dynatrace для синтетического мониторинга или настроен для WebHooks.	Синтетический мониторинг (для защищенных сайтов), WebHooks для уведомлений о проблемах.
`Content-Type`	Определяет тип содержимого полезной нагрузки запроса. Можно переопределить в Dynatrace для WebHooks.	WebHooks для уведомлений о проблемах (позволяет отправлять не-JSON полезные нагрузки).
`DNT (Do Not Track)`	Индикатор предпочтений пользователя относительно отслеживания. Dynatrace учитывает его для соблюдения конфиденциальности.	Мониторинг реальных пользователей (RUM), соблюдение конфиденциальности.
`X-dtreferer`	Используется для целей мониторинга реальных пользователей (RUM), но может быть заблокирован брандмауэрами.	Веб-приложения (RUM), могут вызывать проблемы с безопасностью.
`X-Dynatrace-Tenant`	Используется Dynatrace для внутренних административных целей, связанных с идентификацией клиента.	Внутренние процессы Dynatrace, синтетический мониторинг.
`X-Dynatrace-Js-Agent` / `X-Oneagent-Js-Injection`	Связаны с инъекцией JavaScript агента в веб-страницы для мониторинга реальных пользователей.	Веб-приложения (RUM), диагностика инъекции JS.

Часто Задаваемые Вопросы (FAQ)

Что такое заголовок X-dynaTrace?

Заголовок X-dynaTrace - это проприетарный HTTP-заголовок, который Dynatrace OneAgent автоматически добавляет к запросам для обеспечения сквозной трассировки транзакций (PurePath) и корреляции данных между различными сервисами и компонентами в вашей распределенной системе.

Почему Dynatrace добавляет этот заголовок?

Dynatrace добавляет заголовок X-dynaTrace для сшивания отдельных фрагментов распределенной транзакции в единую PurePath. Это позволяет платформе отслеживать путь запроса от начала до конца, выявлять зависимости, измерять время отклика каждого компонента и автоматически обнаруживать корневые причины проблем производительности.

Можно ли отключить добавление заголовка X-dynaTrace?

Полное отключение добавления заголовка X-dynaTrace для конкретных запросов без отключения мониторинга всего сервиса является сложной задачей. Настройки "URL-based sampling" могут фильтровать запросы из мониторинга, но не предотвращают добавление заголовка. Если это вызывает проблемы (например, блокировку брандмауэром), рекомендуется настроить сетевые компоненты на разрешение заголовка или связаться с поддержкой Dynatrace.

В чем разница между X-dynaTrace и W3C Trace Context (traceparent, tracestate)?

Заголовок X-dynaTrace используется для трассировки внутри одной среды Dynatrace и имеет более высокий приоритет в этой экосистеме. Заголовки W3C Trace Context (traceparent, tracestate) являются международным стандартом и предназначены для интероперабельности, позволяя отслеживать трассировки между различными инструментами мониторинга и средами. Dynatrace поддерживает оба, но W3C заголовки используются для межсистемной трассировки.

Какие проблемы могут возникнуть с заголовком X-dynaTrace?

Основные проблемы включают блокировку или удаление заголовка брандмауэрами или API-шлюзами, чрезмерное расширение заголовка, приводящее к отклонению запросов (очень редко), и нечитаемый формат заголовка в очередях сообщений, таких как Kafka (поскольку он не предназначен для ручного декодирования).

Заключение

Заголовок X-dynaTrace является фундаментальным компонентом в архитектуре мониторинга Dynatrace, обеспечивая беспрецедентную сквозную видимость и корреляцию транзакций. Благодаря автоматической инъекции OneAgent, этот заголовок позволяет Dynatrace строить подробные PurePaths, выявлять узкие места и диагностировать проблемы в сложных распределенных системах. Понимание его назначения, механизма работы и потенциальных проблем, а также его взаимодействия с такими стандартами, как W3C Trace Context, является ключом к максимально эффективному использованию Dynatrace для обеспечения оптимальной производительности и надежности приложений. Грамотная конфигурация сетевых компонентов и инструментов тестирования для корректной обработки этого заголовка критически важна для поддержания непрерывности трассировки и полноценного использования аналитических возможностей Dynatrace.