#Корреляция логов приложения с trace

Когда OpenTelemetry Java agent инструментаризует ваше приложение, он может автоматически добавлять активный контекст trace — trace_id, span_id и trace_flags — в контекст логирования вашего приложения (MDC). Выводя эти значения в логах, вы можете напрямую перейти от строки лога к соответствующему trace, а затем — от trace обратно к логам, которые сгенерировал запрос.

На этой странице объясняется, как вывести контекст trace в логах для приложений Java.

#Как это работает

Java agent поставляется с инструментированием логирования, которое копирует текущий контекст span в MDC (Mapped Diagnostic Context) вашей библиотеки логирования. Вам не нужно разбирать HTTP-заголовки или писать какой-либо код для этого — агент извлекает контекст из заголовков распространения и автоматически заполняет MDC. Внедряемые ключи:

Эти ключи используют формат snake_case и являются встроенными значениями агента по умолчанию. Внедрение включено по умолчанию, поэтому все, что вам нужно сделать, — сослаться на эти ключи в шаблоне вывода логов.

Инструментирование соответствует вашей библиотеке логирования:

Если вам когда-либо понадобится отключить конкретное внедрение (или снова включить его), задайте соответствующее свойство или переменную среды для workload. По умолчанию каждый из этих параметров имеет значение true:

#Вывод ID в логах

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

2026-06-12 10:15:42.123 trace_id=4bf92f3577b34da6a3ce929d0e0e4736 span_id=00f067aa0ba902b7 trace_flags=01 INFO  ProviderController - request /hello

#Spring Boot

Для приложения Spring Boot самый простой способ — переопределить logging.pattern.level, чтобы ID добавлялись в начало каждой строки лога без переписывания всего шаблона:

logging.pattern.level = trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p

#Logback

Если вы управляете собственным logback.xml или logback-spring.xml, ссылайтесь на ключи через %X{...} (что в Logback эквивалентно %mdc{...}) внутри шаблона:

<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
  <encoder>
    <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} trace_id=%X{trace_id} span_id=%X{span_id} trace_flags=%X{trace_flags} %-5level %logger{36} - %msg%n</pattern>
  </encoder>
</appender>

Для приложений, которые используют стандартный консольный appender Spring Boot, вместо этого можно переопределить свойство CONSOLE_LOG_PATTERN, внедрив в шаблон те же токены %X{trace_id}.

#Log4j 2

Для Log4j 2 ссылайтесь на ключи через %X{...} в PatternLayout:

<Console name="Console" target="SYSTEM_OUT">
  <PatternLayout
    pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} trace_id=%X{trace_id} span_id=%X{span_id} trace_flags=%X{trace_flags} %-5p %c{1} - %m%n"/>
</Console>

#Ключи OpenTelemetry agent против встроенной корреляции Spring Boot / Micrometer

#Экспорт логов через OTLP

Приведенные выше шаблоны предназначены для текстовых логов (консоль или файл), которые читаются или собираются как текст. Если же вы экспортируете логи напрямую через OTLP, trace_id и span_id передаются в выделенных полях записи лога OTLP, а не как атрибуты MDC, поэтому экспортированные через OTLP логи остаются коррелированными без добавления ID в шаблон лога.

#Другие языки

Другие языки OpenTelemetry также связывают логи с trace в режиме zero-code (auto-instrumentation), но имена внедряемых полей и способ их включения различаются в зависимости от языка. Обратитесь к рекомендациям для используемого языка:

#Ссылки

• Автоинструментирование Logger MDC — авторитетный список внедряемых ключей и поддерживаемых библиотек логирования.
• README по инструментированию Logback MDC — примеры шаблонов и параметры конфигурации.
• Конфигурация Java agent и отключение конкретного инструментирования — как включать и отключать отдельные инструментирования.