Lambda Powertools

Lambda Powertools とは

Lambda Powertools は、AWS が公式に提供するオープンソースライブラリで、Lambda 関数の構造化ログ、分散トレーシング、カスタムメトリクスを最小限のコードで実装できる。TypeScript、Python、Java、.NET の 4 言語版があり、正式名称は「Powertools for AWS Lambda」である。2026 年 8 月時点でドキュメントは AWS 公式ドキュメント配下 (docs.aws.amazon.com/powertools/) に置かれており、以前の docs.powertools.aws.dev はそこへリダイレクトされる。

追加のインフラは要らない。関数コードから呼ぶライブラリと、あらかじめ公開されている Lambda Layer だけで動く。逆に言えば導入の判断は、監視まわりの下ごしらえを自前のユーティリティで抱えるか、公式ライブラリの流儀に寄せるかという選択になる。

3 つの主要機能

1. Logger (構造化ログ)

JSON 形式のログを出力し、Lambda のコンテキスト情報を各行に付与できる。ここは「自動」の範囲を誤解しやすい。関数名・メモリサイズ・関数 ARN・リクエスト ID・コールドスタートかどうかは injectLambdaContext を通したときに付く項目で、付け方は Middy ミドルウェア (middy(handler).use(injectLambdaContext(logger)))、クラスメソッドのデコレーター (@logger.injectLambdaContext())、ハンドラー内で logger.addContext(context) を呼ぶ手動の 3 通りである。デコレーター形式が使えるのはハンドラーをクラスメソッドとして書いている場合に限られる。一方で X-Ray のトレース ID は、トレーシングを有効にしているかどうかに関係なく常にログへ入る。

運用で引っかかるのはログレベルの決まり方である。POWERTOOLS_LOG_LEVEL の既定は INFO だが、Lambda 側の詳細なログ制御 (Advanced Logging Controls) を有効にしている場合の優先順位は AWS_LAMBDA_LOG_LEVEL 環境変数、コード側の logLevel や setLogLevel()、POWERTOOLS_LOG_LEVEL の順になる。環境変数を直したのに DEBUG が出ないときは、この順番を上から確認するのが早い。サンプリング (POWERTOOLS_LOGGER_SAMPLE_RATE) は既定値が 0 で、0.0 から 1.0 の値を明示しない限り一切効かない。設定したつもりで効いていない典型がここである。

2. Tracer (分散トレーシング)

AWS X-Ray と統合し、Lambda 関数の呼び出し、AWS SDK の呼び出し、HTTP リクエストを自動的にトレースする。サービスマップでリクエストの流れを可視化し、ボトルネックを特定できる。

3. Metrics (カスタムメトリクス)

CloudWatch Embedded Metrics Format (EMF) の形式で標準出力へ書き出し、そのログから CloudWatch 側が非同期にメトリクスを生成する。API を叩いてメトリクスを送るのではないという点が機序として重要で、metrics.addMetric() で値を積み metrics.publishStoredMetrics() で書き出すのが基本形になる。公式ドキュメントは、専用のスタックが不要で Lambda 関数のレイテンシに影響しないと明記している。

コストの勘所は「一意なメトリクスの数」である。CloudWatch 側の数え方はメトリクス名とディメンション名・ディメンション値の組み合わせ単位なので、ディメンションにリクエスト ID やユーザー ID のような値を入れると一意なメトリクスが際限なく増えて費用が跳ねる。ディメンションは環境名や機能名といった取り得る値の少ない軸に絞るのが安全である。なお 1 つの EMF オブジェクトに載せられるメトリクスは 100 までという上限がある。

SAM での設定

SAM での設定の例を示す。

Globals:
  Function:
    Runtime: nodejs22.x
    Environment:
      Variables:
        POWERTOOLS_SERVICE_NAME: order-service
        POWERTOOLS_LOG_LEVEL: INFO
        POWERTOOLS_METRICS_NAMESPACE: OrderService
    Tracing: Active  # X-Ray を有効化
    Layers:
      - '{{resolve:ssm:/aws/service/powertools/typescript/generic/all/latest}}'

Layer の指定でつまずきやすいのは版数である。公式が案内するレイヤー名は AWSLambdaPowertoolsTypeScriptV2、公開アカウントは商用リージョンが 094274105915 (GovCloud と中国リージョンは別アカウント) だが、バージョン番号はリージョンごとに揃っていない。ARN を直書きするならリージョンごとに実在するバージョンを確認する必要があり、上のように公式が用意した SSM パラメータを解決させればその手間が消える。版を固定したいときは latest の位置にバージョン番号を入れたパスを指す。

ランタイムの指定も陳腐化しやすい。nodejs20.x は 2026 年 4 月 30 日にサポート終了となっているため、新しく書くなら nodejs22.x 以降を選ぶ。

ハンドラーへの組み込み方は、機能ごとに Middy ミドルウェア、クラスメソッドのデコレーター、手動呼び出しが用意されている。Middy とデコレーターは別の仕組みで、混ぜて書くと初期化の順序が読みにくくなるため、プロジェクト内でどちらかに寄せておくとよい。

コア機能以外のユーティリティ

Logger・Tracer・Metrics のほかに、サーバーレスで何度も書くことになる処理がまとめられている。Parameters は SSM パラメータストア、Secrets Manager、AppConfig、DynamoDB から値を取得してキャッシュする。Idempotency は同じ入力に対する二重実行を防ぐもので、クラスメソッドのデコレーター、Middy ミドルウェア、関数のラッパーの形で使える。Batch は SQS だけでなく Kinesis Data Streams と DynamoDB Streams のバッチにも対応し、バッチ内の一部のレコードだけが失敗したときの扱いを引き受ける。

どれも自前で書けるものではあるが、冪等性やバッチの部分失敗はコーナーケースを取りこぼしやすい領域で、公式実装に寄せる価値が大きい。

実践的な知識は関連書籍でも得られる。