Документацияbreadcrumb arrow Grafanabreadcrumb arrow Документация GlaberGraphbreadcrumb arrow Источники данныхbreadcrumb arrow Tempobreadcrumb arrow Устранение неполадок

Устранение неполадок источника данных Tempo

В этом документе приведены решения распространённых проблем, с которыми вы можете столкнуться при настройке или использовании источника данных Tempo в Grafana.

Область применения этого руководства

Это руководство охватывает проблемы, связанные с подключением Grafana к Tempo и использованием функций источника данных. Оно применимо к следующим конфигурациям:

  • Самостоятельно размещённая Grafana + самостоятельно размещённый Tempo — вы управляете как Grafana (OSS или Enterprise), так и Tempo.
  • Grafana Cloud + Cloud Traces — вы используете Grafana Cloud с управляемым бэкендом Tempo (Grafana Cloud Traces). Некоторые конфигурации (потоковая передача, генератор метрик) обрабатываются автоматически.
  • Grafana Cloud + самостоятельно размещённый Tempo через PDC — вы используете Grafana Cloud, но подключаетесь к собственному экземпляру Tempo через Private data source connect.

Там, где шаги по устранению неполадок различаются между этими конфигурациями, руководство указывает это. Разделы, помеченные Grafana Cloud only или self-managed Tempo, применяются только к этим средам.

Ресурсы для устранения неполадок Tempo

По проблемам с самим Tempo (а не с источником данных) обратитесь к документации продукта Tempo:

Ресурсы для устранения неполадок трассировки в Grafana Cloud

Дополнительные ресурсы для Grafana Cloud:

Ошибки подключения

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

Не удалось подключиться к Tempo

Сообщение об ошибке: Failed to connect to Tempo или dial tcp: connection refused

Причина: Grafana не может достичь экземпляра Tempo. Обычно это означает, что процесс Tempo не запущен, URL в настройках источника данных неверен или правило сетевого уровня блокирует подключение.

Решение:

  1. Убедитесь, что экземпляр Tempo запущен и доступен с сервера Grafana.
  2. Проверьте, что URL верен в конфигурации источника данных. HTTP-порт Tempo по умолчанию — 3200. Распространённые ошибки в URL включают:
    • Добавление завершающих сегментов пути, например /api или /tempo, к URL самостоятельно размещённого Tempo. Правильный формат — http://<HOST>:3200 без пути. Суффикс /tempo используется только для URL Grafana Cloud Traces.
    • Использование gRPC-порта (9095) вместо HTTP-порта (3200). URL источника данных Tempo должен быть HTTP-конечной точкой. Grafana выводит gRPC-соединение для потоковой передачи из того же URL.
    • Примеры формата URL по средам см. в разделе Подключение.
  3. Убедитесь, что нет правил брандмауэра, блокирующих подключение между Grafana и Tempo.
  4. Пользователям Grafana Cloud, подключающимся к самостоятельно размещённому экземпляру Tempo, убедитесь, что вы настроили Private data source connect, если Tempo не является общедоступным.
  5. Убедитесь, что протокол (HTTP или HTTPS) соответствует вашей конфигурации Tempo.

Тайм-аут подключения

Сообщение об ошибке: Connection timed out или context deadline exceeded

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

Решение:

  1. Проверьте сетевую задержку между Grafana и Tempo.
  2. Убедитесь, что Tempo не перегружен и не испытывает проблем с производительностью. Если у вас установлены дашборды Tempo mixin, проверьте их на предмет насыщения ресурсов или повышенных частот ошибок.
  3. Увеличьте настройку Timeout в конфигурации источника данных в разделе Additional settings.
  4. Проверьте, не истекает ли по тайм-ауту подключение на каких-либо сетевых устройствах (балансировщиках нагрузки, прокси).
  5. Для больших запросов трассировок рассмотрите возможность уменьшения диапазона времени или добавления более конкретных фильтров.

Сбои подключения TLS/SSL

Сообщение об ошибке: TLS handshake failed или x509: certificate signed by unknown authority

Причина: Есть несоответствие между настройками TLS в Grafana и тем, что поддерживает или требует экземпляр Tempo. Например, Tempo может представить самоподписанный сертификат, которому сервер Grafana доверяет, или имя хоста в сертификате не совпадает с URL.

Решение:

  1. Убедитесь, что у Tempo есть действительный TLS-сертификат, если включён HTTPS.
  2. Проверьте, что сертификат доверен сервером Grafana.
  3. Если используется самоподписанный сертификат, настройте TLS/SSL Auth Details в настройках источника данных.
  4. Убедитесь, что Common Name (CN) или Subject Alternative Name (SAN) сертификата соответствует имени хоста, используемому в URL.

Дополнительную информацию о настройке шифрования TLS с Tempo см. в разделе Настройка связи TLS.

Ошибки аутентификации

Эти ошибки возникают при проблемах с учётными данными или разрешениями.

Аутентификация не удалась

Сообщение об ошибке: 401 Unauthorized или 403 Forbidden

Причина: Учётные данные аутентификации недействительны или у пользователя нет разрешения на доступ к Tempo. Эта ошибка появляется, когда вы выбираете Save & test или при выполнении запроса.

Решение:

  1. Убедитесь, что учётные данные аутентификации (имя пользователя/пароль или API-ключ) верны в настройках источника данных.
  2. Проверьте, что у пользователя или сервисной учётной записи есть требуемые разрешения.
  3. Убедитесь, что выбранный в источнике данных метод аутентификации соответствует тому, что ожидает Tempo.
  4. Для Grafana Cloud убедитесь, что ваш токен Cloud Access Policy имеет область действия traces:read. Инструкции по настройке см. в разделе Создание токена Cloud Access Policy. Чтобы найти URL вашего стека и учётные данные, см. Поиск URL, пользователя и пароля вашего стека.
  5. Для самостоятельно размещённого Tempo убедитесь, что учётные данные соответствуют настроенным в блоке server Tempo или обратном прокси.

Save and test возвращает 404

Сообщение об ошибке: Tempo echo endpoint returned status 404 при выборе Save & test

Причина: Проверка работоспособности Grafana достигает сервера, но конечная точка api/echo возвращает 404. Наиболее распространённая причина — неверные сегменты пути в URL (такие как /api или /tempo на самостоятельно размещённом экземпляре), которые смещают запрос проверки работоспособности на несуществующий путь. 404 также может возникнуть, когда обратный прокси перед Tempo отклоняет запросы, содержащие неожиданные заголовки базовой аутентификации.

Решение:

  1. Убедитесь, что URL не включает завершающих сегментов пути. Для самостоятельно размещённого Tempo URL должен быть http://<HOST>:3200 без пути. Правильный формат см. в разделе Подключение.
  2. Если между Grafana и Tempo находится обратный прокси, проверьте, не возвращает ли 404 прокси. Сам Tempo игнорирует неожиданные заголовки аутентификации, но прокси может их отклонить.
  3. Если Tempo не требует аутентификации, выберите No authentication в настройках источника данных.
  4. Проверьте, что учётные данные аутентификации введены в правильные поля. Для Grafana Cloud поле User — это ID экземпляра (не ваш логин Grafana), а Password — токен Cloud Access Policy.

Проблемы мультиарендной аутентификации

Сообщение об ошибке: Unauthorized при использовании мультиарендного Tempo

Причина: ID арендатора (заголовок X-Scope-OrgID) отсутствует или неверен. Этот заголовок должен быть задан как на пути записи (в конфигурации вашего Alloy или OpenTelemetry Collector), так и на пути чтения (в настройках источника данных Grafana), чтобы маршрутизировать данные к правильному арендатору.

Решение:

  1. В настройках источника данных Tempo убедитесь, что заголовок X-Scope-OrgID настроен в разделе Authentication > HTTP Headers. Шаги настройки источника данных см. в разделе Мультиарендность.
  2. На пути записи убедитесь, что тот же заголовок X-Scope-OrgID задан в конфигурации вашего Alloy или OpenTelemetry Collector, чтобы трассировки принимались под правильным арендатором.
  3. Проверьте, что у аутентифицированного пользователя есть доступ к указанному арендатору.
  4. Для кросс-арендных запросов убедитесь, что все указанные арендаторы доступны.

Дополнительную информацию см. в разделах Включение мультиарендности и ID арендаторов.

Ошибки запросов

Эти ошибки возникают при проблемах с запросами TraceQL или поиском трассировок.

Трассировка не найдена

Сообщение об ошибке: Trace not found или trace ID not found

Причина: Указанный ID трассировки не существует в Tempo или вышел за пределы настроенного периода хранения. Распространённые причины включают:

  • Выборка (Sampling): головная или хвостовая выборка в вашем конвейере инструментирования (Alloy, OpenTelemetry Collector) могла отбросить трассировку до того, как она достигла Tempo. Это самая распространённая причина отсутствующих трассировок.
  • Хранение: трассировки доступны только в течение срока, установленного в конфигурации хранения Tempo. Для пользователей Grafana Cloud применяются периоды хранения по умолчанию, если вы не свяжетесь с поддержкой для их изменения.
  • Сбой приёма: трассировка могла не быть успешно принята из-за лимитов частоты, ошибок или неправильно настроенных конвейеров.

Решение:

  1. Убедитесь, что ID трассировки верен и полон.

  2. Проверьте конфигурацию выборки в Alloy или OpenTelemetry Collector. Если включена головная или хвостовая выборка, трассировка могла быть намеренно отброшена. Рекомендации см. в разделе Стратегии выборки.

  3. Проверьте, что трассировка находится в пределах настроенного периода хранения Tempo.

  4. Если используются ограничения диапазона времени, расширьте диапазон времени в настройках TraceID query.

  5. Включите Use time range in query в настройках TraceID query и настройте значения временного сдвига, чтобы искать в более широком диапазоне.

  6. Убедитесь, что трассировка была успешно принята Tempo. Вы можете выполнить широкий запрос, чтобы проверить наличие недавних трассировок:

    traceql 
    { } | count() > 0

    Если это возвращает результаты, трассировки принимаются, но ваш конкретный ID трассировки мог быть отброшен выборкой или выйти из срока хранения. Дополнительные примеры запросов см. в TraceQL cookbook.

  7. Пользователям Grafana Cloud см. Устранение неполадок TraceQL и поиска на предмет запросов TraceQL, которые могут помочь исследовать отсутствующие трассировки.

Синтаксические ошибки TraceQL

Сообщение об ошибке: parse error или unexpected token

Причина: Запрос TraceQL содержит синтаксические ошибки.

Решение:

  1. Убедитесь, что запрос следует синтаксису TraceQL.
  2. Проверьте, что все фигурные скобки, круглые скобки и кавычки сбалансированы.
  3. Убедитесь, что имена атрибутов правильно отформатированы с правильной областью. Используйте точечную нотацию для атрибутов промежутка или ресурса, например span.http.status_code или resource.service.name.
  4. Используйте конструктор запросов Search, чтобы генерировать допустимые запросы TraceQL, если вы не знакомы с синтаксисом.
  5. Убедитесь, что операторы используются правильно. Поддерживаемые операторы включают =, !=, =~, !~, >, <, >=, <=.

Запрос не возвращает результатов

Причина: Запрос допустим, но не соответствует ни одной трассировке.

Решение:

  1. Расширьте диапазон времени, чтобы искать в более широком периоде.
  2. Убедитесь, что имена и значения атрибутов существуют в ваших трассировках.
  3. Проверьте, что имена атрибутов совпадают точно, так как они чувствительны к регистру.
  4. Используйте конструктор запросов Search, чтобы исследовать доступные атрибуты и значения.
  5. Начните с более широкого запроса и постепенно добавляйте фильтры, чтобы сузить результаты.
  6. Попробуйте Grafana Traces Drilldown, приложение без запросов, которое позволяет исследовать данные трассировки с помощью метрик RED без написания TraceQL.
  7. Учтите, что поиск Tempo недетерминирован — идентичные запросы могут возвращать разные результаты, потому что Tempo сканирует параллельно и возвращает первые совпадающие трассировки. Подробности см. в разделе Понимание поведения поиска.
  8. Убедитесь, что трассировки принимаются в Tempo, запросив известный ID трассировки.

Трассировки не появляются после успешного подключения

Причина: Save & test проходит успешно, но выполнение запросов в Explore не возвращает трассировок. Подключение источника данных действительно, но никакие данные трассировки не достигают Tempo, или запросы не соответствуют никаким принятым данным.

Решение:

  1. Убедитесь, что ваши приложения инструментированы и что ваш коллектор (Alloy, OpenTelemetry Collector) пересылает промежутки в Tempo. Проверьте журналы коллектора на предмет ошибок отправки, отклонённых промежутков или потерь.
  2. Пользователям Grafana Cloud, которые отправляют трассировки с помощью Alloy, см. Устранение неполадок отправки трассировок с помощью Alloy на предмет проблем на стороне приёма.
  3. Убедитесь, что диапазон времени запроса охватывает период, когда трассировки были сгенерированы. Данные трассировки появляются только для окна, в котором промежутки были приняты.
  4. Для мультиарендных настроек убедитесь, что заголовок X-Scope-OrgID одинаков как на пути записи (коллектор), так и на пути чтения (источник данных Grafana). Несовпадение приводит к тому, что трассировки принимаются под одним арендатором, а запрашиваются под другим.
  5. Попробуйте широкий запрос, например {}, с коротким недавним диапазоном времени, чтобы подтвердить, что какие-либо трассировки существуют в Tempo. Если это возвращает результаты, фильтры вашего исходного запроса слишком узки.

Тайм-аут запроса

Сообщение об ошибке: context deadline exceeded или query timeout

Причина: Запрос выполнялся слишком долго. Поиск трассировок сканирует необработанные данные трассировки за выбранный диапазон времени, поэтому широкие запросы за длительные периоды могут превысить лимиты тайм-аута.

Решение:

  1. Уменьшите диапазон времени, чтобы ограничить объём сканируемых данных.
  2. Добавьте более конкретные фильтры, чтобы сузить область поиска.
  3. По возможности используйте индексированные атрибуты в ваших запросах для более быстрого поиска.
  4. Для самостоятельно размещённого Tempo увеличьте тайм-аут запроса в конфигурации сервера Tempo, если это уместно.
  5. Если вам нужны агрегированные данные (частоты, количества, длительности), а не отдельные трассировки, рассмотрите использование запросов метрик TraceQL (например, { } | rate()) или предварительно вычисленных метрик из генератора метрик, которые оптимизированы для агрегированных рабочих нагрузок.

Запрос метрик TraceQL не удаётся

Сообщение об ошибке: localblocks processor not found или metrics-generator not configured

Причина: Запросы метрик TraceQL (такие как { } | rate() или { } | count_over_time()) требуют, чтобы процессор local-blocks был активен в конфигурации генератора метрик Tempo. Этот процессор отделён от процессоров service-graphs и span-metrics и должен быть включён независимо.

Решение:

  1. Для самостоятельно размещённого Tempo активируйте процессор local-blocks в конфигурации overrides. Путь конфигурации зависит от вашей версии Tempo и метода развёртывания:

    • Стандартный: overrides.metrics_generator_processors: ["local-blocks"]
    • Более новые версии и Helm: overrides.defaults.metrics_generator.processors: [local-blocks]

    Шаги настройки и требуемую конфигурацию см. в разделе Настройка метрик TraceQL.

  2. Для Grafana Cloud процессор local-blocks включён по умолчанию. Если вы всё ещё видите эту ошибку, свяжитесь с поддержкой Grafana.

  3. Убедитесь, что генератор метрик запущен и работоспособен, проверив журналы генератора метрик Tempo на предмет ошибок.

Проблемы с потоковой передачей

Потоковая передача отображает результаты запросов TraceQL по мере их появления. Без потоковой передачи вы не видите результаты, пока запрос не завершится. Потоковая передача доступна пользователям Grafana Cloud по умолчанию. Для самостоятельно размещённого Tempo потоковая передача поиска требует Tempo v2.2 или более поздней версии, а потоковая передача метрик требует Tempo v2.7 или более поздней версии. Обе требуют stream_over_http_enabled: true в конфигурации Tempo.

Дополнительную информацию см. в разделе Потоковая передача.

Потоковая передача не работает

Причина: Результаты не появляются постепенно и отображаются только после завершения всего запроса.

Решение:

  1. Для самостоятельно размещённого Tempo убедитесь, что вы используете требуемую версию Tempo (v2.2 или более позднюю для потоковой передачи поиска, v2.7 или более позднюю для потоковой передачи метрик) и что потоковая передача включена в вашей конфигурации (stream_over_http_enabled: true). Обратитесь к разделу gRPC API Tempo в документации Tempo. Потоковая передача доступна пользователям Grafana Cloud по умолчанию.
  2. Убедитесь, что Streaming включена в ваших настройках источника данных Tempo. Переключатели Search queries и Metrics queries независимы — проверьте, что переключатель для используемого вами типа запроса включён.
  3. Если ваш экземпляр Tempo находится за балансировщиком нагрузки или прокси, который не поддерживает gRPC или HTTP2, потоковая передача может не работать. Отключите потоковую передачу и используйте стандартные HTTP-запросы вместо этого.
  4. Если вы используете Private data source connect (PDC) для доступа к Tempo, убедитесь, что туннель PDC работает и экземпляр Tempo доступен с агента PDC. Проблемы связности PDC могут проявляться как тайм-ауты потоковой передачи.

Ошибка безопасности транспорта gRPC

Сообщение об ошибке: rpc error: code = Unavailable desc = credentials require transport level security

Причина: Grafana пытается использовать gRPC через незащищённое (не-TLS) соединение. Потоковая передача использует gRPC, который может требовать TLS в зависимости от вашей конфигурации Tempo.

Решение:

  1. Настройте TLS между Grafana и Tempo. Обратитесь к разделу Настройка связи TLS.
  2. Если TLS не вариант, отключите потоковую передачу в настройках источника данных Tempo и используйте стандартные HTTP-запросы вместо этого.

Частичные результаты или ошибки потоковой передачи

Сообщение об ошибке: stream error или неполные результаты во время потоковой передачи

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

Решение:

  1. Проверьте стабильность сети между браузером и Grafana.
  2. Убедитесь, что прокси или балансировщики нагрузки не разрывают долгоживущие соединения.
  3. Отключите потоковую передачу и используйте стандартные запросы, если проблемы сохраняются.
  4. Проверьте журналы сервера Tempo на предмет любых ошибок, связанных с потоковой передачей.

Проблемы с графом служб

Service Graph визуализирует зависимости служб и выделяет частоту запросов, частоту ошибок и длительность (метрики RED) по соединениям. Он требует связанного источника данных Prometheus с метриками графа служб, сгенерированными генератором метрик Tempo или Grafana Alloy. Дополнительную информацию см. в разделе Service Graph и представление Service Graph.

Граф служб не отображается

Причина: Представление Service Graph не показывает данных или показывает пустой граф.

Решение:

  1. Убедитесь, что источник данных Prometheus связан в настройках Service Graph источника данных Tempo в разделе Additional settings.

  2. Для самостоятельно размещённого Tempo проверьте, что генератор метрик настроен на создание метрик графа служб. Обратитесь к разделу Метрики графа служб в документации Tempo.

  3. Убедитесь, что следующие метрики графа служб существуют в Prometheus:

    • traces_service_graph_request_total
    • traces_service_graph_request_failed_total
    • traces_service_graph_request_server_seconds_sum

  4. Убедитесь, что Grafana Alloy или генератор метрик Tempo настроены на создание этих метрик. Они отличаются от метрик промежутков (traces_spanmetrics_*), которые питают таблицу представления Service Graph.

  5. Чтобы проверить, что метрики существуют, выполните следующий запрос в Explore с выбранным источником данных Prometheus:

    promql 
    {__name__=~"traces_service_graph_request.*"}

  6. Проверьте, что подключение источника данных Prometheus работает.

  7. Пользователям Grafana Cloud Traces см. Устранение неполадок графа служб и метрик RED.

Таблица представления Service Graph пуста

Причина: Граф узлов Service Graph отрисовывается правильно, но таблица метрик RED рядом с ним не показывает данных.

Решение:

  1. Таблица представления Service Graph использует другой набор метрик, чем граф узлов. Фронтенд Grafana запрашивает traces_spanmetrics_calls_total и traces_spanmetrics_latency_bucket. Подтвердите, что эти метрики существуют в вашем связанном источнике данных Prometheus. Более новые версии Tempo могут создавать traces_spanmetrics_duration_seconds_bucket вместо traces_spanmetrics_latency_bucket. Если у вас есть только более новое имя метрики, столбец длительности не показывает данных, пока фронтенд Grafana не поддержит переименованную метрику.
  2. Убедитесь, что генерация метрик промежутков включена в конфигурации вашего Tempo или Alloy. Обратитесь к разделу Включение графов служб в документации Tempo.

Предупреждения о высокой кардинальности

Причина: Запросы графа служб или метрик промежутков создают предупреждения о высокой кардинальности или медленные запросы.

Решение:

  1. Изучите кардинальность меток ваших метрик графа служб и промежутков. Метки с высокой кардинальностью (такие как уникальные имена Pod или ID запросов) создают множество временных рядов и ухудшают производительность запросов.
  2. Обратитесь к разделу Кардинальность в документации Tempo за руководством по управлению кардинальностью меток.

Граф служб показывает неполные данные

Причина: Некоторые службы или соединения отсутствуют на графе.

Решение:

  1. Убедитесь, что все службы инструментированы и отправляют промежутки.
  2. Проверьте, что имена промежутков и имена служб согласованы.
  3. Убедитесь, что диапазон времени включает данные от всех ожидаемых служб.
  4. Убедитесь, что в источнике данных Prometheus есть метрики для всех служб.

Проблемы trace to logs/metrics/profiles

Эти проблемы связаны с функциями корреляции, которые связывают трассировки с другими телеметрическими сигналами. Подробности конфигурации см. в разделах Trace to logs, Trace to metrics и Trace to profiles.

Причина: Ссылки на журналы не появляются при просмотре трассировки.

Решение:

  1. Убедитесь, что источник данных Loki или другой источник данных журналов настроен в настройках Trace to logs.
  2. Проверьте, что настроенные теги существуют в ваших промежутках.
  3. Убедитесь, что хотя бы один сопоставленный тег имеет непустое значение в промежутке.
  4. При использовании пользовательского запроса убедитесь, что синтаксис запроса допустим для целевого источника данных.
  5. Проверьте, что Filter by trace ID или Filter by span ID не включены при использовании пользовательского запроса.
  6. При использовании Filter by trace ID с производными полями Loki убедитесь, что регулярное выражение производного поля соответствует имени поля ID трассировки, используемому в ваших журналах. Разные библиотеки инструментирования используют разные имена полей (traceID, trace_id или traceId). Распространённые шаблоны регулярных выражений по формату инструментирования см. в разделе Trace to logs.

Причина: Обратное направление — переход от строки журнала Loki к трассировке — не работает. На строках журнала не появляется ссылка на трассировку.

Решение:

  1. Убедитесь, что производное поле настроено в источнике данных Loki в разделе Additional settings > Derived fields. Производное поле извлекает ID трассировки из строк журнала и создаёт ссылку на Tempo.
  2. Проверьте, что регулярное выражение производного поля соответствует формату ID трассировки в ваших журналах. Используйте Show example log message в настройках производного поля, чтобы протестировать регулярное выражение на образце строки журнала.
  3. Убедитесь, что переключатель Internal link включён и указывает на правильный источник данных Tempo.
  4. Если разные службы используют разные имена полей ID трассировки, вам нужна отдельная запись производного поля для каждого формата. Шаблоны регулярных выражений по формату см. в разделе Trace to logs.

Причина: Ссылки на метрики не появляются при просмотре трассировки.

Решение:

  1. Убедитесь, что источник данных Prometheus или другой источник данных метрик настроен в настройках Trace to metrics.
  2. Проверьте, что настроенные теги существуют в ваших промежутках.
  3. При использовании пользовательских запросов убедитесь, что они являются допустимым PromQL.
  4. Убедитесь, что переменная $__tags правильно размещена в пользовательских запросах.

Причина: Ссылки на данные профилирования не появляются при просмотре трассировки.

Решение:

  1. Убедитесь, что источник данных Grafana Pyroscope настроен в настройках Trace to profiles.
  2. Проверьте, что настроенные теги существуют в ваших промежутках.
  3. Убедитесь, что настроенный тип профиля соответствует тому, для которого у Pyroscope есть данные (например, process_cpu:cpu:nanoseconds:cpu:nanoseconds). Несоответствие между настроенным типом профиля и доступными данными приводит к тому, что ссылка не появляется.
  4. Сузьте значения Span start time shift и Span end time shift. Профили выбираются через интервалы, поэтому узкое временное окно вокруг промежутка с большей вероятностью совпадёт с данными профиля, чем широкое.
  5. Убедитесь, что источник данных профилирования подключён и возвращает данные.

Причина: Сгенерированный запрос не соответствует никаким данным в целевом источнике данных.

Решение:

  1. Настройте Span start time shift и Span end time shift, чтобы расширить диапазон времени.
  2. Убедитесь, что метки журналов или метрик соответствуют атрибутам промежутка.
  3. Проверьте, что сопоставления тегов правильно транслируют имена атрибутов между источниками данных. Атрибуты промежутка используют точки (например, service.name), но метки Loki используют подчёркивания (например, service_name). Убедитесь, что сопоставления тегов учитывают это различие. Конфигурацию сопоставления тегов см. в разделе Trace to logs.
  4. Если такой тег, как pod, хранится как структурированные метаданные Loki, а не как индексированная метка, автоматически сгенерированный селектор потока {pod="..."} возвращает пустые результаты. Включите Use custom query и переместите тег в фильтр конвейера. Пример пользовательского запроса см. в разделе Trace to logs.
  5. Выполните сгенерированный запрос напрямую в представлении Explore целевого источника данных, чтобы подтвердить, что он возвращает данные вне контекста трассировки.
  6. Используйте Query Inspector, чтобы просмотреть сгенерированный запрос и убедиться, что он верен.

Проблемы производительности

Эти проблемы связаны с медленными запросами или высоким потреблением ресурсов.

Медленные запросы трассировок

Причина: Запросы возвращают результаты долго.

Решение:

  1. Уменьшите диапазон времени дашборда или Explore.
  2. Добавьте более конкретные фильтры, чтобы сузить область поиска.
  3. По возможности используйте индексированные атрибуты в запросах TraceQL.
  4. Включите потоковую передачу, чтобы видеть результаты по мере их появления.
  5. Рассмотрите использование конструктора запросов Search, который может помочь оптимизировать запросы.

Высокое использование памяти во время запросов

Причина: Большие трассировки или наборы результатов потребляют чрезмерное количество памяти.

Решение:

  1. Уменьшите настройку Limit в параметрах запроса, чтобы возвращать меньше трассировок.
  2. Уменьшите настройку Span Limit, чтобы возвращать меньше промежутков на трассировку.
  3. Добавьте фильтры, чтобы уменьшить размер набора результатов.
  4. Избегайте запросов за очень большие диапазоны времени.

Другие распространённые проблемы

Следующие проблемы не выдают конкретных сообщений об ошибках, но встречаются часто.

Граф узлов не отображается

Причина: Визуализация графа узлов не появляется над представлением трассировки.

Решение:

  1. Убедитесь, что Node graph включён в настройках источника данных Tempo в разделе Additional settings.
  2. Проверьте, что трассировка содержит несколько промежутков с отношениями родитель-потомок. Промежутки должны включать traceID и spanID, а некорневые промежутки должны включать parentSpanID, чтобы установить иерархию. Если эти идентификаторы отсутствуют, данные трассировки неполны на уровне инструментирования, и граф не может быть отрисован.

Автодополнение не работает

Причина: Редактор TraceQL не показывает подсказки для атрибутов или значений. Автодополнение требует, чтобы Tempo перечислял теги, что требует поддерживаемого бэкенда хранения (vParquet или более нового).

Решение:

  1. Для самостоятельно размещённого Tempo убедитесь, что бэкенд хранения поддерживает поиск по тегам. Tempo требует формат vParquet или более новый для поиска по тегам и автодополнения. Подробности см. в разделе Конфигурация Parquet. Grafana Cloud Traces поддерживает автодополнение по умолчанию.
  2. Проверьте настройку Tags time range в настройках источника данных, чтобы убедиться, что она охватывает период с недавними данными трассировки.
  3. Увеличьте настройку Tag limit, если у вас много уникальных атрибутов.
  4. Убедитесь, что подключение источника данных Tempo работает, выбрав Save & test в настройках источника данных.

Настройки источника данных исчезают после перезапуска

Причина: Вы настроили параметры в интерфейсе Grafana (такие как ссылки trace-to-logs, граф служб или временные сдвиги промежутков), но они исчезают после перезапуска Grafana. Это происходит, когда источник данных провижинен через файл конфигурации YAML, Helm-чарт или Terraform. Провижиненные источники данных доступны только для чтения в интерфейсе — любые изменения, которые вы вносите через интерфейс, не сохраняются и молча откатываются при следующем перезапуске.

Вы можете определить, что источник данных провижинен, если форма настроек доступна только для чтения и кнопка читается как Test вместо Save & test.

Решение:

  1. Чтобы изменить настройки навсегда, отредактируйте файл YAML провижининга и перезапустите Grafana (или дождитесь перезагрузки системы провижининга). Любую настройку, доступную в интерфейсе, можно задать в файле YAML, включая конфигурацию trace-to-logs, trace-to-metrics и графа служб. Полный справочник по YAML см. в разделе Провижининг источника данных Tempo.
  2. Для Grafana Cloud вы можете клонировать провижиненный источник данных, чтобы создать редактируемую копию, которая сохраняет изменения интерфейса. Шаги см. в разделе Клонирование провижиненного источника данных для Grafana Cloud.

Алертинг TraceQL недоступен

Причина: Вы можете выбрать источник данных Tempo в конструкторе правил Grafana Alerting, но стандартные запросы поиска TraceQL возвращают данные трассировки (промежутки и ID трассировок), а не числовые временные ряды. Правила алертинга требуют числовых данных для вычисления порогов, поэтому запросы поиска трассировок не создают пригодных условий алертинга.

Решение:

Запросы метрик TraceQL (такие как { } | rate() или { status = error } | count_over_time()) возвращают числовые временные ряды и могут напрямую управлять порогами алертов. Однако алертинг TraceQL требует экспериментального флага функции tempoAlerting, который отключён по умолчанию. Чтобы включить его, задайте флаг функции tempoAlerting в вашей конфигурации Grafana. Для Grafana Cloud свяжитесь с поддержкой, чтобы его включить. Пошаговую настройку см. в разделе Алерты на основе трассировок.

Caution

Флаг функции tempoAlerting экспериментальный. Для продакшен-алертинга рассмотрите подход на основе Prometheus, описанный ниже.

В качестве альтернативы используйте генератор метрик Tempo, чтобы создавать метрики Prometheus из данных трассировки, затем создайте правила алертинга против источника данных Prometheus, который хранит эти метрики.

  1. Настройте генератор метрик Tempo (используя процессор service-graphs, span-metrics или local-blocks), чтобы создавать метрики из трассировок и удалённо записывать их в совместимый с Prometheus бэкенд.
  2. Создайте правила алертинга против источника данных Prometheus, который принимает эти метрики. Например, создайте алерт по высокой частоте ошибок, используя traces_spanmetrics_calls_total с фильтром status_code="STATUS_CODE_ERROR".
  3. Обратитесь к таблице поддержки функций в обзоре источника данных Tempo за подробностями о поддержке алертинга.

Переключение между несколькими экземплярами Tempo

Причина: У вас настроено несколько источников данных Tempo (например, по одному на среду или на арендатора), но нет встроенного раскрывающегося списка в интерфейсе Explore или дашбордах для динамического переключения между ними.

Обходное решение:

  1. В дашбордах создайте переменную шаблона источника данных, отфильтрованную по типу tempo. Это добавляет раскрывающийся список, позволяющий зрителям переключаться между экземплярами Tempo без редактирования дашборда.
  2. В Explore используйте выбор источника данных в верхней панели, чтобы переключаться между настроенными источниками данных Tempo.
  3. Для мультиарендных настроек на одном экземпляре Tempo рассмотрите использование заголовка X-Scope-OrgID вместо отдельных источников данных. Подробности конфигурации см. в разделе Мультиарендность.

Проблемы с Private data source connect (только Grafana Cloud)

Эти проблемы связаны с подключением к приватному экземпляру Tempo с помощью Private data source connect (PDC). PDC доступен только в Grafana Cloud.

Note

Private data source connect позволяет Grafana Cloud безопасно подключаться к источникам данных в вашей приватной сети, не открывая их для публичного интернета. Инструкции по настройке см. в разделе Private data source connect.

Агент PDC не подключён

Сообщение об ошибке: No healthy PDC agents available или Private data source connect agent not connected

Причина: Агент PDC, установленный в вашей приватной сети, не запущен или не может подключиться к Grafana Cloud.

Решение:

  1. Убедитесь, что агент PDC запущен в вашей приватной сети.
  2. Проверьте журналы агента PDC на предмет ошибок подключения.
  3. Убедитесь, что у агента PDC есть исходящий сетевой доступ к конечным точкам Grafana Cloud.
  4. Убедитесь, что агент PDC использует правильный токен для вашего экземпляра Grafana Cloud.
  5. Проверьте, что правила брандмауэра разрешают исходящие HTTPS-подключения (порт 443) от агента PDC.
  6. Перезапустите агент PDC, если он выглядит зависшим или неотвечающим.

Дополнительную информацию см. в разделе Private data source connect.

Подключение через PDC не удаётся

Сообщение об ошибке: Failed to connect through private data source или Connection refused via PDC

Причина: Агент PDC подключён к Grafana Cloud, но не может достичь экземпляра Tempo в вашей приватной сети.

Решение:

  1. Убедитесь, что URL Tempo верен и доступен с машины, на которой запущен агент PDC.
  2. Проверьте, что агент PDC может разрешить имя хоста Tempo (разрешение DNS).
  3. Убедитесь, что нет правил брандмауэра, блокирующих подключения от агента PDC к Tempo.
  4. Убедитесь, что порт Tempo (по умолчанию 3200) открыт и доступен.
  5. Проверьте связность с хоста агента PDC до Tempo, используя curl или telnet.

Ошибки тайм-аута PDC

Сообщение об ошибке: Request timed out via private data source connect

Причина: Запросы через туннель PDC истекают по тайм-ауту.

Решение:

  1. Проверьте сетевую задержку между агентом PDC и Tempo.
  2. Убедитесь, что у хоста агента PDC достаточно ресурсов (ЦП, память, пропускная способность сети).
  3. Убедитесь, что никакие сетевые устройства между агентом PDC и Tempo не отбрасывают долгоживущие подключения.
  4. Для больших запросов рассмотрите возможность уменьшения диапазона времени или добавления более конкретных фильтров.
  5. Проверьте, не разделяют ли несколько источников данных один и тот же агент PDC, что может вызвать конкуренцию за ресурсы.

Несоответствие аутентификации PDC

Сообщение об ошибке: Unauthorized или 403 Forbidden при использовании PDC

Причина: Аутентификация, настроенная в источнике данных, не работает с подключением PDC.

Решение:

  1. Убедитесь, что учётные данные аутентификации правильно настроены в настройках источника данных Grafana Cloud.
  2. Проверьте, что экземпляр Tempo принимает настроенный метод аутентификации.
  3. Убедитесь, что любые требуемые заголовки (такие как X-Scope-OrgID для мультиарендного Tempo) правильно передаются через PDC.
  4. Протестируйте подключение напрямую с хоста агента PDC, чтобы убедиться, что учётные данные работают вне PDC.

Получение дополнительной помощи

Если проблемы сохраняются после следования этому руководству по устранению неполадок:

  1. Пользователям Grafana Cloud: попробуйте Grafana Assistant для интерактивного исследования проблем с трассировками (если он включён в вашей учётной записи).
  2. Пользователям Grafana Cloud, которые отправляют трассировки с помощью Alloy, см. шаги по устранению неполадок Alloy на предмет проблем на стороне приёма.
  3. Задавайте вопросы на форумах сообщества Grafana или в Grafana Community Slack.
  4. Просмотрите проблемы Grafana на GitHub на предмет известных ошибок.
  5. Просмотрите проблемы Tempo на GitHub на предмет ошибок, специфичных для Tempo.
  6. Включите журналирование отладочного уровня в Grafana, чтобы получить подробную информацию об ошибках.
  7. Проверьте журналы сервера Tempo на предмет дополнительных сведений об ошибках.
  8. Свяжитесь с поддержкой Grafana, если вы пользователь Enterprise, Cloud Pro или Cloud Contracted.

При сообщении о проблемах указывайте:

  • Версию Grafana
  • Версию Tempo
  • Сообщения об ошибках (удалите конфиденциальную информацию)
  • Шаги для воспроизведения
  • Примеры запросов TraceQL (удалите конфиденциальные данные)
  • Соответствующие настройки конфигурации