【Serverless Framework】API Gatewayのログを定義する

本日のお題

Serverless Framework（以下「SFW」）において、API Gateway関連ログの出力方法について。 *1

参考

• Serverless Framework公式ページ

やり方

provider.logsセクション内の各通信方式(httpApi, restApi, websocket)にAPI Gateway関連ログのプロパティを定義すればOK。(他にもframeworkLambdaという、「AWS Lambda-backed カスタムリソースのログ」の設定項目があるが、今回は割愛)

https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml#logs

各通信方式毎に設定可能なプロパティが決まっているので、使用する通信方式に沿ったプロパティを定義する。（各プロパティは下表を参照）

なおこの項目は、API Gateway マネジメントコンソールの「ステージ」 - 「ログ/トレース」タブの設定項目に対応しています。*2

プロパティ名	説明	「ログ/トレース」タブの該当項目	httpApi	restApi	websocket	備考
accessLogging	アクセスログを出力する	「アクセスログの有効化」	×	〇	〇	「/aws/api-gateway/<API名>-」ロググループにログが出力される
format	HTTPログやアクセスログのフォーマットをcontext形式で設定する	「ログの形式」	〇	〇	〇	・RestApi及びwebsocketの場合、accessLoggingがtrueの場合のみ反映される ・context形式については下記URLを参照（※1） ・未指定時は自動設定される
executionLogging	簡単な実行ログを出力する	-	×	〇	〇	「API-Gateway-Execution-Logs_/」ロググループにログが出力される
level	ログを出力するイベントをINFO(全部), ERROR(エラーのみ), OFF(出力しない)から設定する	CloudWatchログ	×	〇	〇	INFOを選択した場合、エラーイベントもロギングされる
fullExecutionData	実行ログに詳細情報が追加される	-	×	〇	〇	・リクエスト情報やLambdaへのリクエスト、Lambdaからのレスポンス情報も記載される。 ・リクエストbodyもロギングされるので、扱う情報によっては注意が必要
role	API GatewayのログをCloudWatchに出力する際に使用するIAM RoleのARN	-	×	〇	×
roleManagedExternally	API GatewayのログをCloudWatchに出力する際に使用するIAM RoleをSFW外部で管理するかどうか	-	×	〇	×	デフォルトはfalse

※1：https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html#context-variable-reference

# 設定例
provider
  logs
    restApi
      accessLogging: true
      executionLogging: true
      level: INFO
      fullExecutionData: false      

少々短めですが、今回はこの辺で。

*1:Lambda関数のログは、SFWでデプロイすれば、JavaScriptのconsole.logなど各種ログ出力関数で出力できます

*2:「X-Rayトレース」はprovider.tracingセクションで設定します