LogTape .0 での暗黙的コンテキストの導入

LogTape 0.7.0 のリリースを発表できることを嬉しく思います。これは、暗黙的コンテキストを導入するもので、これまで以上に簡単にコンテキスト情報をログに追加できるようにする強力な新機能です。アプリケーション全体。

暗黙的なコンテキストとは何ですか?

アプリケーションで HTTP リクエストを処理していると想像してください。コードベースのどこにログが作成されるかに関係なく、リクエストの処理中に生成されるすべてのログ メッセージにリクエスト ID を含める必要があります。暗黙的なコンテキストを使用する前に、次のことを行う必要があります。

1. すべての関数呼び出しでリクエスト ID を渡します
2. 各モジュールのコンテキストを含む新しいロガーを作成します
3. または、グローバル変数を使用します (これには独自の問題があります)

暗黙的コンテキストを使用すると、リクエスト ハンドラーの先頭でコンテキストを設定できるようになり、その実行コンテキスト内のすべてのログ メッセージにその情報が自動的に含まれるようになります。簡単な例を次に示します:

function handleRequest(requestId: string) {
  withContext({ requestId }, () => {
    // Any log message in this function or any function it calls
    // will automatically include the requestId
    processRequest();
  });
}

function processRequest() {
  // Note that we don't need to pass the requestId explicitly
  getLogger("processor").info(
    "Processing request: {requestId}"
  );
}

どのように機能するのでしょうか?

暗黙的コンテキストは、基盤となるランタイムのコンテキスト ローカル ストレージ メカニズム (Node.js の AsyncLocalStorage など) を使用して、コードの実行全体を通じてコン​​テキスト情報を維持します。これは、非同期操作間でもコンテキストが適切に維持されることを意味します。

アプリケーションで暗黙的コンテキストを有効にするには、コンテキストローカルストレージを使用して LogTape を構成する必要があります。

import { AsyncLocalStorage } from "node:async_hooks";
import { configure } from "@logtape/logtape";

await configure({
  // ... other settings ...
  contextLocalStorage: new AsyncLocalStorage(),
});

ネストされたコンテキストと優先順位

暗黙的コンテキストの強力な機能の 1 つは、ネストできることです。コンテキストをネストすると、内部コンテキストは外部コンテキストの値を継承し、オーバーライドできます:

function handleRequest(requestId: string) {
  withContext({ requestId, stage: "request" }, () => {
    // stage is "request" here
    processUser(1234);
  });
}

function processUser(userId: number) {
  withContext({ userId, stage: "user" }, () => {
    // stage is "user" here, but requestId is still available
    getLogger("processor").info(
      "Processing user: {userId} for request: {requestId}"
    );
  });
}

コンテキスト値の解決に関して、LogTape は明確な優先順位に従います。

1. ログ メッセージ内の明示的なプロパティが最も優先されます
2. Logger.with() 経由で設定された明示的なコンテキストは 2 番目に優先されます
3. withContext() 経由で設定された暗黙的なコンテキストは最も低い優先順位を持ちます

ランタイムサポート

2024 年 10 月の時点で、暗黙的コンテキストは以下でサポートされています。

• Node.js
• デノ
• パン

Web ブラウザは、TC39 非同期コンテキスト提案の実装を待っているため、暗黙的コンテキストをまだサポートしていません。

ユースケース

暗黙的コンテキストは、以下の場合に特に価値があります。

1. リクエスト トレース: リクエスト内のすべてのログにリクエスト ID、ユーザー ID、またはセッション ID を追加します
2. トランザクション監視: 複数の操作にわたるトランザクション ID を追跡します
3. エラー コンテキスト: エラー ログに関連するコンテキスト情報が常に含まれていることを確認します
4. パフォーマンス監視: 複数の操作にわたるタイミング情報を追加します
5. テナント コンテキスト: マルチテナント アプリケーションでは、すべての操作にわたってテナント情報を追跡します

ベストプラクティス

暗黙的コンテキストを使用する場合は、次のベスト プラクティスを考慮してください。

1. 実際に実行コンテキスト全体に属する情報には暗黙的コンテキストを使用します
2. コンテキスト データを軽量に保ちます。コンテキスト データは実行全体を通じて保持されることを忘れないでください
3. アプリケーション全体で意味のある一貫したキー名を使用します
4. コンテキスト構造の一貫性を確保するために TypeScript の使用を検討してください
5. アプリケーションに予想されるコンテキスト構造を文書化します

移行ガイド

すでに LogTape を使用している場合、暗黙的コンテキストを使用するようにアップグレードするのは簡単です。

1. LogTape 0.7.0 にアップデート
2. LogTape 構成にコンテキストローカルストレージを追加します
3. コンテキストが手動で渡されている場所を特定する
4. 適切な境界で withContext() 呼び出しに置き換えます

結論

LogTape 0.7.0 の暗黙的コンテキストは、コードを煩雑にしたりコールスタックを介してコンテキストを手動で渡したりすることなく、コンテキスト情報をログに追加する強力な方法を提供します。これらは、Web サービス、API、および操作全体にわたるコンテキストの追跡が重要なその他のアプリケーションで特に役立ちます。

この機能をどのように使用してアプリケーションのロギングと可観測性を向上させるかを見るのが楽しみです。ぜひ試してみて、ご意見をお聞かせください!

詳細については、暗黙的コンテキストに関する完全なドキュメントを確認してください。

以上がLogTape .0 での暗黙的コンテキストの導入の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。