Sync fastapi docs from f5c6e9b4 on 2026-10-11
This commit is contained in:
The Librarian
@@ -0,0 +1,161 @@
|
||||
# OpenTelemetry { #opentelemetry }
|
||||
|
||||
Когда ваш API запущен, вам может понадобиться узнать, сколько трафика он получает, какие HTTP-запросы выполняются медленно и когда происходят ошибки.
|
||||
|
||||
**Телеметрия** — это данные о поведении вашего приложения, которые помогают ответить на эти вопросы. Распространённые типы включают:
|
||||
|
||||
- **Метрики**: измерения, которые можно агрегировать за период времени, например время ответа и количество обрабатываемых HTTP-запросов.
|
||||
- **Трейсы**: записи отдельных HTTP-запросов и операций, выполненных для их обработки. Каждая операция с измеренным временем называется **спан**.
|
||||
- **Логи**: записи событий с временными метками, например запуск приложения или сбой операции.
|
||||
|
||||
[**OpenTelemetry**](https://opentelemetry.io/) — это набор стандартов и инструментов для сбора телеметрии и отправки её в сервис мониторинга, где её можно просматривать на дашбордах.
|
||||
|
||||
**FastAPI по умолчанию предоставляет поддержку OpenTelemetry** для трейсов HTTP-запросов, метрик и логов. WebSocket-соединения также предоставляют трейсы и логи. Чтобы увидеть эти данные, настройте сервис мониторинга для их получения.
|
||||
|
||||
## Установите FastAPI { #install-fastapi }
|
||||
|
||||
Установите FastAPI с дополнительными зависимостями `standard`, которые включают пакеты для отправки телеметрии:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ uv add "fastapi[standard]"
|
||||
---> 100%
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
## Создайте приложение { #create-the-app }
|
||||
|
||||
Создайте файл `main.py`:
|
||||
|
||||
{* ../../docs_src/opentelemetry/tutorial001_py310.py *}
|
||||
|
||||
Обратите внимание, что всё это работает по умолчанию, вам не нужно писать какой-либо пользовательский код, чтобы телеметрия работала.
|
||||
|
||||
## FastAPI Cloud { #fastapi-cloud }
|
||||
|
||||
Когда вы развёртываете приложение в [FastAPI Cloud](https://fastapicloud.com) с `fastapi[standard]`, метрики работают автоматически. Вам не нужно настраивать что-либо ещё.
|
||||
|
||||
На тарифах Pro вы можете просматривать количество HTTP-запросов, долю ошибок и время ответа в [дашборде метрик](https://fastapicloud.com/docs/monitoring-and-performance/metrics/).
|
||||
|
||||
<img src="/img/tutorial/opentelemetry/image01.png" alt="Дашборд метрик FastAPI Cloud Pro с примером данных">
|
||||
|
||||
## Другие сервисы мониторинга { #other-monitoring-services }
|
||||
|
||||
Чтобы отправлять телеметрию в другой сервис мониторинга, настройте эндпоинт, который принимает **OTLP**, протокол OpenTelemetry для отправки телеметрии. Используйте базовый HTTP/protobuf-эндпоинт сервиса.
|
||||
|
||||
Задайте эти переменные окружения, заменив пример URL на ваш эндпоинт:
|
||||
|
||||
```bash
|
||||
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`.
|
||||
|
||||
## Запустите приложение { #run-the-app }
|
||||
|
||||
Запустите приложение в том же терминале:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ uv run fastapi run
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
В другом терминале отправьте HTTP-запрос:
|
||||
|
||||
```console
|
||||
$ curl http://127.0.0.1:8000/items/1
|
||||
{"item_id":1}
|
||||
```
|
||||
|
||||
Откройте ваш сервис мониторинга и найдите `my-api`. После следующего экспорта вы сможете увидеть трейс со спаном `GET /items/{item_id}`, а также метрики количества HTTP-запросов, длительности ответа и активных HTTP-запросов.
|
||||
|
||||
## Настройте телеметрию { #customize-telemetry }
|
||||
|
||||
### Настройте провайдеры и экспортеры { #configure-providers-and-exporters }
|
||||
|
||||
**Провайдер** предоставляет объекты, которые записывают трейсы, метрики или логи. Его конфигурация управляет тем, как эти данные обрабатываются и экспортируются.
|
||||
|
||||
Библиотеки телеметрии могут настраивать глобальные провайдеры OpenTelemetry. Настройте библиотеку до запуска приложения, и FastAPI будет использовать эти провайдеры автоматически.
|
||||
|
||||
Когда OTLP-эндпоинт задан в окружении, FastAPI добавляет экспортер для этого получателя к каждому включённому провайдеру. Существующие экспортеры продолжают отправлять данные своим получателям.
|
||||
|
||||
Настраивайте каждого получателя один раз. Если другая библиотека уже отправляет данные получателю, заданному в окружении, отключите у неё экспорт по настройкам из окружения или выключите автоматическую настройку FastAPI:
|
||||
|
||||
```python
|
||||
app = FastAPI(telemetry={"auto_configure": False})
|
||||
```
|
||||
|
||||
Вы также можете передать провайдер напрямую в словаре `telemetry`. Например, этот провайдер использует консольный экспортер OpenTelemetry, чтобы печатать спаны HTTP-запросов в вашем терминале:
|
||||
|
||||
{* ../../docs_src/opentelemetry/tutorial002_py310.py hl[2:8] *}
|
||||
|
||||
**Экспортер** отправляет спаны их получателю. `BatchSpanProcessor` группирует спаны и отправляет их в фоне. Замените консольный экспортер на экспортер, предоставленный вашей библиотекой мониторинга, чтобы использовать её получателя. См. [руководство OpenTelemetry по инструментированию Python](https://opentelemetry.io/docs/languages/python/instrumentation/) для дополнительных вариантов настройки.
|
||||
|
||||
Используйте `meter_provider` или `logger_provider` в том же словаре, чтобы предоставить провайдер метрик или логов. Приложение или библиотека, создающая провайдер, управляет его завершением работы. FastAPI управляет компонентами экспорта, которые он добавляет.
|
||||
|
||||
/// warning | Предупреждение
|
||||
|
||||
OpenTelemetry по умолчанию использует глобальные провайдеры. Независимая настройка телеметрии для [монтированных подприложений](sub-applications.md) не гарантируется.
|
||||
|
||||
///
|
||||
|
||||
### Трассировка операций HTTP-запроса { #trace-request-operations }
|
||||
|
||||
По умолчанию трейсы HTTP-запросов включают спаны для разрешения зависимостей, запуска вашей функции-обработчика пути, сериализации HTTP-ответа и запуска каждой задачи в `BackgroundTasks` FastAPI. Эти спаны используют тот же провайдер и экспортеры.
|
||||
|
||||
Спаны фоновых задач остаются частью трейса HTTP-запроса. Они выполняются после завершения спана HTTP-ответа, поэтому не увеличивают измеренное время ответа.
|
||||
|
||||
Чтобы записывать только спан HTTP-запроса, установите `operation_spans` в `False`:
|
||||
|
||||
{* ../../docs_src/opentelemetry/tutorial003_py310.py hl[3] *}
|
||||
|
||||
|
||||
### Трассировка WebSocket-соединений { #trace-websocket-connections }
|
||||
|
||||
У каждого WebSocket-соединения есть спан, например `WS /ws/{room}`, охватывающий обработчик и очистку зависимостей. Он использует тех же провайдеров и те же настройки, включая `operation_spans` для разрешения зависимостей и выполнения эндпоинта.
|
||||
|
||||
Метрики HTTP-запросов охватывают только HTTP-запросы. Обычные отключения WebSocket с кодами `1000` или `1001` не создают логи ошибок.
|
||||
|
||||
### Анализ ошибок { #inspect-errors }
|
||||
|
||||
FastAPI записывает необработанные исключения как логи OpenTelemetry, связанные с трейсом HTTP-запроса или соединения. Логи ошибок записываются даже тогда, когда трейс не попал в выборку.
|
||||
|
||||
Логи исключений включают тип исключения, сообщение и трассировку стека. Сообщения и трассировки стека могут содержать конфиденциальную информацию. Используйте процессоры логов вашего провайдера, чтобы фильтровать или редактировать их, либо установите `logs` в `False`, чтобы отключить эти логи.
|
||||
|
||||
FastAPI также записывает ошибки валидации HTTP-запросов как логи уровня предупреждения с маршрутом и количеством ошибок. Эти логи не включают невалидные входные данные.
|
||||
|
||||
## Выберите, что записывать { #choose-what-to-record }
|
||||
|
||||
Словарь `telemetry` также принимает следующие настройки:
|
||||
|
||||
| Настройка | Назначение | По умолчанию |
|
||||
| --- | --- | --- |
|
||||
| `tracing` | Записывать спаны HTTP-запросов и WebSocket-соединений | `True` |
|
||||
| `metrics` | Записывать метрики HTTP-запросов | `True` |
|
||||
| `logs` | Записывать ошибки валидации и необработанные исключения | `True` |
|
||||
| `operation_spans` | Добавлять спаны для операций HTTP-запроса | `True` |
|
||||
| `exclude` | Пропускать HTTP-запросы, когда функция, получающая ASGI scope, возвращает `True` | `None` |
|
||||
| `auto_configure` | Добавлять экспортеры для эндпоинтов, заданных в переменных окружения | `True` |
|
||||
|
||||
Например, чтобы собирать метрики, исключая проверки работоспособности:
|
||||
|
||||
```python
|
||||
from fastapi import FastAPI
|
||||
|
||||
app = FastAPI(
|
||||
telemetry={
|
||||
"tracing": False,
|
||||
"exclude": lambda scope: scope["path"] == "/health",
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
Установите `auto_configure` в `False`, когда ваше приложение самостоятельно выполняет настройку провайдера, например внутри своей lifespan-функции.
|
||||
@@ -8,6 +8,8 @@ Use a neutral tone (not overly formal or informal).
|
||||
|
||||
Use correct Russian grammar — appropriate cases, suffixes, and endings depending on context.
|
||||
|
||||
Translate technical terms in prose unless explicitly instructed otherwise below. If there is no commonly used Russian equivalent, use a Russified English term, optionally adding a short Russian explanation. Preserve code identifiers, API names, and protocol names.
|
||||
|
||||
For the following technical terms, use these specific translations to ensure consistency and clarity across the documentation:
|
||||
|
||||
* production (meaning production software or environment): продакшн (do not change the ending, for example, translate `in production` as `в продакшн` (not `в продакшене`))
|
||||
@@ -48,6 +50,15 @@ For the following technical terms, use these specific translations to ensure con
|
||||
* media type: тип содержимого (or `медиа-тип`)
|
||||
* request: HTTP-запрос
|
||||
* response: HTTP-ответ
|
||||
* endpoint: эндпоинт (for example, `OTLP-эндпоинт`)
|
||||
* handler: обработчик
|
||||
* span (in tracing): спан (add `отрезок трассировки` if clarification is needed)
|
||||
* stack trace: трассировка стека
|
||||
* warning logs: логи уровня предупреждения
|
||||
* destination (meaning a telemetry destination): получатель (for example, `отправлять данные получателю`, not `отправлять данные в назначение`)
|
||||
* trace is not sampled: трейс не попал в выборку
|
||||
* sensitive information: конфиденциальная информация
|
||||
* health check: проверка работоспособности (or `проверка состояния`)
|
||||
* type hints: аннотации типов
|
||||
* type annotations: аннотации типов
|
||||
* context manager: менеджер контекста
|
||||
|
||||
Reference in New Issue
Block a user