mirror of
https://github.com/fastapi/fastapi.git
synced 2026-10-08 19:21:32 -04:00
🌐 Update translations for uk (add-missing) (#16429)
Co-authored-by: pr-submit[bot] <pr-submit[bot]@users.noreply.github.com> Co-authored-by: Yurii Motov <yurii.motov.monte@gmail.com>
This commit is contained in:
1 file changed
+161
@@ -0,0 +1,161 @@
|
||||
# OpenTelemetry { #opentelemetry }
|
||||
|
||||
Коли ваш API працює, вам може бути потрібно знати, скільки трафіку він отримує, які запити повільні та коли виникають помилки.
|
||||
|
||||
**Телеметрія** - це дані про поведінку вашого застосунку, які допомагають відповісти на ці запитання. Поширені типи:
|
||||
|
||||
- **Метрики**: вимірювання, які можна узагальнювати за певний час, як-от час відповіді та кількість оброблюваних запитів.
|
||||
- **Трасування**: записи окремих запитів і операцій, виконаних для їх обробки. Кожна операція з виміряною тривалістю називається **span**.
|
||||
- **Журнали**: записи подій із часовими мітками, як-от запуск застосунку або збій операції.
|
||||
|
||||
[**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 ви можете переглядати кількість запитів, частоту помилок і час відповіді на [панелі метрик](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` заголовки, які він визначає, наприклад `api-key=YOUR_API_KEY`.
|
||||
|
||||
## Запустіть застосунок { #run-the-app }
|
||||
|
||||
Запустіть застосунок у тому самому терміналі:
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ uv run fastapi run
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
В іншому терміналі надішліть запит:
|
||||
|
||||
```console
|
||||
$ curl http://127.0.0.1:8000/items/1
|
||||
{"item_id":1}
|
||||
```
|
||||
|
||||
Відкрийте ваш сервіс моніторингу та знайдіть `my-api`. Після наступного експорту ви зможете побачити трасування зі span `GET /items/{item_id}`, а також метрики кількості запитів, тривалості відповіді та активних запитів.
|
||||
|
||||
## Налаштуйте телеметрію { #customize-telemetry }
|
||||
|
||||
### Налаштуйте провайдери та експортери { #configure-providers-and-exporters }
|
||||
|
||||
**Провайдер** надає об'єкти, які записують трасування, метрики або журнали. Його конфігурація визначає, як ці дані обробляються та експортуються.
|
||||
|
||||
Бібліотеки телеметрії можуть налаштовувати глобальні провайдери OpenTelemetry. Налаштуйте бібліотеку перед запуском застосунку, і FastAPI автоматично використовуватиме ці провайдери.
|
||||
|
||||
Коли кінцеву точку OTLP задано в оточенні, FastAPI додає експортер для цього місця призначення до кожного ввімкненого провайдера. Наявні експортери продовжують надсилати дані до своїх місць призначення.
|
||||
|
||||
Налаштовуйте кожне місце призначення лише один раз. Якщо інша бібліотека вже обробляє місце призначення, задане в оточенні, вимкніть у ній експорт за налаштуваннями оточення або вимкніть автоматичне налаштування FastAPI:
|
||||
|
||||
```python
|
||||
app = FastAPI(telemetry={"auto_configure": False})
|
||||
```
|
||||
|
||||
Ви також можете передати провайдер безпосередньо у словнику `telemetry`. Наприклад, цей провайдер використовує консольний експортер OpenTelemetry для виведення span запитів у вашому терміналі:
|
||||
|
||||
{* ../../docs_src/opentelemetry/tutorial002_py310.py hl[2:8] *}
|
||||
|
||||
**Експортер** надсилає span до їхнього місця призначення. `BatchSpanProcessor` групує span і надсилає їх у фоновому режимі. Замініть консольний експортер на той, який надає ваша бібліотека моніторингу, щоб використовувати її місце призначення. Додаткові параметри налаштування наведено в [посібнику з інструментування Python для OpenTelemetry](https://opentelemetry.io/docs/languages/python/instrumentation/).
|
||||
|
||||
Використовуйте `meter_provider` або `logger_provider` у тому самому словнику, щоб надати провайдер метрик або журналів. Застосунок або бібліотека, що створює провайдер, керує його вимкненням. FastAPI керує компонентами експорту, які додає.
|
||||
|
||||
/// warning | Попередження
|
||||
|
||||
OpenTelemetry за замовчуванням використовує глобальні провайдери. Незалежне налаштування телеметрії для [змонтованих підзастосунків](sub-applications.md) не гарантоване.
|
||||
|
||||
///
|
||||
|
||||
### Трасуйте операції запитів { #trace-request-operations }
|
||||
|
||||
За замовчуванням трасування запитів включають span для розв'язання залежностей, виконання вашої функції операції шляху, серіалізації відповіді та виконання кожного завдання у `BackgroundTasks` FastAPI. Ці span використовують ті самі провайдер і експортери.
|
||||
|
||||
Span фонових завдань залишаються частиною трасування запиту. Вони виконуються після завершення span HTTP-відповіді, тому не збільшують виміряний час відповіді.
|
||||
|
||||
Щоб записувати лише span HTTP-запиту, задайте `operation_spans` значення `False`:
|
||||
|
||||
{* ../../docs_src/opentelemetry/tutorial003_py310.py hl[3] *}
|
||||
|
||||
|
||||
### Трасуйте з'єднання WebSocket { #trace-websocket-connections }
|
||||
|
||||
Кожне з'єднання WebSocket має span, наприклад `WS /ws/{room}`, що охоплює обробник і очищення залежностей. Він використовує ті самі провайдери й налаштування, включно з `operation_spans` для розв'язання залежностей і виконання кінцевої точки.
|
||||
|
||||
Метрики HTTP-запитів охоплюють лише HTTP-запити. Звичайні від'єднання WebSocket із кодами `1000` або `1001` не створюють записів про помилки в журналах.
|
||||
|
||||
### Переглядайте помилки { #inspect-errors }
|
||||
|
||||
FastAPI записує необроблені винятки як журнали OpenTelemetry, пов'язані з трасуванням запиту або з'єднання. Помилки записуються в журнали, навіть коли трасування не потрапляє до вибірки.
|
||||
|
||||
Записи винятків у журналах містять тип винятку, повідомлення та трасування стека. Повідомлення та трасування стека можуть містити конфіденційну інформацію. Використовуйте процесори журналів вашого провайдера для фільтрування або приховування такої інформації або задайте `logs` значення `False`, щоб вимкнути ці журнали.
|
||||
|
||||
FastAPI також записує помилки валідації запитів як попередження в журналах із маршрутом і кількістю помилок. Ці записи не містять некоректних вхідних даних.
|
||||
|
||||
## Виберіть, що записувати { #choose-what-to-record }
|
||||
|
||||
Словник `telemetry` також приймає такі налаштування:
|
||||
|
||||
| Налаштування | Призначення | За замовчуванням |
|
||||
| --- | --- | --- |
|
||||
| `tracing` | Записувати span HTTP-запитів і з'єднань WebSocket | `True` |
|
||||
| `metrics` | Записувати метрики HTTP-запитів | `True` |
|
||||
| `logs` | Записувати помилки валідації та необроблені винятки | `True` |
|
||||
| `operation_spans` | Додавати span для операцій запитів | `True` |
|
||||
| `exclude` | Пропускати запити, коли функція, що отримує 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`, коли ваш застосунок самостійно налаштовує провайдери, наприклад у своїй функції тривалості життя.
|
||||
Reference in new issue
Block a user