Документация Grafana Документация GlaberGraph Источники данных Tempo Настройка Tempo Trace to logs

Настройка корреляции trace to logs

Корреляция trace to logs позволяет переходить от промежутка в Tempo непосредственно к соответствующим журналам в Loki, а от строки журнала в Loki обратно к её трассировке в Tempo. Когда она настроена, в представлении трассировки появляется ссылка Logs for this span, а на строках журнала, содержащих ID трассировки, появляется ссылка на настроенный источник данных трассировки.

Это конфигурация двух источников данных:

• Источник данных Tempo: управляет тем, как Grafana запрашивает журналы, когда вы нажимаете на промежуток, включая временное окно, запрос и сопоставляемые теги.
• Источник данных Loki: управляет тем, как ID трассировок извлекаются из строк журнала и связываются обратно с трассировками.

Обе стороны должны быть настроены, чтобы корреляция работала в любом направлении.

Перед началом

Чтобы настроить корреляцию trace to logs, вам нужно:

• Источник данных Tempo, настроенный в Grafana
• Источник данных Loki, настроенный в Grafana
• Приложения, которые выдают трассировки и журналы с общим идентификатором, таким как ID трассировки, имя службы или оба
• Разрешения Editor или Admin в Grafana

Настройка источника данных Tempo

Эти настройки управляют тем, как Grafana запрашивает ваш источник данных журналов, когда вы нажимаете на промежуток в представлении трассировки. В этом руководстве используется Loki, но Trace to logs также поддерживает Elasticsearch, Splunk, OpenSearch, Falcon LogScale, Google Cloud Logging и VictoriaMetrics Logs.

1. Перейдите в Connections > Data sources и выберите ваш источник данных Tempo.

2. Прокрутите до раздела Trace to logs.

3. Выберите ваш источник данных Loki в раскрывающемся списке Data source.

4. Настройте поля Span start time shift и Span end time shift.

   Эти поля расширяют временное окно запроса журналов вокруг начальной и конечной временных меток промежутка. Временные метки промежутка точны до миллисекунды, но строки журнала часто записываются немного раньше или позже границы промежутка. Значение по умолчанию 0 может не вернуть журналов, если временные метки не совпадают точно. Распространённая отправная точка — -2s для сдвига начала и 2s для сдвига конца.

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

5. Настройте Tags, чтобы сопоставить атрибуты промежутка с именами меток Loki.

   Grafana использует эти теги, чтобы отфильтровать журналы до правильной службы, Pod или кластера. Имя метки Loki, которое вы вводите, должно точно совпадать с именем метки в ваших потоках Loki. Несовпадение молча нарушает корреляцию без отображения ошибки.

   Если вы не настраиваете никаких тегов, Grafana использует следующие значения по умолчанию: cluster, hostname, namespace, pod, service.name (переопределяется в service_name) и service.namespace (переопределяется в service_namespace). Автоматическое переопределение точек в подчёркивания применяется только к этим тегам по умолчанию. Для пользовательских тегов вы должны указать переопределённое имя явно.

   Чтобы настроить сопоставление, используйте кнопку Add tag, чтобы добавить каждую строку. Следующая таблица показывает распространённые теги и их типичные эквиваленты меток Loki:

   Expand table

   Атрибут промежутка	Метка Loki
   service.name	service_name
   service.namespace	service_namespace
   cluster	cluster
   namespace	namespace
   pod	pod
   hostname	hostname

   Выбирайте метки с низкой кардинальностью. В Loki каждая уникальная комбинация значений меток создаёт отдельный поток. Метки, принимающие множество различных значений, такие как pod, host, thread, duration, traceId или spanId, могут создавать сотни тысяч или даже миллионы потоков, вызывая медленные запросы, высокое использование памяти и потерю журналов при приёме. Метки, перечисленные выше (service_name, namespace, cluster), являются хорошим выбором, потому что они имеют ограниченный, небольшой набор значений. Если вам нужно запрашивать значения с высокой кардинальностью, такие как ID трассировок или имена Pod, храните их как структурированные метаданные вместо этого. Их можно запрашивать без создания дополнительных потоков. Дополнительную информацию см. в разделе Кардинальность.

   Note

   При использовании Loki ссылка Logs for this span появляется на промежутке только в том случае, если хотя бы один из настроенных тегов существует на этом промежутке. Если ни один из тегов не совпадает, ссылка не появляется, и ошибка не отображается.

6. Настройте переключатели Filter by trace ID и Filter by span ID.

   • Filter by trace ID: фильтрует результаты Loki до всех журналов для всей трассировки, а не только выбранного промежутка. Это хорошо работает для большинства случаев использования.
   • Filter by span ID: фильтрует до журналов для одного промежутка. Это работает только в том случае, если в ваших журналах есть поле ID промежутка.

   Эти переключатели отключены, когда включена опция Use custom query, потому что пользовательский запрос управляет фильтрацией напрямую.

   Нажатие Logs for this span фильтрует по ID трассировки, а не по ID промежутка, поэтому результаты включают все журналы для всей трассировки, содержащие совпадающий ID трассировки, а не только журналы, выданные во время этого конкретного промежутка. Если ваши результаты выглядят шире, чем ожидалось, это ожидаемое поведение. Чтобы сузить результаты до активности конкретного промежутка, напишите пользовательский запрос LogQL, который фильтрует по ID промежутка или специфичным для промежутка атрибутам, если ваше приложение их записывает, например {service_name="my-service"} | json | spanId="". Чтобы эта функция работала вообще, ваше приложение должно внедрять ID трассировок в строки журнала, например, используя структурированное журналирование OpenTelemetry SDK. Без ID трассировок в журналах запрос возвращается к фильтру по диапазону времени.

7. Необязательно: включите Use custom query и напишите выражение LogQL, чтобы заменить автоматически сгенерированный запрос.

   Используйте ${__tags}, чтобы автоматически внедрить сопоставленные фильтры тегов:

   logql Copy

   {${__tags}} | logfmt | trace_id=`${__trace.traceId}`

   Если такой тег, как pod, хранится как структурированные метаданные Loki, а не как индексированная метка, он не может появиться в селекторе потока {}. Переместите его в фильтр конвейера вместо этого:

   logql Copy

   {${__tags}} | pod=`${__span.tags["k8s.pod.name"]}` |= `${__trace.traceId}`

   Полный список доступных переменных см. в разделе Пользовательские переменные запросов.

8. Нажмите Save & test.

Настройка источника данных Loki

Эти настройки включают ссылку Tempo на строках журнала Loki, позволяя переходить от записи журнала к её трассировке.

1. Перейдите в Connections > Data sources и выберите ваш источник данных Loki.

2. В разделе Additional settings прокрутите до Derived fields.

3. Нажмите Add, чтобы добавить новое производное поле.

4. Введите Name для поля, например TraceID.

5. Выберите Type и введите шаблон для извлечения ID трассировки из строк журнала.

   Если вы выберете Regex in log line, введите регулярное выражение с одной группой захвата. Следующая таблица показывает распространённые шаблоны:

   Expand table

   Формат журнала	Регулярное выражение
   traceID=<VALUE>	traceID=(\w+)
   trace_id=<VALUE>	trace_id=(\w+)
   Поле JSON "traceId": "<VALUE>"	"traceId":"(\w+)"

   Если вы выберете Label, введите регулярное выражение, соответствующее ключу метки, например trace[_]?id, чтобы соответствовать как traceid, так и trace_id.

   Tip

   Если ваши приложения используют разные имена полей ID трассировки, вам нужна отдельная запись производного поля для каждого формата. Чтобы упростить это, стандартизируйте структурированные метаданные OpenTelemetry, чтобы ID трассировок хранились как согласованная метка.

6. Включите переключатель Internal link и выберите ваш источник данных Tempo в раскрывающемся списке.

7. В поле Query введите ${__value.raw}.

   Это передаёт извлечённый ID трассировки в Tempo при нажатии на ссылку. Поле показывает ${__value.raw} как текст-заполнитель, но вы должны ввести его как фактическое значение.

8. Нажмите Save & test.

Дополнительные сведения о параметрах производных полей см. в разделе Производные поля в документации источника данных Loki.

Провижининг настроек trace to logs

Вы можете провижинить конфигурацию trace to logs, используя блок tracesToLogsV2 в вашем файле YAML источника данных. Полный пример YAML провижининга, включающий все настройки Tempo, см. в разделе Провижининг источника данных Tempo. Общие инструкции по провижинингу см. в разделе Провижининг источников данных.

Пример: служба NGINX

Этот пример предполагает:

• Приложения, работающие в Kubernetes, которые выдают трассировки OpenTelemetry в Tempo
• Журналы, отправленные в Loki с метками service_name, namespace и pod
• ID трассировок, записанные в журналы как trace_id=<VALUE>

Настройки источника данных Tempo:

Настройки производного поля источника данных Loki:

Ожидаемый результат

После настройки обоих источников данных:

• В Explore с выбранным источником данных Tempo нажмите на любой промежуток, а затем нажмите Logs for this span. Loki открывается с фильтром по service_name=nginx и namespace=production в пределах настроенного временного окна вокруг промежутка.
• В Explore с выбранным источником данных Loki любая строка журнала, содержащая trace_id=..., показывает ссылку на ваш источник данных Tempo. Нажатие на неё открывает полную трассировку в Tempo.

Устранение неполадок

Если ссылки trace to logs не появляются, не возвращают данных или работают только для некоторых служб, см. Проблемы trace to logs/metrics/profiles в руководстве по устранению неполадок.

Если поля конфигурации неактивны, ваш источник данных провижинен. О параметрах см. раздел Провижининг настроек trace to logs.

Дальнейшие шаги

• Настройка корреляции trace to metrics: связывайте промежутки с запросами метрик в Prometheus.
• Настройка корреляции trace to profiles: связывайте промежутки с данными профилирования в Grafana Pyroscope.
• Настройка источника данных Tempo: вернуться к настройкам подключения, аутентификации и потоковой передачи.