AWS Lambda Powertools Python入門 第 2 回 ~Tracer Utility

シリーズ第 2 回では、Core Utilities の Tracer について紹介します。Tracer を利用することで、AWS X-Ray SDK を利用するよりもより簡単にトレースの機能を利用できます。

Tracer は、AWS X-Ray Python SDK の薄いラッパーです。主な機能は以下の通りです。

• コールドスタートをアノテーションとして、レスポンスまたは例外をメタデータとして自動的に捕捉
• ローカル環境におけるテスト実行時など AWS Lambda 環境で実行していないときは自動的に無効化
• トレース非同期メソッド、ジェネレータ、コンテキストマネージャをサポート
• AWS X-Ray による自動パッチサポートモジュール

ユーティリティーを利用する前に対象の Lambda 関数が AWS X-Ray にトレースデータを送信できるように Tracing を Active にしてパーミッションを設定します (Amazon API Gateway でトレースを有効化して Lambda 関数を呼び出すようなパッシブ計測の場合は、Lambda 関数は自動的にトレースデータを送信します)。また環境変数の POWERTOOLS_SERVICE_NAME を指定することで、コード内でのサービス名の指定を省略できます。AWS SAM のテンプレート (抜粋) は以下の通りです。

Tracer に関連したその他の環境変数は以下の通りです。

AWS CLI で AWS X-Ray にトレースデータの送信を許可する場合の例は以下の通りです。

まず始めに簡単に使い始めるためには、Tracer クラスをインスタンス化して capture_lambda_handler デコレーターをハンドラーに指定します。 

Lambda 関数を実行するとこちらのようにトレースデータを取得することができます。

capture_lambda_handler デコレーターは運用を容易にするために以下の追加のタスクを実行します。

• 初期化のオーバーヘッドが発生しているトレースを容易にフィルタするための ColdStart アノテーションを追加します。
• Tracer をインスタンス化する際に service パラメータをセットするか、環境変数の POWERTOOLS_SERVICE_NAME を指定すると service アノテーションを追加します。
• ハンドラーのレスポンスまたは例外情報を自動的にキャプチャしトレースのメタデータに含めます。

アノテーションはトレースに含まれる Key-Value で、AWS X-Ray によってインデックス化されます。アノテーションを利用してトレースをフィルタすることが可能で、さらにトランザクションを分析するためのトレースグループを作成するために利用することもできます。AWS X-Ray のアノテーションは Value に 1,000 Unicode 文字列まで登録でき、またトレースごとに 50 エントリーまで作成することができます。

メタデータも同様にトレースに含まれる Key-Value ですが、AWS X-Ray によってインデックス化されない点がアノテーションと異なります。一方でメタデータは Value にブール値、数値、文字列、オブジェクトを含めることができ、また名前空間を指定することもできます。これらの値を運用管理のためにトレースに追加して利用することができます。

Lambda 関数実行後に確認するとトレースにメタデータが追加されています。

capture_method デコレーターを利用すると同期型関数のトレースを取得できます。

非同期関数やジェネレータに対しても capture_method デコレーターを使用することができます。

Tracer は AWS Lambda の実行環境以外では、自動的に無効化されます。そのためデバッグなどの理由でローカル実行する際に、コードを変更する必要はありません。

• トレースを分析したり、特定のビューを作成したり、Trace Group の機能を利用してメトリクスを集計するためにアノテーションを利用しましょう。
• メタデータのデータをより容易にグループ化するには名前空間を利用しましょう。
• アノテーションやメタデータはカレントのサブセグメントに追加されます。異なるサブセグメントに追加したい場合は、X-Ray SDK の context manager の機能を利用します。