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
79
i18n/ja/pages/handlers/logging.md
Normal file
79
i18n/ja/pages/handlers/logging.md
Normal file
|
|
@ -0,0 +1,79 @@
|
|||
---
|
||||
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** サーバーでは、この問いがいつも以上に重要です。ホストはサーバーをサブプロセスとして起動し、その **stdout** から MCP メッセージを読み取っています。標準エラーは自由に使えます。
|
||||
|
||||
標準ライブラリは最初から正しく動作します。ログ出力はデフォルトで `sys.stderr` に送られます。`logger.info(...)` の行はターミナル(またはホストがサブプロセスの stderr を集める場所)に届き、プロトコルのストリームはきれいなまま保たれます。
|
||||
|
||||
!!! tip
|
||||
stdio サーバーで `print()` を使わないでください。`print` は **stdout** に書き込みますが、stdout はプロトコルのものです。サーバーの稼働中、SDK は実際に「フラッシュされた」stdout を stderr へ振り向けるので、通信路を壊すことはありません。しかし、ブロックバッファリングされたプロセスでの `print()` は、たいていフラッシュされないまま `sys.stdout` のバッファに残り、終了時にインタープリターがそれを吐き出すと、そのままプロトコルのストリームに流れ込みます。振り向けられた場合でも、その行はレベルもロガー名もなく、フィルターする手段もないまま、生の状態でログ出力の中に紛れ込みます。
|
||||
|
||||
`logger.debug("got here")` なら同じ 1 行の手間で、正しい場所に出力されます。
|
||||
|
||||
## レベル {#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
|
||||
```
|
||||
|
||||
**Tools** タブから `search_books` を呼び出してください。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