Документацияbreadcrumb arrow Grafanabreadcrumb arrow Документация GlaberGraphbreadcrumb arrow Источники данныхbreadcrumb arrow Zipkinbreadcrumb arrow Устранение неполадок
Последнее обновление: августа 11, 2026

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

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

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

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

error reading settings: url is empty

Симптомы:

  • Save & test немедленно завершается неудачно
  • Проверка работоспособности возвращает ошибку

Решения:

  1. Откройте настройки источника данных и убедитесь, что поле URL не пусто.
  2. Введите полный URL вашего экземпляра Zipkin, например http://localhost:9411.

«request failed: 404 Not Found» или другие ошибки статуса HTTP

Симптомы:

  • Save & test завершается неудачно с ошибкой статуса HTTP
  • Запросы трассировок возвращают ошибки

Возможные причины и решения:

Причина Решение
Неверный URL или порт Убедитесь в правильности URL и порта. Порт Zipkin по умолчанию — 9411. Убедитесь, что вы случайно не использовали порт Jaeger (16686).
Отсутствует путь /api/v2 Источник данных Zipkin вызывает /api/v2/services, /api/v2/traces и т. д. Убедитесь, что эти конечные точки доступны по настроенному URL.
Неправильная настройка обратного прокси Если используется обратный прокси, убедитесь, что он правильно пересылает запросы к API Zipkin.
Сбой аутентификации Если экземпляр Zipkin требует аутентификации, убедитесь, что ваши учётные данные верны.

error creating http client или ошибки TLS

Симптомы:

  • Save & test завершается неудачно с ошибкой подключения или TLS
  • HTTPS-подключения отклоняются

Решения:

  1. Если используется HTTPS, убедитесь, что TLS-сертификат действителен и доверен сервером Grafana.
  2. Настройте параметры TLS в Additional settings > Advanced HTTP settings.
  3. Для самоподписанных сертификатов добавьте сертификат CA в хранилище доверенных сертификатов сервера Grafana или включите Skip TLS Verify (не рекомендуется для продакшена).

Save & test истекает по тайм-ауту

Симптомы:

  • Save & test зависает и в конечном итоге истекает по тайм-ауту
  • Сообщение об ошибке не возвращается

Возможные причины и решения:

Причина Решение
Экземпляр Zipkin не работает Убедитесь, что экземпляр Zipkin запущен и доступен с сервера Grafana.
Правила брандмауэра или сети Убедитесь, что сервер Grafana может достичь экземпляра Zipkin. Проверьте, что правила брандмауэра разрешают исходящий трафик на настроенном порту.
Сбой разрешения DNS Убедитесь, что имя хоста в URL правильно разрешается с сервера Grafana.

Для Grafana Cloud, если вы обращаетесь к приватному экземпляру Zipkin, настройте Private data source connect.

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

Эти ошибки возникают при использовании редактора запросов в Explore или на дашбордах.

«Failed to load spans from Zipkin»

Симптомы:

  • Сообщение об ошибке появляется в редакторе запросов
  • Каскадный селектор Traces не заполняет службы, промежутки или трассировки

Эта ошибка возникает, когда фронтенд не может достичь конечных точек API Zipkin (/api/v2/services, /api/v2/spans или /api/v2/traces).

Решения:

  1. Убедитесь, что экземпляр Zipkin запущен и доступен.
  2. Протестируйте конечную точку напрямую: curl http://<ZIPKIN_URL>/api/v2/services.
  3. Проверьте, что сервер Grafana может достичь API Zipkin.
  4. Просмотрите журналы сервера Grafana для получения более подробной информации. Ищите An error occurred while doing a resource call в журналах.

«An error occurred within the plugin»

Симптомы:

  • Общая ошибка появляется при запросе или просмотре трассировок
  • В интерфейсе не отображаются конкретные сведения об ошибке

Это общая ошибка, возвращаемая бэкендом плагина Zipkin при возникновении внутренней ошибки. Фактические сведения об ошибке доступны только в журналах сервера Grafana.

Решения:

  1. Включите журналирование отладочного уровня, чтобы получить подробную информацию об ошибках.
  2. Проверьте журналы сервера Grafana на предмет сообщений типа An error occurred while doing a resource call или An error occurred while processing response from resource call.
  3. Убедитесь, что экземпляр Zipkin работоспособен и отвечает на запросы API.

«No data» или пустые результаты

Симптомы:

  • Запрос выполняется без ошибок, но не возвращает данные
  • Представление трассировки показывает «No data»
  • Каскадный селектор показывает «No traces found» или «[No traces in time range]»

Возможные причины и решения:

Причина Решение
Неверный ID трассировки Убедитесь, что ID трассировки верен. ID трассировок Zipkin — это шестнадцатеричные строки из 16 или 32 символов.
Пустой ID трассировки Убедитесь, что поле Trace ID не пусто. Бэкенд отклоняет запросы с invalid/empty traceId.
Диапазон времени не содержит данных Расширьте диапазон времени дашборда или Explore. Трассировки должны попадать в выбранный диапазон времени, чтобы каскадный селектор мог их найти.
Срок хранения трассировки истёк Zipkin мог удалить старые данные трассировки в соответствии с настройками хранения. Проверьте конфигурацию хранилища Zipkin.
Нет зарегистрированных служб Если каскадный селектор показывает «No traces found» на верхнем уровне, в вашем экземпляре Zipkin может не быть данных. Убедитесь, что данные собираются.

Ошибки загрузки

Эти ошибки возникают при импорте файла трассировки JSON.

«JSON is not valid Zipkin format»

Симптомы:

  • Ошибка появляется после загрузки файла трассировки JSON
  • Трассировка не отрисовывается

Возможные причины и решения:

Причина Решение
Недопустимый синтаксис JSON Проверьте файл с помощью JSON-линтера. Распространённые проблемы включают завершающие запятые, отсутствующие кавычки или незакрытые скобки.
Неверная структура JSON Файл должен быть массивом JSON объектов промежутков ([{...}, {...}]), а не единичным объектом. Обратитесь к формату промежутка Zipkin v2.
Неверный тип файла Убедитесь, что вы загружаете файл .json, а не другой формат.

unsupported query type upload. only available in frontend mode

Симптомы:

  • Ошибка при попытке использовать загруженные данные трассировки на панели дашборда или в алерте

Запросы загрузки работают только в Explore. Они не могут использоваться на панелях дашборда или в правилах алертинга, потому что загрузка обрабатывается в браузере, а не на бэкенде.

Решение:

Используйте тип запроса TraceID с ID трассировки из вашей загруженной трассировки, если вам нужно отобразить её на дашборде. Это требует, чтобы трассировка существовала в вашем экземпляре Zipkin.

Ошибки конфигурации

Эти ошибки связаны с настройками конфигурации источника данных.

«Invalid time shift. See tooltip for examples.»

Симптомы:

  • Ошибка появляется в конфигурации trace to logs или trace to metrics
  • Поле Span start time shift или Span end time shift выделено

Решения:

  1. Используйте допустимые форматы единиц времени: 5s, 1m, 3h, -30m.
  2. Используйте отрицательное значение, чтобы сдвинуть время в прошлое (например, -1h).
  3. Значение должно быть числом, за которым следует единица времени (s, m, h).

Симптомы:

  • В представлении трассировки не появляются ссылки на журналы
  • Ссылки появляются для одних промежутков, но не для других

Возможные причины и решения:

Причина Решение
Теги отсутствуют в промежутке Теги, настроенные в настройках trace to logs, должны существовать в атрибутах промежутка, чтобы ссылка появилась. Убедитесь, что промежуток содержит ожидаемые теги.
Источник данных журналов не настроен Убедитесь, что целевой источник данных журналов (Loki, Elasticsearch, Splunk, OpenSearch, FalconLogScale, Google Cloud Logging или VictoriaMetrics Logs) настроен и работает.
Переменные пользовательского запроса не разрешены При использовании пользовательского запроса ссылка появляется только тогда, когда все переменные разрешаются в непустые значения. Убедитесь, что промежуток содержит указанные теги.
Выбран неверный тип источника данных Источник данных trace to logs должен быть поддерживаемым источником данных журналов. Другие типы источников данных не появляются в раскрывающемся списке.

Симптомы:

  • В представлении трассировки не появляются ссылки на метрики

Решения:

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

Ошибки переменных шаблонов

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

Значение переменной не подставляется в запрос

Симптомы:

  • Поле ID трассировки показывает синтаксис переменной (например, ${traceId}) вместо фактического значения
  • Запрос не возвращает результатов при использовании переменной

Решения:

  1. Перейдите к дашборду, который хотите обновить, и нажмите Edit.
  2. Нажмите значок Dashboard options, чтобы открыть боковую панель.
  3. Разверните раздел Variables.
  4. Убедитесь, что переменная определена.
  5. Проверьте, что имя переменной соответствует синтаксису, используемому в запросе. Имена переменных чувствительны к регистру.
  6. Убедитесь, что для переменной выбрано или введено значение.
  7. Для переменных текстового поля убедитесь, что зритель ввёл значение.

Включение журналирования отладочного уровня

Чтобы получить подробную информацию об ошибках для устранения неполадок:

  1. Установите уровень журнала Grafana в debug в файле конфигурации:

    ini 
    [log]
level = debug

  2. Просмотрите журналы в /var/log/grafana/grafana.log (или в настроенном вами расположении журналов).

  3. Найдите записи, специфичные для Zipkin, которые содержат сведения о запросах и ответах, такие как:

    • Failed to close response body
    • An error occurred while doing a resource call
    • An error occurred while processing response from resource call

  4. Сбросьте уровень журнала на info после устранения неполадок, чтобы избежать чрезмерного объёма журналов.

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

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

  1. Проверьте форумы сообщества Grafana на наличие похожих проблем.
  2. Просмотрите проблемы Grafana на GitHub на предмет известных ошибок.
  3. Обратитесь к документации Zipkin за рекомендациями, специфичными для службы.
  4. Свяжитесь с поддержкой Grafana, если у вас платный план. Откройте обращение в поддержку для Grafana Cloud или свяжитесь с поддержкой для Grafana Enterprise.
  5. При сообщении о проблемах указывайте:
    • Версию Grafana
    • Сообщения об ошибках (удалите конфиденциальную информацию)
    • Шаги для воспроизведения
    • Соответствующую конфигурацию (удалите учётные данные)