メインコンテンツに移動

builders.flash

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

AWS Lambda Powertools Python入門 第 4 回 ~Metrics Utility

2022-07-04 | Author : 福井 厚

はじめに

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

第 3 回では、AWS Lambda Powertools Python の Logger ユーティリティーの使い方についてご紹介しました。今回は Core Utilities の中の Metrics についてご紹介します。なお、本シリーズでは、AWS Lambda Powertools Python 1.25.1 を対象としています。


X ポスト » | Facebook シェア » | はてブ »

builders.flash メールメンバー登録

builders.flash メールメンバー登録で、毎月の最新アップデート情報とともに、AWS を無料でお試しいただけるクレジットコードを受け取ることができます。
今すぐ登録 »

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) の例

AWS Serverless Application Model (SAM) の例です。(抜粋)

Screenshot of an AWS Serverless Application Model (SAM) template demonstrating a Lambda function using Powertools for Python with environment variables defined for service name and metrics namespace.

メトリクスの作成

Metics を利用するために Metrics をインポートしてインスタンス化します。またユニットの単位の指定には、MeticUnit をインポートして利用します。metrics.log_metrics デコレーターをハンドラーに指定します。

add_metric メソッドを利用してメトリクスを作成できます。

Screenshot of example Python code demonstrating the use of AWS Lambda Powertools Metrics. The code shows how to import Metrics and MetricUnit, create a Metrics object, and log a metric named 'SuccessfulCalling' using the @metrics.log_metrics decorator in a Lambda handler function.

Amazon CloudWatch Logs を確認

上のコードの結果、Amazon CloudWatch Logs に、次のような EMF 形式のログが書き込まれ、CloudWatch Metrics にカスタムの名前空間が追加されます。

{     "_aws": {        "Timestamp": 1654233601233,         "CloudWatchMetrics": [             {                 "Namespace": "MetricsDemoApp",                 "Dimensions": [                     [ "service" ]                ],                 "Metrics": [                     {                         "Name": "SuccessfulCalling",                        "Unit": "Count"                     }                 ]             }         ]     },     "service": "metrics-demo",     "SuccessfulCalling": [ 1 ] }
Screenshot of the AWS CloudWatch Metrics dashboard showing the metrics browsing interface. The 'MetricsDemoApp' namespace is highlighted, and the graph area is currently empty, awaiting metric selection.

add_dimension メソッド

また add_dimension メソッドを使用してすべての集約されたメトリクスのためにカスタムのディメンジョンを作成することができます。

Screenshot of Python code demonstrating how to use AWS Lambda Powertools to add a dimension to CloudWatch metrics in a Lambda function. The highlighted line shows metrics.add_dimension(name='environment', value='prod').

追加のディメンジョン

追加のディメンジョンが表示されます。
Screenshot of AWS CloudWatch Metrics interface showing environment and service grouping options in the Oregon region.

解説

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 メソッドを利用することができます。

Screenshot of a Python code example demonstrating the use of AWS Lambda Powertools Metrics, setting default dimensions and logging metrics within a Lambda handler function.

コマンド / コード

Screenshot of AWS CloudWatch Metrics Dashboard showing an empty graph. No metrics are selected, and message prompts user to select metrics to display.

CloudWatch のメトリクス

メトリクスのフラッシュ

すべてのカスタムメトリクスを追加したら、それらをシリアライズして標準アウトプットに書き出す必要があります。log_metrics デコレーターでこれを自動的に行うことができます。

このデコレーターは、すべての作成したメトリクスの検証、シリアライズ、書き出しを行います。メトリクスの検証中、メトリクスが提供されない場合はログに警告が記録されますが、例外は発生しません。

注意：メトリクスが与えられていて、かつ以下のクライテリアを満たしていない場合は、SchemaValidationError 例外が発生します。

  • 最大 8 個のユーザー定義ディメンジョン
  • 1 つだけ名前空間がセットされている
  • メトリクスの単位は CloudWatch がサポートしているものでなければならない

空のメトリクスに SchemaValidationError 例外を発生させる

毎回必ず、少なくとも 1 つ以上のメトリクスが送信されることを確実にしたい場合は、log_metorics デコレーターに raise_on_empty_metrics パラメータを追加します。
Screenshot of example Python code using @metrics.log_metrics decorator with raise_on_empty_metrics=True for an AWS Lambda handler function.

SchemaValidationError 例外

このように指定するとメトリクスを送信しない場合に、SchemaValidationError 例外が発生します。

Screenshot showing an AWS CloudWatch log event with a SchemaValidationError from AWS Lambda Powertools Python, indicating that at least one metric must be provided. The error traceback and log message are highlighted in the interface.

複数のミドルウェアのネスト

複数のミドルウェアを利用する時は、コードがまだ実行されていない段階で早期にメトリクスが検証されるのを防ぐために、log_metrics を最後のデコレーター (一番上に記載) として利用して、すべての後続のデコレーターを整形します。

Screenshot of a Python code example demonstrating how to use AWS Lambda Powertools for logging metrics and capturing Lambda handler traces, with decorators applied to the lambda_handler function.

コールドスタートメトリクスのキャプチャ

log_metrics デコレーターに capture_cold_start_metric パラメータを渡すことによって、コールドスタートメトリクスを任意でキャプチャすることができます。コールドスタート時はこの機能によって・ColdStart という名前のメトリクスを含む単独の分割された EMF のバイナリオブジェクトが作成されます。・function_name と service のディメンジョンが追加されます。これによってアプリケーション独自のメトリクスや関係のないディメンジョンからコールドスタートのメトリクスを分離しておくことができます。

Screenshot of Python code demonstrating the use of the @metrics.log_metrics decorator from AWS Lambda Powertools, with the capture_cold_start_metric option enabled, on a lambda_handler function definition.

capture_cold_start_metric パラメータ

Screenshot showing an example JSON structure for AWS Lambda Powertools CloudWatchMetrics, including metrics for ColdStart with dimensions for function_name and service.

コールドスタートメトリクスを任意でキャプチャ

まとめ

今回は、AWS Lambda Powertools Python の Metrics について紹介しました。Metirics Utility を利用することでアプリケーションで記録したいメトリクスを簡単に CloudWatch Logs の EMF に従った形式で作成することができます。Lambda 関数を実装する際にはこの機能を組み込むことをお勧めします。

次回は EventHandler について紹介します。次回もお楽しみに。

筆者プロフィール

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

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

A portrait photograph of a smiling man wearing glasses, a beard, and a red sweater over a pink shirt. The image is titled 'Portrait of Fukui Atsushi, 2021.'