Python

ClickStack использует стандарт OpenTelemetry для сбора телеметрических данных (логов и трассировок). Трассировки генерируются автоматически при помощи автоматической инструментализации, поэтому ручная инструментализация не нужна, чтобы извлечь пользу из трассировки.

В этом руководстве рассматривается интеграция:

• Логи
• Метрики
• Трассировки

Начало работы

Установите пакет инструментирования ClickStack OpenTelemetry

Выполните следующую команду, чтобы установить пакет ClickStack OpenTelemetry.

pip install hyperdx-opentelemetry

Установите библиотеки автоматической инструментации OpenTelemetry для пакетов, используемых вашим Python‑приложением. Мы рекомендуем использовать инструмент opentelemetry-bootstrap, который поставляется с OpenTelemetry Python SDK, для сканирования пакетов вашего приложения и генерации списка доступных библиотек.

opentelemetry-bootstrap -a install

Настройте переменные окружения

Далее в оболочке необходимо задать следующие переменные окружения, чтобы отправлять телеметрию в ClickStack:

export HYPERDX_API_KEY='<ВАШ_API_КЛЮЧ_ДЛЯ_ПРИЕМА_ДАННЫХ>' \
OTEL_SERVICE_NAME='<ИМЯ_ВАШЕГО_ПРИЛОЖЕНИЯ_ИЛИ_СЕРВИСА>' \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 

Переменная окружения OTEL_SERVICE_NAME используется для идентификации вашего сервиса в приложении HyperDX. Вы можете задать ей любое удобное вам имя.

Запуск приложения с Python-агентом OpenTelemetry

Теперь вы можете запустить приложение с Python-агентом OpenTelemetry (opentelemetry-instrument).

opentelemetry-instrument python app.py

Если вы используете Gunicorn, uWSGI или uvicorn

В этом случае для корректной работы агента OpenTelemetry для Python потребуются дополнительные изменения.

Чтобы настроить OpenTelemetry для серверов приложений, использующих режим веб-сервера pre-fork, убедитесь, что вызываете метод configure_opentelemetry внутри хука post-fork.

Gunicorn

from hyperdx.opentelemetry import configure_opentelemetry

def post_fork(server, worker):
    configure_opentelemetry()

uWSGI

from hyperdx.opentelemetry import configure_opentelemetry
from uwsgidecorators import postfork

@postfork
def init_tracing():
    configure_opentelemetry()

uvicorn

OpenTelemetry в настоящее время не работает с uvicorn, запущенным с флагом --reload или при использовании нескольких воркеров (--workers). Рекомендуем отключить эти флаги во время тестирования или использовать Gunicorn.

Расширенная конфигурация

Захват сетевого трафика

Включив функции захвата сетевого трафика, разработчики получают возможность эффективно отлаживать заголовки и тела HTTP‑запросов. Это можно сделать, просто установив флаг HYPERDX_ENABLE_ADVANCED_NETWORK_CAPTURE в 1.

export HYPERDX_ENABLE_ADVANCED_NETWORK_CAPTURE=1

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

Логи не отображаются из-за уровня логирования

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

import logging

logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)

Экспорт в консоль

OpenTelemetry Python SDK обычно отображает ошибки в консоли при их возникновении. Однако если вы не сталкиваетесь с какими-либо ошибками, но замечаете, что ваши данные не появляются в HyperDX, как ожидалось, вы можете включить режим отладки. Когда режим отладки активирован, вся телеметрия будет выводиться в консоль, что позволяет проверить, корректно ли ваше приложение проинструментировано и передаёт ожидаемые данные.

export DEBUG=true

Подробнее об инструментировании Python с OpenTelemetry см. здесь: https://opentelemetry.io/docs/instrumentation/python/manual/