docs-fastapi/docs/ru/docs/advanced/opentelemetry.md

OpenTelemetry

Когда ваш API запущен, вам может понадобиться узнать, сколько трафика он получает, какие HTTP-запросы выполняются медленно и когда происходят ошибки.

Телеметрия — это данные о поведении вашего приложения, которые помогают ответить на эти вопросы. Распространённые типы включают:

• Метрики: измерения, которые можно агрегировать за период времени, например время ответа и количество обрабатываемых HTTP-запросов.
• Трейсы: записи отдельных HTTP-запросов и операций, выполненных для их обработки. Каждая операция с измеренным временем называется спан.
• Логи: записи событий с временными метками, например запуск приложения или сбой операции.

OpenTelemetry — это набор стандартов и инструментов для сбора телеметрии и отправки её в сервис мониторинга, где её можно просматривать на дашбордах.

FastAPI по умолчанию предоставляет поддержку OpenTelemetry для трейсов HTTP-запросов, метрик и логов. WebSocket-соединения также предоставляют трейсы и логи. Чтобы увидеть эти данные, настройте сервис мониторинга для их получения.

Установите FastAPI

Установите FastAPI с дополнительными зависимостями standard, которые включают пакеты для отправки телеметрии:

$ uv add "fastapi[standard]"
---> 100%

Создайте приложение

Создайте файл main.py:

{* ../../docs_src/opentelemetry/tutorial001_py310.py *}

Обратите внимание, что всё это работает по умолчанию, вам не нужно писать какой-либо пользовательский код, чтобы телеметрия работала.

FastAPI Cloud

Когда вы развёртываете приложение в FastAPI Cloud с fastapi[standard], метрики работают автоматически. Вам не нужно настраивать что-либо ещё.

На тарифах Pro вы можете просматривать количество HTTP-запросов, долю ошибок и время ответа в дашборде метрик.

Другие сервисы мониторинга

Чтобы отправлять телеметрию в другой сервис мониторинга, настройте эндпоинт, который принимает OTLP, протокол OpenTelemetry для отправки телеметрии. Используйте базовый HTTP/protobuf-эндпоинт сервиса.

Задайте эти переменные окружения, заменив пример URL на ваш эндпоинт:

export OTEL_SERVICE_NAME=my-api
export OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.example.com

OTEL_SERVICE_NAME идентифицирует ваше приложение в сервисе мониторинга. Эндпоинт — это базовый URL для получения данных. Трейсы отправляются в /v1/traces, метрики — в /v1/metrics, а логи — в /v1/logs по этому URL.

Если ваш сервис требует аутентификации, задайте OTEL_EXPORTER_OTLP_HEADERS со значением HTTP-заголовков, которые он указывает, например api-key=YOUR_API_KEY.

Запустите приложение

Запустите приложение в том же терминале:

$ uv run fastapi run

В другом терминале отправьте HTTP-запрос:

$ curl http://127.0.0.1:8000/items/1
{"item_id":1}

Откройте ваш сервис мониторинга и найдите my-api. После следующего экспорта вы сможете увидеть трейс со спаном GET /items/{item_id}, а также метрики количества HTTP-запросов, длительности ответа и активных HTTP-запросов.

Настройте телеметрию

Настройте провайдеры и экспортеры

Провайдер предоставляет объекты, которые записывают трейсы, метрики или логи. Его конфигурация управляет тем, как эти данные обрабатываются и экспортируются.

Библиотеки телеметрии могут настраивать глобальные провайдеры OpenTelemetry. Настройте библиотеку до запуска приложения, и FastAPI будет использовать эти провайдеры автоматически.

Когда OTLP-эндпоинт задан в окружении, FastAPI добавляет экспортер для этого получателя к каждому включённому провайдеру. Существующие экспортеры продолжают отправлять данные своим получателям.

Настраивайте каждого получателя один раз. Если другая библиотека уже отправляет данные получателю, заданному в окружении, отключите у неё экспорт по настройкам из окружения или выключите автоматическую настройку FastAPI:

app = FastAPI(telemetry={"auto_configure": False})

Вы также можете передать провайдер напрямую в словаре telemetry. Например, этот провайдер использует консольный экспортер OpenTelemetry, чтобы печатать спаны HTTP-запросов в вашем терминале:

{* ../../docs_src/opentelemetry/tutorial002_py310.py hl[2:8] *}

Экспортер отправляет спаны их получателю. BatchSpanProcessor группирует спаны и отправляет их в фоне. Замените консольный экспортер на экспортер, предоставленный вашей библиотекой мониторинга, чтобы использовать её получателя. См. руководство OpenTelemetry по инструментированию Python для дополнительных вариантов настройки.

Используйте meter_provider или logger_provider в том же словаре, чтобы предоставить провайдер метрик или логов. Приложение или библиотека, создающая провайдер, управляет его завершением работы. FastAPI управляет компонентами экспорта, которые он добавляет.

/// warning | Предупреждение

OpenTelemetry по умолчанию использует глобальные провайдеры. Независимая настройка телеметрии для монтированных подприложений не гарантируется.

///

Трассировка операций HTTP-запроса

По умолчанию трейсы HTTP-запросов включают спаны для разрешения зависимостей, запуска вашей функции-обработчика пути, сериализации HTTP-ответа и запуска каждой задачи в BackgroundTasks FastAPI. Эти спаны используют тот же провайдер и экспортеры.

Спаны фоновых задач остаются частью трейса HTTP-запроса. Они выполняются после завершения спана HTTP-ответа, поэтому не увеличивают измеренное время ответа.

Чтобы записывать только спан HTTP-запроса, установите operation_spans в False:

{* ../../docs_src/opentelemetry/tutorial003_py310.py hl[3] *}

Трассировка WebSocket-соединений

У каждого WebSocket-соединения есть спан, например WS /ws/{room}, охватывающий обработчик и очистку зависимостей. Он использует тех же провайдеров и те же настройки, включая operation_spans для разрешения зависимостей и выполнения эндпоинта.

Метрики HTTP-запросов охватывают только HTTP-запросы. Обычные отключения WebSocket с кодами 1000 или 1001 не создают логи ошибок.

Анализ ошибок

FastAPI записывает необработанные исключения как логи OpenTelemetry, связанные с трейсом HTTP-запроса или соединения. Логи ошибок записываются даже тогда, когда трейс не попал в выборку.

Логи исключений включают тип исключения, сообщение и трассировку стека. Сообщения и трассировки стека могут содержать конфиденциальную информацию. Используйте процессоры логов вашего провайдера, чтобы фильтровать или редактировать их, либо установите logs в False, чтобы отключить эти логи.

FastAPI также записывает ошибки валидации HTTP-запросов как логи уровня предупреждения с маршрутом и количеством ошибок. Эти логи не включают невалидные входные данные.

Выберите, что записывать

Словарь telemetry также принимает следующие настройки:

Настройка	Назначение	По умолчанию
tracing	Записывать спаны HTTP-запросов и WebSocket-соединений	True
metrics	Записывать метрики HTTP-запросов	True
logs	Записывать ошибки валидации и необработанные исключения	True
operation_spans	Добавлять спаны для операций HTTP-запроса	True
exclude	Пропускать HTTP-запросы, когда функция, получающая ASGI scope, возвращает True	None
auto_configure	Добавлять экспортеры для эндпоинтов, заданных в переменных окружения	True

Например, чтобы собирать метрики, исключая проверки работоспособности:

from fastapi import FastAPI

app = FastAPI(
    telemetry={
        "tracing": False,
        "exclude": lambda scope: scope["path"] == "/health",
    }
)

Установите auto_configure в False, когда ваше приложение самостоятельно выполняет настройку провайдера, например внутри своей lifespan-функции.