From c972176846392986cd07e6da49c9e3aedbcb290a Mon Sep 17 00:00:00 2001 From: "pr-submit[bot]" <314742883+pr-submit[bot]@users.noreply.github.com> Date: Fri, 2 Oct 2026 13:12:54 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=8C=90=20Update=20translations=20for=20uk?= =?UTF-8?q?=20(add-missing)=20(#16429)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: pr-submit[bot] Co-authored-by: Yurii Motov --- docs/uk/docs/advanced/opentelemetry.md | 161 +++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 docs/uk/docs/advanced/opentelemetry.md diff --git a/docs/uk/docs/advanced/opentelemetry.md b/docs/uk/docs/advanced/opentelemetry.md new file mode 100644 index 0000000000..7264c3522e --- /dev/null +++ b/docs/uk/docs/advanced/opentelemetry.md @@ -0,0 +1,161 @@ +# OpenTelemetry { #opentelemetry } + +Коли ваш API працює, вам може бути потрібно знати, скільки трафіку він отримує, які запити повільні та коли виникають помилки. + +**Телеметрія** - це дані про поведінку вашого застосунку, які допомагають відповісти на ці запитання. Поширені типи: + +- **Метрики**: вимірювання, які можна узагальнювати за певний час, як-от час відповіді та кількість оброблюваних запитів. +- **Трасування**: записи окремих запитів і операцій, виконаних для їх обробки. Кожна операція з виміряною тривалістю називається **span**. +- **Журнали**: записи подій із часовими мітками, як-от запуск застосунку або збій операції. + +[**OpenTelemetry**](https://opentelemetry.io/) - це набір стандартів та інструментів для збирання телеметрії та надсилання її до сервісу моніторингу, де ви можете переглядати її на інформаційних панелях. + +**FastAPI надає підтримку OpenTelemetry за замовчуванням** для трасувань, метрик і журналів HTTP-запитів. З'єднання WebSocket також надають трасування та журнали. Щоб переглядати ці дані, налаштуйте сервіс моніторингу для їх отримання. + +## Встановіть FastAPI { #install-fastapi } + +Встановіть FastAPI з додатковими залежностями `standard`, які включають пакети для надсилання телеметрії: + +
+ +```console +$ uv add "fastapi[standard]" +---> 100% +``` + +
+ +## Створіть застосунок { #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/). + +Панель метрик 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 } + +Запустіть застосунок у тому самому терміналі: + +
+ +```console +$ uv run fastapi run +``` + +
+ +В іншому терміналі надішліть запит: + +```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`, коли ваш застосунок самостійно налаштовує провайдери, наприклад у своїй функції тривалості життя.