Устранение неполадок источника данных Pyroscope
В этом документе приведены решения распространённых проблем, с которыми вы можете столкнуться при настройке или использовании источника данных Pyroscope. Инструкции по настройке см. в разделе Настройка источника данных Pyroscope.
Ошибки подключения и конфигурации
Эти ошибки возникают при настройке источника данных или при подключении к бэкенду Pyroscope.
«Data source is not working» или подключение не удаётся
Симптомы:
- Save & test завершается ошибкой подключения
- Сообщение об ошибке указывает, что бэкенд Pyroscope недоступен
- Ошибки тайм-аута при проверке источника данных
Возможные причины и решения:
Проблемы с форматом URL
Симптомы:
- Проверка источника данных немедленно завершается неудачно
- Ошибка указывает на недопустимый URL
Решения:
- Убедитесь, что URL включает протокол (
http://илиhttps://). - Удалите любые завершающие слэши из URL.
- Для Grafana Cloud Profiles найдите правильный URL в разделе Manage your stack в настройках вашей организации.
- Убедитесь, что номер порта верен для вашего развёртывания.
Ошибки «Connection refused» или тайм-аута
Симптомы:
- Проверка источника данных завершается сетевыми ошибками
- Запросы завершаются ошибками подключения
- Периодические проблемы со связностью
Решения:
- Проверьте сетевую связность от сервера Grafana до конечной точки Pyroscope.
- Проверьте, что правила брандмауэра разрешают исходящие подключения на требуемом порту (по умолчанию: 4040).
- Для развёртываний Kubernetes убедитесь, что служба правильно открыта (exposed).
- Проверьте, требуется ли прокси, и настройте его в настройках источника данных.
Ошибки сертификатов SSL/TLS
Симптомы:
- Сбои проверки сертификата
- Ошибки SSL-рукопожатия
- Сообщения «Certificate not trusted»
Решения:
- Убедитесь, что системное время верно на сервере Grafana.
- Убедитесь, что сертификат действителен и не истёк.
- Для самоподписанных сертификатов включите Skip TLS Verify в настройках источника данных (не рекомендуется для продакшена).
- Добавьте сертификат CA в доверенные сертификаты сервера Grafana.
- Проверьте, что промежуточные сертификаты включены в цепочку сертификатов.
Проблемы приватной связности или обратного прокси
Симптомы:
- Источник данных работает из одних сетей, но не из других.
- Подключение через обратный прокси, балансировщик нагрузки или приватную связь (private link) не удаётся.
Решения:
- Включите схему в Connection URL. При подключении через приватную конечную точку или обратный прокси используйте
https://явно, а не только имя хоста. - Убедитесь, что обратный прокси или шлюз передаёт пути API Pyroscope без изменений. Перезапись или удаление пути запроса не позволяет источнику данных достичь бэкенда.
- Для Grafana Cloud, подключающегося к бэкенду Pyroscope в приватной сети, настройте Private data source connect.
- Убедитесь, что любой брандмауэр или приватная связь разрешает исходящий HTTPS от Grafana до конечной точки Pyroscope.
Ошибки аутентификации
Эти ошибки возникают, когда источник данных не может аутентифицироваться в бэкенде Pyroscope.
«Authentication failed» или «Unauthorized»
Симптомы:
- Save & test завершается ошибками аутентификации
- Запросы возвращают коды состояния 401 или 403
- Типы профилей не загружаются
Возможные причины и решения:
Базовая аутентификация не работает
Симптомы:
- Учётные данные базовой аутентификации отклоняются
- Работает в браузере, но не удаётся в Grafana
Решения:
- Убедитесь, что базовая аутентификация включена в настройках источника данных.
- Убедитесь, что имя пользователя и пароль введены правильно (без лишних пробелов).
- Проверьте, что бэкенд Pyroscope настроен на приём базовой аутентификации.
- Для Grafana Cloud Profiles используйте базовую аутентификацию с вашим токеном политики доступа в качестве пароля. См. Проблемы с политикой доступа и токеном Grafana Cloud.
Проблемы с аутентификацией по API-ключу
Симптомы:
- API-ключ отклоняется
- Ошибка указывает на недействительный токен
Решения:
- Убедитесь, что вы используете правильный формат API-ключа для вашего развёртывания Pyroscope.
- Для Grafana Cloud создайте новый токен политики доступа с областью действия
profiles:read. - Убедитесь, что у учётных данных есть требуемые разрешения на чтение данных профилирования.
- Проверьте, не истёк ли срок действия токена, и при необходимости создайте новый.
Проблемы с политикой доступа и токеном Grafana Cloud
Симптомы:
- Аутентификация не удаётся при подключении источника данных к Grafana Cloud Profiles.
- Запросы возвращают 401 или 403 после миграции бэкенда или изменения стека.
- Источник данных читает из другого стека или арендатора, чем ожидалось.
Причина:
Grafana Cloud Profiles аутентифицируется с помощью токена политики доступа, а не пароля пользователя. Токен должен принадлежать политике доступа, которая включает область действия profiles:read и нацелена на правильный стек. Токен с неверной областью действия или созданный для другого стека не проходит аутентификацию или возвращает данные из неверного арендатора. Токены и URL подключения специфичны для стека и не переносятся во время миграции.
Решения:
- Создайте или выберите политику доступа, которая включает область действия
profiles:readи чья область (realm) нацелена на правильный стек, затем создайте токен для этой политики. - В источнике данных включите Basic auth. Введите числовой ID экземпляра в качестве имени пользователя и токен политики доступа в качестве пароля. Найдите ID экземпляра и конечную точку в разделе Manage your stack.
- Убедитесь, что Connection URL указывает на конечную точку Pyroscope для того же стека, что и токен.
- После миграции бэкенда или изменения стека создайте токен заново, затем обновите как URL, так и учётные данные.
Ошибки запросов
Эти ошибки возникают при выполнении запросов к источнику данных Pyroscope.
«No data» или пустые результаты
Симптомы:
- Запрос выполняется без ошибок, но не возвращает данные
- Граф пламени показывает сообщение «No data»
- График метрик пуст
Возможные причины и решения:
Note
Если проверка подключения источника данных проходит успешно, но профили не существуют ни для одного запроса, проблема обычно на стороне приёма данных, а не в источнике данных. Источник данных только читает профили из Pyroscope; он не собирает и не отправляет их. Убедитесь, что ваше приложение, SDK или коллектор, такой как Grafana Alloy или OpenTelemetry Collector, отправляет профили в ваш бэкенд Pyroscope. О настройке приёма данных см. Настройка клиента на отправку профилей.
«Profile type not found» или пустой селектор типов профилей
Симптомы:
- Раскрывающийся список типов профилей пуст
- Ошибка указывает, что тип профиля не существует
Решения:
- Убедитесь, что бэкенд Pyroscope принимает профили из ваших приложений.
- Проверьте, что диапазон времени включает периоды, когда профили собирались.
- Проверьте подключение источника данных, чтобы убедиться, что оно работает правильно.
- Для новых развёртываний подождите несколько минут, пока первоначальные данные профилей будут приняты.
Имена или значения меток не загружаются
Симптомы:
- Селектор меток не заполняется
- В раскрывающихся меню не появляются метки
- Автодополнение не работает
Решения:
- Убедитесь, что подключение источника данных работает, проверив его в настройках.
- Сначала выберите тип профиля, поскольку метки загружаются на основе выбранного типа профиля.
- Расширьте диапазон времени, чтобы убедиться, что данные меток доступны.
- Проверьте консоль браузера на предмет ошибок JavaScript, которые могут указывать на проблемы.
Синтаксические ошибки запроса
Симптомы:
- Сообщение об ошибке указывает на недопустимый синтаксис запроса
- Селектор меток отклоняется
Решения:
- Используйте правильный синтаксис селектора меток. Pyroscope использует синтаксис, похожий на Prometheus.
- Заключайте значения меток в двойные кавычки:
{service_name="my-service"}. - Используйте допустимые операторы:
=,!=,=~,!~. - Экранируйте специальные символы в шаблонах регулярных выражений при использовании
=~или!~.
Пример допустимых запросов:
{service_name="my-app"}
{service_name="my-app", env="production"}
{service_name=~"my-app.*"}
Запросы возвращают только свежие данные, хотя более старые данные сохранены
Если запрос за длительный диапазон времени возвращает данные только за самые последние дни, вероятно, диапазон времени запроса превышает серверный лимит запроса. Это чаще всего сообщается в Grafana Cloud Profiles. См. Диапазон времени запроса и лимиты хранения.
Проблемы с графом пламени
Эти ошибки специфичны для визуализации графа пламени.
Граф пламени не отрисовывается
Симптомы:
- Запрос возвращает данные, но граф пламени не отображается
- Область графа пламени пуста
- Индикатор загрузки никогда не завершается
Решения:
- Проверьте, что Query Type установлен так, чтобы включать данные профилей (не только метрики).
- Убедитесь, что ответ содержит допустимые данные профилей, с помощью Query Inspector.
- Попробуйте обновить страницу или повторно выполнить запрос.
- Для больших профилей увеличьте лимиты памяти браузера или уменьшите диапазон времени.
Граф пламени истекает по тайм-ауту или не загружается при больших диапазонах времени
Симптомы:
- Граф пламени отрисовывается для короткого диапазона времени, например пяти минут, но истекает по тайм-ауту для более длинного диапазона, например 30 минут или более.
- Запросы за большие диапазоны времени медленные или периодически завершаются неудачно.
Причина:
Отрисовка графа пламени за большой диапазон времени требует, чтобы бэкенд Pyroscope объединил множество профилей, что увеличивает время запроса и использование памяти. Большие диапазоны или диапазоны с высокой кардинальностью могут превысить тайм-ауты запросов до возврата результата.
Решения:
- Сузьте диапазон времени. Начните с короткого окна, например пяти минут, затем постепенно расширяйте его, чтобы найти наибольший диапазон, который надёжно отрисовывается.
- Добавьте фильтры меток, чтобы уменьшить объём профилей, которые должен объединить бэкенд.
- Убедитесь, что диапазон находится в пределах серверных лимитов запросов, описанных в разделе Диапазон времени запроса и лимиты хранения.
- Для самостоятельно размещённых развёртываний проверьте ресурсы бэкенда и настройки тайм-аута запросов, если большие диапазоны постоянно завершаются неудачно.
Граф пламени показывает агрегированные данные без деталей
Симптомы:
- Граф пламени не имеет ожидаемой детализации
- Имена функций отсутствуют или усечены
- Стек вызовов выглядит неполным
Решения:
- Увеличьте масштаб до меньшего диапазона времени, чтобы получить более детальные профили.
- Убедитесь, что ваше приложение инструментировано для захвата полных стеков вызовов.
- Проверьте, настроен ли агент профилирования с достаточной частотой выборки.
- Для компилируемых языков убедитесь, что доступны отладочные символы.
Невозможно взаимодействовать с графом пламени
Симптомы:
- Нажатие на элементы графа пламени не работает
- Всплывающая подсказка не появляется
- Элементы управления масштабированием и фильтрацией не реагируют
Решения:
- Убедитесь, что в вашем браузере включён JavaScript.
- Проверьте консоль браузера на предмет ошибок JavaScript.
- Попробуйте использовать другой браузер или очистить кэш браузера.
- Обновите Grafana до последней версии.
Ошибки переменных шаблонов
Эти ошибки возникают при использовании переменных шаблонов с источником данных Pyroscope.
Переменные не возвращают значений
Симптомы:
- Раскрывающийся список переменной пуст
- Зависимые переменные не заполняются
Решения:
- Убедитесь, что подключение источника данных работает, проверив его в настройках.
- Для переменных Label и Label value убедитесь, что выбран тип профиля. Метки и значения меток ограничены выбранным типом профиля.
- Расширьте диапазон времени дашборда, чтобы запрос переменной охватывал период, когда профили собирались.
- Убедитесь, что бэкенд Pyroscope принимает профили из ваших приложений.
Переменные не фильтруют запросы так, как ожидалось
Симптомы:
- Результаты запроса не изменяются при изменении значения переменной
- Запросы не возвращают данных после выбора значения переменной
Решения:
- Убедитесь, что переменная правильно указана в селекторе меток, например
{service_name="$service"}. - Когда включены Multi-value или Include All, значение переменной становится шаблоном регулярного выражения. Используйте оператор
=~вместо=, например{service_name=~"$service"}. - Убедитесь, что метка, используемая в переменной, существует в данных профилирования для выбранного типа профиля.
Дополнительную информацию см. в разделе Переменные шаблонов Pyroscope.
Проблемы с Profiles Drilldown
Эти ошибки специфичны для приложения Profiles Drilldown.
Profiles Drilldown недоступен
Симптомы:
- Опция Profiles Drilldown не появляется в меню
- Ошибка при попытке доступа к Profiles Drilldown
Решения:
- Убедитесь, что плагин Profiles Drilldown установлен и включён.
- Для самостоятельно размещённой Grafana установите плагин из каталога плагинов Grafana.
- Перезапустите Grafana после установки плагина.
- Проверьте, что у вас есть требуемые разрешения для доступа к приложению.
Службы или профили не появляются в Profiles Drilldown
Симптомы:
- Profiles Drilldown не показывает службы
- Ожидаемые приложения отсутствуют
Решения:
- Убедитесь, что источник данных Pyroscope настроен и работает.
- Проверьте, что профили принимаются с правильной меткой
service_name. - Убедитесь, что диапазон времени включает периоды, когда профили собирались.
- Для режима микросервисов убедитесь, что URL источника данных указывает на правильный шлюз.
Проблемы с Trace to profiles
Эти ошибки возникают при связывании данных трассировки и профилирования.
Trace to profiles — наиболее чувствительная к конфигурации функция источника данных. Большинство проблем возникает из-за невыполненного предварительного условия, а не из-за неправильной настройки источника данных.
Контрольный список предварительных условий:
Подтвердите все следующие пункты перед дальнейшим устранением неполадок:
- Ваше приложение инструментировано с помощью языкового SDK Pyroscope для профилирования и с помощью OpenTelemetry для трассировки.
- Вы установили пакет-мост профилирования промежутков OpenTelemetry для вашего языка. Это отдельный пакет от SDK Pyroscope и SDK OpenTelemetry.
- Профилирование использует инструментирование на основе SDK. Профили промежутков недоступны при сборе на основе eBPF.
- В источнике данных Tempo настроен Trace to profiles, и он указывает на ваш источник данных Pyroscope.
- Теги, настроенные в источнике данных Tempo, присутствуют в атрибутах или ресурсах промежутка.
Инструкции по настройке для каждого языка см. в разделе Связывание трассировок с профилями.
Профили промежутков не появляются
Симптомы:
- Промежутки трассировки не показывают ссылки на профили
- Опция «Profiles for this span» отсутствует
Решения:
- Убедитесь, что источник данных Tempo настроен с включённым Trace to profiles и что он указывает на ваш источник данных Pyroscope.
- Убедитесь, что атрибут
pyroscope.profile.idсуществует на промежутке в Tempo. Если он отсутствует, пакет-мост неправильно помечает промежутки. - Убедитесь, что метка
span_nameсуществует в данных профилирования в Pyroscope. Если она отсутствует, пакет-мост неправильно помечает образцы. - Убедитесь, что теги, которые вы настроили в источнике данных Tempo, соответствуют атрибутам или ресурсам промежутка. Если они не совпадают, ссылка не появляется.
- Убедитесь, что данные профилей существуют для диапазона времени трассировки.
Дополнительную информацию см. в разделе Настройка Trace to profiles.
Профиль не соответствует промежутку трассировки
Симптомы:
- Данные профиля не коррелируют с трассировкой
- Неверный диапазон времени в профиле
Решения:
- Убедитесь, что временные метки трассировки и профиля синхронизированы.
- Проверьте, что часы приложения точны.
- Убедитесь, что метки
span_idиtrace_idправильно передаются в профили.
Профили промежутков недоступны при сборе на основе eBPF
Симптомы:
- Трассировки и профили оба существуют, но ссылки на промежутки не появляются.
- Профилирование собирается с помощью eBPF, например через Grafana Alloy или Beyla.
Причина:
Профилирование промежутков сопоставляет образцы профилирования с активным промежутком трассировки, что требует языкового SDK и моста профилирования промежутков OpenTelemetry. Сбор на основе eBPF не может связать образцы с отдельными промежутками, поэтому он не создаёт профили промежутков.
Решения:
- Инструментируйте приложение с помощью поддерживаемого языкового SDK Pyroscope и соответствующего пакета-моста, чтобы включить профили промежутков.
- Если вы должны использовать профилирование eBPF, просматривайте профили по службе вместо этого. Корреляция по отдельным промежуткам в настоящее время не поддерживается для данных, собранных eBPF.
Фильтруйте профили промежутков по имени промежутка или ID трассировки, а не по ID промежутка
Симптомы:
- Запросы, отфильтрованные по
span_id, не возвращают данных, тогда какspan_nameработает. - Корреляция профилей с конкретным промежутком по
span_idненадёжна.
Причина:
Мост профилирования промежутков помечает образцы профилирования с помощью span_name и trace_id. В зависимости от SDK, контекст профилирования может быть привязан только к корневому промежутку трассировки, при этом дочерние промежутки его наследуют. span_id имеет высокую кардинальность и не является надёжной меткой для корреляции.
Решения:
- Фильтруйте данные профилирования по
span_nameилиtrace_id, а не поspan_id. - Используйте ссылку Profiles for this span, которая коррелирует с помощью атрибута промежутка
pyroscope.profile.id, а не запроса по метке.
Конфликт профилировщика .NET с автоинструментированием OpenTelemetry
Симптомы:
- В .NET профили промежутков не работают, когда одновременно включены профилировщик .NET Pyroscope и автоинструментирование OpenTelemetry.
- Одному из профилировщиков не удаётся подключиться.
Причина:
CLR .NET позволяет только одному профилировщику подключаться к процессу одновременно. Профилировщик .NET Pyroscope и автоинструментирование OpenTelemetry каждый полагаются на отдельный профилировщик CLR, поэтому они конфликтуют.
Решения:
- Используйте ручное инструментирование OpenTelemetry вместо автоинструментирования.
- Добавьте пакет
Pyroscope.OpenTelemetryи зарегистрируйтеPyroscopeSpanProcessorв вашем конвейере трассировки. - Инструкции по настройке см. в разделе Профили промежутков с Traces to profiles для .NET.
Корреляция журналов с профилями
Симптомы:
- Вы хотите перейти от строки журнала непосредственно к данным профилирования, но ссылка не существует.
Причина:
Grafana поддерживает Trace to profiles, но прямой корреляции журналов с профилями нет.
Решения:
- Коррелируйте через общие метки, такие как
service_name, чтобы переходить между журналами и профилями для одной службы и диапазона времени. - Если ваши журналы содержат
trace_id, используйте производное поле Loki, чтобы открыть трассировку, затем используйте Profiles for this span из трассировки, чтобы достичь данных профилирования.
Проблемы производительности
Эти проблемы связаны с медленными запросами или высоким потреблением ресурсов.
Медленные запросы или тайм-ауты
Симптомы:
- Запросы выполняются долго
- Запросы истекают по тайм-ауту до возврата результатов
- Панели дашборда не загружаются
Решения:
- Уменьшите диапазон времени, чтобы сократить объём обрабатываемых данных.
- Добавьте фильтры меток, чтобы сузить область запроса.
- Увеличьте настройку Timeout в Additional settings источника данных.
- Настройте Minimal step, чтобы уменьшить количество точек данных.
- Для больших развёртываний убедитесь, что у бэкенда Pyroscope достаточно ресурсов.
Высокое использование памяти в браузере
Симптомы:
- Браузер перестаёт отвечать при просмотре профилей
- Появляются предупреждения о памяти
- Страница падает при загрузке графов пламени
Решения:
- Уменьшите диапазон времени, чтобы загружать меньшие профили.
- Закройте ненужные вкладки браузера, чтобы освободить память.
- Используйте меньшее окно агрегации для очень больших профилей.
- Рассмотрите использование Profiles Drilldown для крупномасштабного анализа.
Проблемы, специфичные для Grafana Cloud
Эти проблемы чаще всего сообщаются в Grafana Cloud Profiles. Некоторые лимиты также применяются к самостоятельно размещённым развёртываниям Pyroscope, где вы можете настроить их напрямую в конфигурации Pyroscope.
Диапазон времени запроса и лимиты хранения
Симптомы:
- Запрос за длительный диапазон времени, например 30 дней, возвращает данные только за самые последние дни.
- Более старые профили выглядят отсутствующими, хотя период хранения не истёк.
- Пользователи интерпретируют отсутствующие данные как потерю данных или ошибку.
Причина:
Pyroscope применяет лимиты запросов на стороне сервера, которые отделены от периода хранения данных и часто короче его. Эти лимиты применяются фронтендом запросов Pyroscope, а не источником данных Grafana, поэтому источник данных не может их изменить или переопределить.
Поскольку период хранения обычно длиннее окна запроса, профили могут быть сохранены, но не доступны для запросов. Например, Grafana Cloud Profiles хранит данные 14 дней на бесплатных планах и 30 дней на платных, тогда как окно запроса по умолчанию составляет 7 дней.
Note
Показанные значения по умолчанию — это значения по умолчанию для Pyroscope OSS. Grafana Cloud и самостоятельно размещённые развёртывания могут настраивать другие значения.
Решения:
- Подтвердите, что это лимит, а не пробел в приёме данных, сузив диапазон времени до самого последнего периода и убедившись, что данные появляются.
- Чтобы запросить дальше, чем окно запроса, повысьте лимит, а не разделяйте запрос на меньшие диапазоны. Поскольку окно измеряется от текущего времени, разделение длинного диапазона на 7-дневные приращения не возвращает более старые данные.
- Для самостоятельно размещённых развёртываний увеличьте
querier.max-query-lookbackи, при необходимости,querier.max-query-lengthв конфигурации лимитов Pyroscope. Установите значение0, чтобы отключить этот лимит. - Для Grafana Cloud Profiles свяжитесь с поддержкой Grafana, чтобы настроить эти лимиты для вашего арендатора.
- Если один запрос превышает
querier.max-query-length, уменьшите временной промежуток запроса, чтобы он оставался в пределах настроенного лимита.
Включение журналирования отладочного уровня
Чтобы получить подробную информацию об ошибках для устранения неполадок:
-
Установите уровень журнала Grafana в
debugв файле конфигурации:[log] level = debug -
Просмотрите журналы в
/var/log/grafana/grafana.log(или в настроенном вами расположении журналов). -
Найдите записи, специфичные для Pyroscope, которые содержат сведения о запросах и ответах.
-
Сбросьте уровень журнала на
infoпосле устранения неполадок, чтобы избежать чрезмерного объёма журналов.
Получение дополнительной помощи
Если вы испробовали решения из этого руководства, но проблемы сохраняются:
- Проверьте форумы сообщества Grafana на наличие похожих проблем.
- Просмотрите проблемы Pyroscope на GitHub на предмет известных ошибок.
- Обратитесь к документации Pyroscope за дополнительными рекомендациями.
- Свяжитесь с поддержкой Grafana, если вы пользователь Enterprise, Cloud Pro или Cloud Contracted.
- При сообщении о проблемах указывайте:
- Версию Grafana
- Версию Pyroscope (если самостоятельно размещён)
- Сообщения об ошибках (удалите конфиденциальную информацию)
- Шаги для воспроизведения
- Конфигурацию источника данных (удалите учётные данные)