OpenTelemetry¶

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

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

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

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

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

Установите FastAPI¶

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

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

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

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

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

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

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-запросов в вашем терминале:

from fastapi import FastAPI
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter

tracer_provider = TracerProvider()
tracer_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

app = FastAPI(telemetry={"tracer_provider": tracer_provider})


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

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

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

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

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

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

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

from fastapi import FastAPI

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


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

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

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

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

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

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

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

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

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

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

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

from fastapi import FastAPI

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

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