OpenTelemetry¶

Коли ваш API працює, вам може бути потрібно знати, скільки трафіку він отримує, які запити повільні та коли виникають помилки.

Телеметрія - це дані про поведінку вашого застосунку, які допомагають відповісти на ці запитання. Поширені типи:

• Метрики: вимірювання, які можна узагальнювати за певний час, як-от час відповіді та кількість оброблюваних запитів.
• Трасування: записи окремих запитів і операцій, виконаних для їх обробки. Кожна операція з виміряною тривалістю називається span.
• Журнали: записи подій із часовими мітками, як-от запуск застосунку або збій операції.

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 ви можете переглядати кількість запитів, частоту помилок і час відповіді на панелі метрик.

Інші сервіси моніторингу¶

Щоб надсилати телеметрію до іншого сервісу моніторингу, налаштуйте кінцеву точку, яка приймає OTLP, протокол OpenTelemetry для надсилання телеметрії. Використовуйте базову кінцеву точку HTTP/protobuf цього сервісу.

Задайте ці змінні оточення, замінивши URL із прикладу на вашу кінцеву точку:

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

FASTAPI_OTEL_AUTO_CONFIGURE=true вмикає автоматичне налаштування експортерів у FastAPI. OTEL_SERVICE_NAME ідентифікує ваш застосунок у сервісі моніторингу. Кінцева точка - це базовий URL для отримання даних. Трасування надсилаються до /v1/traces, метрики - до /v1/metrics, а журнали - до /v1/logs за цим URL.

Якщо ваш сервіс вимагає автентифікації, задайте в OTEL_EXPORTER_OTLP_HEADERS заголовки, які він визначає, наприклад api-key=YOUR_API_KEY.

Запустіть застосунок¶

Запустіть застосунок у тому самому терміналі:

$ uv run fastapi run

В іншому терміналі надішліть запит:

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

Відкрийте ваш сервіс моніторингу та знайдіть my-api. Після наступного експорту ви зможете побачити трасування зі span GET /items/{item_id}, а також метрики кількості запитів, тривалості відповіді та активних запитів.

Налаштуйте телеметрію¶

Налаштуйте провайдери та експортери¶

Провайдер надає об'єкти, які записують трасування, метрики або журнали. Його конфігурація визначає, як ці дані обробляються та експортуються.

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

За замовчуванням FastAPI використовує налаштовані провайдери без додавання експортерів. Коли автоматичне налаштування ввімкнено й кінцеву точку OTLP задано в оточенні, FastAPI додає експортер для цього місця призначення до кожного ввімкненого провайдера. Наявні експортери продовжують надсилати дані до своїх місць призначення.

Якщо інша бібліотека вже налаштовує експорт до того самого місця призначення, залиште FASTAPI_OTEL_AUTO_CONFIGURE незаданою або задайте їй значення false, щоб уникнути дублювання телеметрії.

Ви також можете передати провайдер безпосередньо у словнику telemetry. Наприклад, цей провайдер використовує консольний експортер OpenTelemetry для виведення span запитів у вашому терміналі:

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}

Експортер надсилає span до їхнього місця призначення. BatchSpanProcessor групує span і надсилає їх у фоновому режимі. Замініть консольний експортер на той, який надає ваша бібліотека моніторингу, щоб використовувати її місце призначення. Додаткові параметри налаштування наведено в посібнику з інструментування Python для OpenTelemetry.

Використовуйте meter_provider або logger_provider у тому самому словнику, щоб надати провайдер метрик або журналів. Застосунок або бібліотека, що створює провайдер, керує його вимкненням. FastAPI керує компонентами експорту, які додає.

Трасуйте операції запитів¶

За замовчуванням трасування запитів включають span для розв'язання залежностей, виконання вашої функції операції шляху, серіалізації відповіді та виконання кожного завдання у BackgroundTasks FastAPI. Ці span використовують ті самі провайдер і експортери.

Span фонових завдань залишаються частиною трасування запиту. Вони виконуються після завершення span HTTP-відповіді, тому не збільшують виміряний час відповіді.

Щоб записувати лише span 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 має span, наприклад WS /ws/{room}, що охоплює обробник і очищення залежностей. Він використовує ті самі провайдери й налаштування, включно з operation_spans для розв'язання залежностей і виконання кінцевої точки.

Метрики HTTP-запитів охоплюють лише HTTP-запити. Звичайні від'єднання WebSocket із кодами 1000 або 1001 не створюють записів про помилки в журналах.

Переглядайте помилки¶

FastAPI записує необроблені винятки як журнали OpenTelemetry, пов'язані з трасуванням запиту або з'єднання. Помилки записуються в журнали, навіть коли трасування не потрапляє до вибірки.

Записи винятків у журналах містять тип винятку, повідомлення та трасування стека. Повідомлення та трасування стека можуть містити конфіденційну інформацію. Використовуйте процесори журналів вашого провайдера для фільтрування або приховування такої інформації або задайте logs значення False, щоб вимкнути ці журнали.

FastAPI також записує помилки валідації запитів як попередження в журналах із маршрутом і кількістю помилок. Ці записи не містять некоректних вхідних даних.

Виберіть, що записувати¶

Словник telemetry також приймає такі налаштування:

Наприклад, щоб збирати метрики, виключаючи перевірки працездатності:

from fastapi import FastAPI

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

Явно задане значення auto_configure у словнику telemetry має пріоритет над FASTAPI_OTEL_AUTO_CONFIGURE. Використовуйте telemetry={"auto_configure": True}, щоб увімкнути автоматичне налаштування в коді, або telemetry={"auto_configure": False}, щоб вимкнути його для застосунку, навіть коли змінна оточення його вмикає.