Python

Python для ClickStack — стек обсервабилити ClickHouse

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

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

• Журналы
• Метрики
• Трассировки

​

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

​

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

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

pip install hyperdx-opentelemetry

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

opentelemetry-bootstrap -a install

​

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

После этого настройте в вашей оболочке следующие переменные окружения, чтобы отправлять телеметрию в ClickStack через OpenTelemetry Collector:

Управляемый ClickStack

OTEL_SERVICE_NAME='<NAME_OF_YOUR_APP_OR_SERVICE>' \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 

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; ей можно присвоить любое имя.

​

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

Теперь вы можете запустить приложение с помощью агента OpenTelemetry Python (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)

​

Вывод в консоль

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

export DEBUG=true

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