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

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

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

POWERTOOLS_TRACE_DISABLED	True を指定するとトレースを無効化します。
POWERTOOLS_TRACER_CAPTURE_RESPONSE	True を指定すると Lambda 関数およびメソッドの戻り値をメタデータとしてキャプチャします。(デフォルト)
POWERTOOLS_TRACER_CAPTURE_ERROR	True を指定すると Lambda 関数およびメソッドのエラーをメタデータとしてキャプチャします。(デフォルト)

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

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

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

• 初期化のオーバーヘッドが発生しているトレースを容易にフィルタするための ColdStart アノテーションを追加します。

• Tracer をインスタンス化する際に service パラメータをセットするか、環境変数の POWERTOOLS_SERVICE_NAME を指定すると service アノテーションを追加します。

• ハンドラーのレスポンスまたは例外情報を自動的にキャプチャしトレースのメタデータに含めます。

自動的に作成された ColdStart アノテーションを利用してクエリを絞りこむことができます。

トレースのメタデータに関数のレスポンスが自動的に含まれます。

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

上記のコードで、わざといくつか例外を発生させてアノテーションでクエリを実行した例が以下の図です。SUCCESS と FAIL に分類されているので、ここから一方をクエリに追加して特定のトレースグループにドリルダウンすることが出来ます。

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

このコードを実行するとトレースにメタデータが追加されます。

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

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

関数にデコレーターを指定することで、トレースに関数単位のサブセグメントが作成され、関数単位の実行時間も表示されるようになります。

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

注意 : 但し、非同期 Lambda ハンドラーはサポートされません。