docs: publish translated docs in twelve languages and the tool that maintains them (#3280)
This commit is contained in:
parent
14aa889992
commit
52ad0a8876
1 changed files with 89737 additions and 54 deletions
87
i18n/ru/pages/handlers/logging.md
Normal file
87
i18n/ru/pages/handlers/logging.md
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
---
|
||||
translation:
|
||||
sections: [c93a3e1aefd77955, 7851abd5ec54393b, f49d1ca2f330f9cd, c03764bd9dfeef7b, 4a0391691a674ae4, 2df5cd279eabf9f5]
|
||||
tool: 1
|
||||
---
|
||||
# Логирование {#logging}
|
||||
|
||||
Пишите в лог из инструмента так же, как из любой другой функции Python: средствами стандартной библиотеки.
|
||||
|
||||
В MCP есть **возможность логирования** на уровне протокола: сервер мог отправлять свои сообщения лога клиенту в виде уведомлений через методы объекта `Context`. Ревизия спецификации 2026-07-28 **объявляет эту возможность устаревшей и ничем её не заменяет**, поэтому в этой документации она не описывается. Полный список того, что устарело и что делать взамен, — на странице **[Устаревшие возможности](../deprecated.md)**.
|
||||
|
||||
Взамен делайте то же, что в любой другой программе на Python: используйте стандартную библиотеку.
|
||||
|
||||
## Инструмент, который пишет в лог {#a-tool-that-logs}
|
||||
|
||||
```python title="server.py" hl_lines="1 5 13"
|
||||
--8<-- "docs_src/logging/tutorial001.py"
|
||||
```
|
||||
|
||||
* `logging.getLogger(__name__)` возвращает логгер, названный по имени модуля. Создайте его один раз, в начале файла.
|
||||
* Внутри инструмента вызывайте `logger.info(...)`, как в любой другой функции. Ничего не нужно внедрять, ничего не нужно ждать через `await`, ничего специфичного для MCP.
|
||||
|
||||
!!! check
|
||||
Вызовите инструмент и посмотрите на результат целиком:
|
||||
|
||||
```python
|
||||
result.content # [TextContent(text="Found 3 books matching 'dune'.")]
|
||||
result.structured_content # {'result': "Found 3 books matching 'dune'."}
|
||||
```
|
||||
|
||||
Строки лога в нём нет нигде. Логи — для **вас**, того, кто эксплуатирует сервер. Модель
|
||||
их никогда не видит. Если модель должна что-то прочитать, верните это через `return`.
|
||||
|
||||
## Куда попадает вывод {#where-it-goes}
|
||||
|
||||
Для сервера на **stdio** этот вопрос важнее обычного. Хост запустил ваш сервер как подпроцесс и читает MCP-сообщения из его **stdout**. Стандартный поток ошибок — ваш.
|
||||
|
||||
Стандартная библиотека уже поступает правильно: по умолчанию вывод логов идёт в `sys.stderr`. Строки из `logger.info(...)` попадают в терминал (или туда, куда хост собирает stderr подпроцесса), а поток протокола остаётся чистым.
|
||||
|
||||
!!! tip
|
||||
Не используйте `print()` в stdio-сервере. `print` пишет в **stdout**, а stdout принадлежит протоколу.
|
||||
Пока сервер работает, SDK перенаправляет в stderr то, что действительно *сброшено* из буфера stdout,
|
||||
так что испортить передаваемые данные это не может. Но в процессе с блочной буферизацией вывод
|
||||
`print()` обычно лежит несброшенным в буфере `sys.stdout`, пока интерпретатор не опустошит его
|
||||
при выходе — прямо в поток протокола. И даже когда строка перенаправлена, она попадает в вывод
|
||||
логов как есть: без уровня, без имени логгера и без возможности её отфильтровать.
|
||||
|
||||
`logger.debug("got here")` — те же усилия на одну строку, и попадает она куда нужно.
|
||||
|
||||
## Уровень {#the-level}
|
||||
|
||||
Вызывать `logging.basicConfig()` самостоятельно не нужно. Конструктор `MCPServer` уже сделал это: с обработчиком, направленным в стандартный поток ошибок, и с уровнем, который вы передаёте в `log_level=`. Так что `MCPServer("Bookshop", log_level="DEBUG")` — всё, что нужно, чтобы увидеть строки из `logger.debug(...)`.
|
||||
|
||||
По умолчанию — `"INFO"`.
|
||||
|
||||
`logging.basicConfig()` никогда не заменяет уже существующие обработчики. Если настроить логирование самостоятельно до создания сервера, ваша конфигурация имеет приоритет.
|
||||
|
||||
## Попробуйте сами {#try-it}
|
||||
|
||||
Запустите сервер через MCP Inspector:
|
||||
|
||||
```console
|
||||
uv run mcp dev server.py
|
||||
```
|
||||
|
||||
Вызовите `search_books` на вкладке **Tools**. Inspector показывает результат: только возвращённое значение. Строка
|
||||
|
||||
```text
|
||||
Searching for 'dune'
|
||||
```
|
||||
|
||||
ушла в стандартный поток ошибок: в терминал, а не в передаваемые данные.
|
||||
|
||||
!!! info
|
||||
Если на самом деле нужна *трассировка* (каждый запрос, сколько он занял, завершился ли ошибкой),
|
||||
нужны не строки лога, а спаны. Сервер уже их выдаёт: SDK по умолчанию трассирует каждое
|
||||
сообщение с помощью OpenTelemetry. См. **[OpenTelemetry](../run/opentelemetry.md)**.
|
||||
|
||||
## Итоги {#recap}
|
||||
|
||||
* Возможность логирования в протоколе MCP объявлена устаревшей в спецификации 2026-07-28 и ничем не заменена. Не стройте на ней ничего.
|
||||
* `logger = logging.getLogger(__name__)` на уровне модуля, `logger.info(...)` в инструменте. Вот и весь паттерн.
|
||||
* Вывод логов никогда не доходит до модели. Доходит только значение, которое вы возвращаете через `return`.
|
||||
* Стандартный поток ошибок — ваш; stdout принадлежит протоколу. Пока сервер работает, SDK перенаправляет сброшенный посторонний вывод из stdout в stderr, но несброшенный `print()` всё равно может вылиться в поток протокола при выходе, а перенаправленные строки приходят без меток. Используйте `logging` — его обработчик сбрасывает буфер после каждой записи.
|
||||
* `MCPServer(..., log_level="DEBUG")` задаёт уровень, а конфигурацию логирования, которую вы сделали раньше, не трогает.
|
||||
|
||||
О том, как сообщить подключённым клиентам, что на сервере что-то изменилось (список инструментов, ресурс), — на странице **[Подписки](subscriptions.md)**.
|
||||
Loading…
Reference in a new issue