AWS Lambda Powertools Python入門 第 4 回 ~Metrics Utility
Author : 福井 厚
皆さん、こんにちは。AWSソリューションアーキテクトの福井です。
第 3 回では、AWS Lambda Powertools Python の Logger ユーティリティーの使い方についてご紹介しました。今回は Core Utilities の中の Metrics についてご紹介します。なお、本シリーズでは、AWS Lambda Powertools Python 1.25.1 を対象としています。
この連載記事のその他の記事はこちら
- 選択
- AWS Lambda Powertools Python 入門 第 1 回
- 第 2 回 ~Tracer Utility
- 第 3 回 ~Logger Utility
- 第 4 回 ~Metrics Utility
- 第 5 回 ~EventHandler Utility - REST API 編
- 第 6 回 EventHandler Utility - GraphQL 編
Metrics (Core Utilities)
Metrics は埋め込みメトリクスフォーマット Amazon CloudWatch Embedded Metric Format (EMF) に従った標準出力に対するメトリクスによってカスタムメトリクスを非同期に作成することができます。メトリクスは Amazon CloudWatch のコンソール でビジュアル化することができます。Metrics の主な機能は以下の通りです。
- 単一の CloudWatch EMF オブジェクト (JSON の blob) を使用して 100 個までのメトリクスを集約可能
- メトリクスの一般的な定義間違い (メトリクスユニット、値、最大ディメンジョン、最大メトリクスなど) を検証可能
- CloudWatch サービスによってメトリクスは非同期に作成され、カスタムスタックは不要
- 異なるディメンジョンを伴う一度限りのメトリクスを作成する Context Manager
Amazon CloudWatch Embedded Metric Format (EMF) とは
CloudWatch Embeded Metric Format は JSON 形式を使用し、CloudWatch Logs に対して自動的に構造化されたログイベント内の埋め込まれたメトリクスの値を抽出するように指示します。CloudWatch を利用して抽出された値に対してグラフやアラートを作成することができます。
CloudWatch Logs に EMF 形式でメトリクスを出力する方法は、以下の 2 つの点で CloudWatch Metrics の API でカスタムメトリクスを出力する方法に比べてメリットがあります。
1 つは、CloudWatch Metrics の PutMetricData API の呼び出しは秒間 150 回という上限が設けられていて、それ以上の呼び出しはスロットリングされるのに対して、AWS Lambda の CloudWach Logs への送信は非同期に行われてスロットリングされることがありません。
2 つ目のメリットはコストです。CloudWatch Metrics の PutMetricData API がを呼び出すよりも CloudWatch Logs への書き込みのほうがコスト的に有利になります (詳しくは、リージョンごとの CLoudWatch の PutMetricData API の呼び出しと CloudWatch Logs の料金 をご参照ください)。以上の理由から AWS Lambda Powertools Python では EMF 形式の CloudWach Logs へのカスタムメトリクスの出力方法を提供しています。
メトリクスに関連する用語
Metrics の利用について説明する前に Amazon CloudWatch に関して知っておくべき用語について説明します。
名前空間 (Namespace)
CloudWatch の名前空間。最上位レベルのコンテナで、与えられたアプリケーションに対する複数のサービス複数のメトリクスをグループ化する。例えば、ServerlessEcommerce など。
ディメンジョン (Dimensions)
ディメンジョンセット (DimensionSet) の配列で Key Value フォーマットのメトリクスのメタデータ。メトリクスをビジュアル化して分析するのを助ける。例えば、支払いサービスの ColdStart。
メトリクス (Metrics)
Name と Unit によるメトリック定義 (MetricDefinition) オブジェクトの配列。100 以上のメトリック定義を含むことはできない。
利用方法
AWS Lambda Powertools Python を Lambda 関数に組み込む方法については、第 1 回 の記事を参照ください。Metrics を利用する際は、以下の設定を行います。環境変数でもコンストラクタのパラメータでも設定可能です。
| 設定 | 説明 | 環境変数 | コンストラクタのパラメータ |
| メトリクスの名前空間 | すべてのメトリクスが配置される論理コンテナ | POWERTOOLS_METRICS_NAMESPACE | namespace |
| サービス | すべてのメトリクスに渡ってサービスをメトリクス ディメンジョンにセット（オプション） | POWERTOOLS_SERVICE_NAME | service |
Tips : アプリケーションやメインサービスをメトリクスの名前空間にすることで、すべてのメトリクスのグループ化が容易になります。
AWS Serverless Application Model (SAM) の例です。(抜粋)
メトリクスの作成
Metics を利用するために Metrics をインポートしてインスタンス化します。またユニットの単位の指定には、MeticUnit をインポートして利用します。metrics.log_metrics デコレーターをハンドラーに指定します。
add_metric メソッドを利用してメトリクスを作成できます。
上のコードの結果、Amazon CloudWatch Logs に、次のような EMF 形式のログが書き込まれ、CloudWatch Metrics にカスタムの名前空間が追加されます。
{
"_aws": {
"Timestamp": 1654233601233,
"CloudWatchMetrics": [
{
"Namespace": "MetricsDemoApp",
"Dimensions": [
[ "service" ]
],
"Metrics": [
{
"Name": "SuccessfulCalling",
"Unit": "Count"
}
]
}
]
},
"service": "metrics-demo",
"SuccessfulCalling": [ 1 ]
}
クリックすると拡大します
また add_dimension メソッドを使用してすべての集約されたメトリクスのためにカスタムのディメンジョンを作成することができます。
追加のディメンジョンが表示されます。
クリックすると拡大します
MetricUnit の enum は CloudWatch がサポートするメトリックスユニットの検索を容易にします。ユニット名をすでに知っている場合は、MetiricUnit を利用する代わりに例えば、“Count” などの文字列値を渡すこともできます。
CloudWatch の EMF はバッチごとに最大 100 メトリクスをサポートします。Lambda Powertools Python の Metics Utility は 100 個目のメトリクスを追加すると自動的にメトリクスを書き出します。101 個目のメトリクスは新しい EMF オブジェクトに集約されます。
注意：ハンドラーの外側でメトリクスやディメンジョンを作成しないでください。グローバルスコープに追加されるメトリクスまたはディメンジョンはコールドスタート時にのみ追加されます。これが意図した動作であれば、この注意は無視できます。
デフォルトディメンジョンへの追加
set_default_dimensions メソッド、または log_metrics デコレーターの default_permissions パラメータを利用して、Lambda の実行全体でデフォルトディメンジョンを永続化することができます。
クリックすると拡大します
クリックすると拡大します
また、ある時点でデフォルトディメンジョンを削除したい場合は、clear_default_dimensions メソッドを利用することができます。
メトリクスのフラッシュ
すべてのカスタムメトリクスを追加したら、それらをシリアライズして標準アウトプットに書き出す必要があります。log_metrics デコレーターでこれを自動的に行うことができます。
このデコレーターは、すべての作成したメトリクスの検証、シリアライズ、書き出しを行います。メトリクスの検証中、メトリクスが提供されない場合はログに警告が記録されますが、例外は発生しません。
注意：メトリクスが与えられていて、かつ以下のクライテリアを満たしていない場合は、SchemaValidationError 例外が発生します。
- 最大 8 個のユーザー定義ディメンジョン
- 1 つだけ名前空間がセットされている
- メトリクスの単位は CloudWatch がサポートしているものでなければならない
空のメトリクスに SchemaValidationError 例外を発生させる
毎回必ず、少なくとも 1 つ以上のメトリクスが送信されることを確実にしたい場合は、log_metorics デコレーターに raise_on_empty_metrics パラメータを追加します。
このように指定するとメトリクスを送信しない場合に、SchemaValidationError 例外が発生します。
クリックすると拡大します
複数のミドルウェアのネスト
複数のミドルウェアを利用する時は、コードがまだ実行されていない段階で早期にメトリクスが検証されるのを防ぐために、log_metrics を最後のデコレーター (一番上に記載) として利用して、すべての後続のデコレーターをラップします。
コールドスタートメトリクスのキャプチャ
log_metrics デコレーターに capture_cold_start_metric パラメータを渡すことによって、コールドスタートメトリクスを任意でキャプチャすることができます。
コールドスタート時はこの機能によって
- ColdStart という名前のメトリクスを含む単独の分割された EMF のバイナリオブジェクトが作成されます。
- function_name と service のディメンジョンが追加されます。
これによってアプリケーション独自のメトリクスや関係のないディメンジョンからコールドスタートのメトリクスを分離しておくことができます。
まとめ
今回は、AWS Lambda Powertools Python の Metrics について紹介しました。Metirics Utility を利用することでアプリケーションで記録したいメトリクスを簡単に CloudWatch Logs の EMF に従った形式で作成することができます。Lambda 関数を実装する際にはこの機能を組み込むことをお勧めします。
次回は EventHandler について紹介します。次回もお楽しみに。
この連載記事のその他の記事はこちら
- 選択
- AWS Lambda Powertools Python 入門 第 1 回
- 第 2 回 ~Tracer Utility
- 第 3 回 ~Logger Utility
- 第 4 回 ~Metrics Utility
- 第 5 回 ~EventHandler Utility - REST API 編
- 第 6 回 EventHandler Utility - GraphQL 編
筆者プロフィール
福井 厚
アマゾン ウェブ サービス ジャパン合同会社
シニアソリューションアーキテクト サーバーレススペシャリスト
2015 年からアマゾンウェブサービスジャパンでソリューションアーキテクトとして活動。サーバーレススペシャリストとして日々モダンアプリケーション開発とサーバーレスの活用の技術支援を行なっています。
AWS を無料でお試しいただけます