Перейти к основному содержимому
Перейти к основному содержимому

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='<YOUR_INGESTION_API_KEY>' \
OTEL_SERVICE_NAME='<NAME_OF_YOUR_APP_OR_SERVICE>' \
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​

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

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

from hyperdx.opentelemetry import configure_opentelemetry

def post_fork(server, worker):
    configure_opentelemetry()

Расширенная настройка​

Сетевое захватывание​

Включив функции сетевого захвата, разработчики получают возможность эффективно отлаживать 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

Читать больше о инструментировке OpenTelemetry для Python можно здесь: https://opentelemetry.io/docs/instrumentation/python/manual/