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

2022-04-04
デベロッパーのためのクラウド活用方法

Author : 福井 厚

皆さん、こんにちは。AWS ソリューションアーキテクトの福井です。

前回の第 1 回 では、AWS Lambda Powertools Python の概要とインストール方法、提供されているユーティリティーの一覧についてご紹介しました。第 2 回からは AWS Lambda Powertools Python で提供されている各種ユーティリティーの具体的な使い方についてご紹介します。今回は Core Utilities の中の Tracer についてご紹介します。なお、本シリーズでは、AWS Lambda Powertools Python 1.25.1 を対象としています。


第 1 回記事はこちら >

この連載記事のその他の記事はこちら

選択
  • 選択
  • AWS Lambda Powertools Python 入門 第 1 回
  • 第 2 回 ~Tracer Utility
  • 第 3 回 ~Logger Utility
  • 第 4 回 ~Metrics Utility
  • 第 5 回 ~EventHandler Utility - REST API 編
  • 第 6 回 EventHandler Utility - GraphQL 編

Tracer (Core Utilities)

シリーズ第 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 に関連したその他の環境変数は以下の通りです。

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

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

aws lambda update-function-configuration --function-name my-function --tracing-config Mode=Active

注意 : トレースモードはバージョン固有コンフィグレーションの一部なので Lambda 関数のバージョン発行後の変更はできません。


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 ハンドラーはサポートされません。


その他の Tips

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

Tips

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

まとめ

今回は、AWS Lambda Powertools Python の Tracer について紹介しました。Tracer を利用することで AWS X-Ray を利用したトレース情報にアノテーションやメタデータを簡単に追加できることがお分かり頂けたと思います。皆様の Lambda 関数に AWS Lambda Powertools Pythonを 組み込んで、ご活用ください。次回もお楽しみに。

この連載記事のその他の記事はこちら

選択
  • 選択
  • AWS Lambda Powertools Python 入門 第 1 回
  • 第 2 回 ~Tracer Utility
  • 第 3 回 ~Logger Utility
  • 第 4 回 ~Metrics Utility
  • 第 5 回 ~EventHandler Utility - REST API 編
  • 第 6 回 EventHandler Utility - GraphQL 編

builders.flash メールメンバーへ登録することで
AWS のベストプラクティスを毎月無料でお試しいただけます


筆者プロフィール

福井 厚
アマゾン ウェブ サービス ジャパン合同会社
シニアソリューションアーキテクト サーバーレススペシャリスト

2015 年からアマゾンウェブサービスジャパンでソリューションアーキテクトとして活動。サーバーレススペシャリストとして日々モダンアプリケーション開発とサーバーレスの活用の技術支援を行なっています。

AWS を無料でお試しいただけます

AWS 無料利用枠の詳細はこちら ≫
5 ステップでアカウント作成できます
無料サインアップ ≫
ご不明な点がおありですか?
日本担当チームへ相談する