Datadog のサーバーレスマクロ

build_serverless Slack

Datadog では、AWS SAM をご利用のお客様のサーバーレスアプリケーションのデプロイに、サーバーレスの CloudFormation マクロをおすすめしています。

以下を行うことで、サーバーレスアプリケーションからのメトリクス、トレース、ログの収集をマクロで自動的に構成できます。

  • Python および Node.js Lambda 関数用に Datadog Lambda ライブラリおよび Lambda 拡張機能をインストールし構成。
  • Lambda 関数からの拡張 Lambda メトリクスおよびカスタムメトリクスの収集を有効化。
  • 必要に応じて、Datadog Forwarder から Lambda 関数ロググループへのサブスクリプションを管理。

インストール

AWS アカウントでマクロを使用可能にするには、Datadog のテンプレートで CloudFormation スタックをデプロイします。このデプロイには、CloudFormation マクロリソースと、マクロを実行したときに呼び出される Lambda 関数が含まれます。このスタックを有効にすると、同じアカウントにデプロイされた他の CloudFormation スタックにマクロを使用できるようになります。アカウントのマクロ定義に関する詳細は、CloudFormation ドキュメントページを参照してください。

初めてインストールする場合は、以下のようにデプロイします。

aws cloudformation create-stack \
  --stack-name datadog-serverless-macro \
  --template-url https://datadog-cloudformation-template.s3.amazonaws.com/aws/serverless-macro/latest.yml \
  --capabilities CAPABILITY_AUTO_EXPAND CAPABILITY_IAM

新しいリリース後にマクロを更新する場合は、同じパラメータを使い update-stack メソッドを使用します。また、最新の リリース からマクロのバージョンを指定することもできます。それには、latest.yml をリリースバージョンに置き換えます(例、0.1.2.yml)。

aws cloudformation update-stack \
  --stack-name datadog-serverless-macro \
  --template-url https://datadog-cloudformation-template.s3.amazonaws.com/aws/serverless-macro/latest.yml \
  --capabilities CAPABILITY_AUTO_EXPAND CAPABILITY_IAM

注: マクロは、AWS アカウントのリージョンに 1 回デプロイするだけで、同じリージョンにデプロイされたすべての CloudFormation スタックに使用できます。

AWS SAM での使用

SAM を使用してサーバーレスアプリケーションをデプロイするには、必要な SAM 変換の後に Datadog Serverless CloudFormation マクロを template.yml ファイルの Transform セクションに追加します。

Transform:
  - AWS::Serverless-2016-10-31
  - Name: DatadogServerless
    Parameters:
      stackName: !Ref "AWS::StackName"
      apiKey: "<DATADOG_API_KEY>"
      pythonLayerVersion: "<LAYER_VERSION>" # Node.js には nodeLayerVersion を使用
      extensionLayerVersion: "<LAYER_VERSION>"
      service: "<SERVICE>" # オプション
      env: "<ENV>" # オプション
      version: "<VERSION>" # オプションl
      tags: "<TAGS>" # オプション
      # その他のパラメーターについては、コンフィギュレーションセクションを参照

注: マクロをインストールしたときに、提供された template.yml ファイルを変更しないと、アカウントに定義されたマクロ名は DatadogServerless になります。オリジナルのテンプレートを変更する場合は、個々に追加する変換の名前が AWS::CloudFormation::Macro リソースの Name プロパティと一致するようにしてください。

コンフィギュレーション

プラグインをさらに構成するには、以下のカスタムパラメーターを使用します。

パラメーター説明
addLayersLambda レイヤーを追加またはユーザーが独自のレイヤーを使用。デフォルトは true。「true」の場合、Lambda ライブラリのバージョン変数も必要になります。「false」の場合は、関数のデプロイメントパッケージに Datadog Lambda ライブラリを含める必要があります。
pythonLayerVersionインストールする Python Lambda レイヤーのバージョン(例: “21”)。Python で記述された Lambda 関数を 1 つ以上デプロイする場合で、addLayers が「true」のときは必須。最新バージョンの数字は、https://github.com/DataDog/datadog-lambda-python/releases で確認できます。
nodeLayerVersionインストールする Node.js Lambda レイヤーのバージョン(例: “29”)。Node.js で記述された Lambda 関数を 1 つ以上デプロイする場合で、addLayers が「true」のときは必須。最新バージョンの数字は、https://github.com/DataDog/datadog-lambda-js/releases で確認できます。
extensionLayerVersion“5” など、インストールする Datadog Lambda Extension レイヤーのバージョン。extensionLayerVersion が設定されている場合は、apiKey (暗号化の場合は apiKMSKey または apiKeySecretArn) の設定も必要となります。extensionLayerVersion を使用する場合は、forwarderArn を設定しないでください。Lambda Extension の詳細はこちら
forwarderArn設定すると、プラグインにより関数のロググループが自動的に Datadog Forwarder にサブスクライブされます。または、AWS::Logs::SubscriptionFilter リソースを使用してログサブスクリプションを定義できます。: ロググループおよびサブスクリプションフィルターの作成にはマクロに関数名が必要なため、初めてデプロイされる関数には ‘FunctionName’ プロパティが定義されている必要があります。‘FunctionName’ に、!Sub などの CloudFormation 関数を含めることはできません。
stackNameデプロイする CloudFormation スタックの名前。forwarderArn が提供されていて、Lambda 関数が動的に命名されている (FunctionName プロパティが Lambda に提供されていない) 場合のみ必須。このパラメーターを SAM および CDK に追加する方法については、以下の例を参照してください。
flushMetricsToLogsDatadog Forwarder Lambda 関数を使用して、ログ経由でカスタムメトリクスを送信します (推奨)。デフォルトは truefalse に設定した場合、Datadog API キーを apiKey (暗号化の場合は apiKMSKey または apiKeySecretArn) を使用して定義する必要があります。
siteデータを送信する Datadog サイトを設定します。flushMetricsToLogs が false の場合にのみ必要です。可能な値は、datadoghq.comdatadoghq.euus3.datadoghq.comus5.datadoghq.comddog-gov.com です。デフォルトは datadoghq.com です。
apiKeyDatadog API キー。flushMetricsToLogsfalse の場合のみ必要。
apiKeySecretArnAWS Secrets Manager で Datadog の API キーを保存しているシークレットの ARN。flushMetricsToLogsfalse の場合や extensionLayerVersion が設定されている場合に、apiKey の代わりにこのパラメータを使用することができます。Lambda の実行ロールに secretsmanager:GetSecretValue アクセス許可を追加することを忘れないようにしましょう。
apiKMSKeyKMS を使用して暗号化された Datadog API キー。flushMetricsToLogs が「false」で、KMS 暗号化を使用している場合、apiKey の代わりにこのパラメーターを使用します。
enableEnhancedMetricsLambda 関数の拡張メトリクスを有効にします。デフォルトは true。Datadog Forwarder Lambda 関数が関数ロググループにサブスクライブする必要があります。
enableXrayTracingLambda 関数のトレースを有効にします。デフォルトは「false」。
enableDDTracingdd-trace、Datadog の APM ライブラリを使用して Lambda 関数のトレースを有効にします。デフォルトは true。Datadog Forwarder Lambda 関数が関数ロググループにサブスクライブする必要があります。
enableDDLogsLambda 関数の Datadog ログ収集を有効にします。注: この設定は、Datadog Forwarder を介して送信されるログには影響しません。デフォルトは true です。
serviceextensionLayerVersion と共に設定すると、マクロによって指定した値を持つすべての Lambda 関数に DD_SERVICE 環境変数が追加されます。forwarderArn と共に設定すると、マクロによって指定した値を持つすべての Lambda 関数に service タグが追加されます。
envextensionLayerVersion と共に設定すると、マクロによって指定した値を持つすべての Lambda 関数に DD_ENV 環境変数が追加されます。forwarderArn と共に設定すると、マクロによって指定した値を持つすべての Lambda 関数に env タグが追加されます。
versionextensionLayerVersion と共に設定すると、マクロによって指定した値を持つすべての Lambda 関数に DD_VERSION 環境変数が追加されます。forwarderArn と共に設定すると、マクロによって指定した値を持つすべての Lambda 関数に version タグが追加されます。
tags1 つの文字列としての key:value のペアのカンマ区切りのリスト。extensionLayerVersion と共に設定すると、すべての Lambda 関数に DD_TAGS 環境変数が追加され、指定した値が設定されます。forwarderArn と共に指定すると、マクロは文字列をパースして、各 key:value ペアをタグとしてすべての Lambda 関数に設定します。
logLevelログのレベルを設定します。拡張ロギングの場合 DEBUG に設定します。
captureLambdaPayload関数の実行スパンにリクエストと応答のペイロードを自動的にタグ付けして、APM アプリケーションに表示できるようにします。

UDS の仕組み

このマクロにより CloudFormation テンプレートが変更され、Node.js および Python 用の Lambda レイヤーを関数にアタッチすることで Datadog Lambda ライブラリがインストールされます。そして、コードの変更を必要とせずに、Lambda ライブラリを初期化する置換ハンドラーへリダイレクトされます。

トラブルシューティング

デバッグログ

デバッグの問題が発生した場合は、CloudWatch ログでマクロ Lambda 関数を確認することができます。CloudWatch ログへのアクセス方法:

  • マクロ CloudFormation スタック (手順に従ってコマンドをコピーした場合、名称は datadog-serverless-macro となります) を検索します
  • 「Resources」タブをクリックして、論理 ID がMacroFunctionLogGroup のCloudWatch ロググループを見つけます

エラーメッセージ: ‘FunctionName’ プロパティが未定義です…

このエラーは、forwarderArn を提供し、Lambda 関数を初めてデプロイする場合に発生します。ロググループが存在せず、マクロはこのロググループの作成または Forwarder へのサブスクライブができません。この問題を修正する一つの方法は、Lambda で FunctionName プロパティを明示的に定義することです(下記の例を参照)。

Resources:
  MyLambda:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs12.x
      FunctionName: MyFunctionName # このプロパティを Lambda に追加します

FunctionName を明示的に定義できない(または定義しない)場合は、SAM テンプレートまたは CDK ソースコードから forwarderArn パラメーターを削除し、以下のように AWS::Logs::SubscriptionFilter リソースを使用してサブスクリプションフィルターを定義します。

Resources:
  MyLogSubscriptionFilter:
    Type: "AWS::Logs::SubscriptionFilter"
    Properties:
      DestinationArn: "<DATADOG_FORWARDER_ARN>"
      LogGroupName: "<CLOUDWATCH_LOG_GROUP_NAME>"
      FilterPattern: ""

エラーメッセージ: ’logGroupNamePrefix’ は制約を満たせませんでした…

FunctionName に、!Sub などの CloudFormation 関数が含まれる場合、forwarderArn オプションは機能しません。この場合、マクロは実際の関数名にアクセスできません(CloudFormation は変換後に関数を実行します)。そのため、関数にロググループやサブスクリプションフィルターを作成できません。

SAM テンプレートまたは CDK ソースコードから forwarderArn パラメーターを削除し、以下のように AWS::Logs::SubscriptionFilter リソースを使用してサブスクリプションフィルターを定義します。

Resources:
  MyLogSubscriptionFilter:
    Type: "AWS::Logs::SubscriptionFilter"
    Properties:
      DestinationArn: "<DATADOG_FORWARDER_ARN>"
      LogGroupName: "<CLOUDWATCH_LOG_GROUP_NAME>"
      FilterPattern: ""

エラーメッセージ: ‘Failed to execute transform DatadogServerless’

このエラーは、コマンドを実行する IAM ユーザーに lambda:InvokeFunction 権限がない場合に発生する可能性があります。そのユーザーの IAM ロールに権限を追加してください。

コミュニティ

製品のフィードバックや質問については、Slack の Datadog コミュニティ#serverless チャンネルに参加してください。