Усунення проблем з автоматичним інструментуванням в Python

Проблеми з установкою

Проблеми встановлення пакунків Python

Встановлення пакунків Python вимагає наявності gcc та gcc-c++, які можливо потрібно встановити, якщо ви використовуєте спрощену версію Linux, таку як CentOS.

• CentOS
• Debian/Ubuntu
• Alpine

yum -y install python3-devel
yum -y install gcc-c++

apt install -y python3-dev
apt install -y build-essential

apk add python3-dev
apk add build-base

Bootstrap з використанням uv

При використанні менеджера пакунків uv, ви можете поставати перед труднощами при виконанні opentelemetry-bootstrap -a install.

Замість цього ви можете згенерувати вимоги OpenTelemetry динамічно і встановити їх за допомогою їх за допомогою uv.

Спочатку встановіть відповідні пакунки (або додайте їх до файлу проєкту та виконайте uv sync):

uv pip install opentelemetry-distro opentelemetry-exporter-otlp

Тепер ви можете встановити автоматичне інструментування:

uv run opentelemetry-bootstrap -a requirements | uv pip install --requirement -

Нарешті, використовуйте uv run для запуску вашого застосунку (дивіться Налаштування агента):

uv run opentelemetry-instrument python myapp.py

Зверніть увагу, що вам потрібно перевстановлювати автоматичне інструментування кожного разу, коли ви виконуєте uv sync або оновлюєте наявні пакунки. Тому рекомендується зробити встановлення частиною вашого процесу збірки.

Проблеми інструментування

Режим налагодження Flask з перезавантажувачем ламає інструментування

Режим налагодження можна увімкнути в застосунку Flask ось так:

if __name__ == "__main__":
    app.run(port=8082, debug=True)

Режим налагодження може зламати інструментування, оскільки він вмикає перезавантажувач. Щоб запустити інструментування під час увімкненого режиму налагодження, встановіть параметр use_reloader в False:

if __name__ == "__main__":
    app.run(port=8082, debug=True, use_reloader=False)

Проблеми з сервером попереднього розгалуження (pre-fork server)

Сервер попереднього розгалуження, такий як Gunicorn з кількома виконавцями, може бути запущений так:

gunicorn myapp.main:app --workers 4

Однак вказання більше ніж одного --workers може порушити генерацію метрик, коли застосовується автоматичне інструментування. Це повʼязано з тим, що розгалуження, створення робочих/дочірніх процесів, створює несумісності між кожною дитиною в фонових потоках і блокуваннями, які передбачаються ключовими компонентами SDK OpenTelemetry. Зокрема, PeriodicExportingMetricReader створює свій власний потік для періодичного скидання даних експортеру. Дивіться також тікети #2767 та #3307. Після розгалуження кожен дочірній процес шукає обʼєкт потоку в памʼяті, який насправді не виконується, і будь-які оригінальні блокування можуть не розблокуватися для кожного нащадка. Дивіться також, розгалуження та блокування, описані в Python issue 6721.

Способи вирішення проблеми

Існують деякі способи вирішення проблеми для серверів попереднього розгалуження з OpenTelemetry. У наступній таблиці наведено підсумок поточної підтримки експорту сигналів різними стеками шлюзів вебсерверів з автоматичною інструментацією, які були попередньо розгалужені з декількома робочими процесами. Дивіться нижче для отримання додаткової інформації та варіантів:

Розгортання з Gunicorn та UvicornWorker

Щоб автоматично інструментувати сервер з декількома робочими процесами, рекомендується робити розгортання використовуючи Gunicorn з uvicorn.workers.UvicornWorker, якщо це застосунок Asynchronous Server Gateway Interface (ASGI) (FastAPI, Starlette тощо). Клас UvicornWorker спеціально створений для обробки розгалужень зі збереженням фонових процесів і потоків. Наприклад:

opentelemetry-instrument gunicorn \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000 \
  myapp.main:app

Використовуйте програмне автоінструментування

Ініціалізуйте OpenTelemetry всередині процесу робочого потоку з програмним автоінструментуванням після розгалуження сервера, замість використання opentelemetry-instrument. Наприклад:

from opentelemetry.instrumentation.auto_instrumentation import initialize
initialize()

from your_app import app

Якщо ви використовуєте FastAPI, зверніть увагу, що initialize() необхідно викликати перед імпортом FastAPI через особливості латок інструментування. Наприклад:

from opentelemetry.instrumentation.auto_instrumentation import initialize
initialize()

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

Потім запустіть сервер за допомогою:

uvicorn main:app --workers 2

Використовуйте Prometheus безпосередньо з OTLP

Розгляньте можливість використання останньої версії Prometheus для отримання OTLP метрик безпосередньо. Налаштуйте PeriodicExportingMetricReader і одного OTLP виконавця на процес, щоб надсилати дані на сервер Prometheus. Ми рекомендуємо не використовувати PrometheusMetricReader з розгалуженнями — див. тікет #3747.

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

Альтернативно, використовуйте одного виконавця в режимі попереднього розгалуження з інструментуванням без коду:

opentelemetry-instrument gunicorn your_app:app --workers 1

Проблеми з підключенням

Підключення gRPC

Щоб відстежити проблеми підключення Python gRPC, встановіть наступні змінні середовища налагодження gRPC:

export GRPC_VERBOSITY=debug
export GRPC_TRACE=http,call_error,connectivity_state
opentelemetry-instrument python YOUR_APP.py