build Code Coverage NPM Slack License

Datadog は、サーバーレスフレームワークを使用してサーバーレスアプリケーションをデプロイする開発者向けに、サーバーレスフレームワークプラグインを推奨しています。 プラグインは、アプリケーションのインスツルメンテーションを自動的に有効にして、次の方法でメトリクス、トレース、ログを収集します。

  • Datadog Lambda ライブラリを Lambda にインストールすると、Lambda レイヤーとして機能します。
  • Datadog Lambda 拡張機能を Lambda 関数に Lambda レイヤーとしてインストールするか (addExtension)、Datadog Forwarder を Lambda 関数のロググループにサブスクライブします (forwarderArn)。
  • Lambda 関数に環境変数やトレースレイヤーを追加するなど、必要なコンフィギュレーション変更を行います。

はじめに

すぐに開始するには、PythonNode.jsRubyJavaGo、または .NET のインストール手順に従い、Datadog で関数の拡張メトリクス、トレース、ログを表示します。

インストールが完了したら、詳細オプションを監視の目的に合わせて設定します。

アップグレード

プラグインの各バージョンは、Datadog Lambda レイヤーの特定のバージョンのセットで公開されています。Datadog Lambda レイヤーの最新バージョンによって提供される新機能とバグ修正を取得するには、サーバーレスフレームワークプラグインをアップグレードします。新しいバージョンを本番アプリケーションに適用する前にテストしてください。

コンフィギュレーションパラメーター

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

パラメーター説明
siteデータを送信する Datadog サイトを設定します。例えば、 datadoghq.com (デフォルト)、datadoghq.euus3.datadoghq.comus5.datadoghq.comap1.datadoghq.com または ddog-gov.com などに設定します。このパラメーターは、Datadog Lambda 拡張機能を使用してテレメトリーを収集する場合に必要です。
apiKeyDatadog API キー。このパラメーターは、Datadog Lambda 拡張機能を使用してテレメトリーを収集する際に必要です。また、デプロイ環境で DATADOG_API_KEY 環境変数を設定することも可能です。
appKeyDatadog アプリキー。monitors フィールドが定義されている場合のみ必要です。また、デプロイ環境で DATADOG_APP_KEY 環境変数を設定することも可能です。
apiKeySecretArnAn alternative to using the apiKey field. The ARN of the secret that is storing the Datadog API key in AWS Secrets Manager. Remember to add the secretsmanager:GetSecretValue permission to the Lambda execution role.
apiKMSKeyapiKey フィールドを使用する代替です。Datadog API キーは KMS を使用して暗号化されています。Lambda の実行ロールに kms:Decrypt 権限を追加することを忘れないようにします。
envaddExtension と共に設定すると、指定した値を持つすべての Lambda 関数に DD_ENV 環境変数が追加されます。それ以外の場合、すべての Lambda 関数に env タグが追加され、指定した値が設定されます。デフォルトはサーバーレスデプロイメントの stage 値です。
serviceaddExtension と共に設定すると、指定した値を持つすべての Lambda 関数に DD_SERVICE 環境変数が追加されます。それ以外の場合、すべての Lambda 関数に service タグが追加され、指定した値が設定されます。デフォルトはサーバーレスプロジェクトの service 値です。
versionaddExtension と共に設定すると、指定した値を持つすべての Lambda 関数に DD_VERSION 環境変数が追加されます。forwarderArn と共に設定すると、すべての Lambda 関数に version タグが追加され、指定した値が設定されます。
tags1 つの文字列としての key:value のペアのカンマ区切りのリスト。extensionLayerVersion と共に設定すると、すべての Lambda 関数に DD_TAGS 環境変数が追加され、指定した値が設定されます。forwarderArn と共に指定すると、プラグインは文字列をパースして、各 key:value ペアをタグとしてすべての Lambda 関数に設定します。
enableXrayTracingLambda 関数と API Gateway 統合で X-Ray トレーシングを有効にするには、true に設定します。デフォルトは false です。
enableDDTracingLambda 関数で Datadog トレースを有効にします。デフォルトは true です。
enableASMLambda 関数で Datadog Application Security Management (ASM) を有効にします。これには、Datadog 拡張機能が存在している必要があり (addExtension を使用または手動で追加)、enableDDTracing も必要です。デフォルトは false です。
enableDDLogsLambda 拡張機能を使用して Datadog のログ収集を有効にします。デフォルトは true です。注: この設定は、Datadog Forwarder から送信されるログには影響しません。
monitors定義すると、Datadog プラグインはデプロイされた関数のモニターを構成します。ご使用の環境で、DATADOG_API_KEY および DATADOG_APP_KEY を設定する必要があります。モニターの定義方法については、推奨されるサーバーレスモニターを有効にして構成するにはを参照してください。
captureLambdaPayloadDatadog APM のスパンで、Lambda の呼び出しに対する AWS Lambda のペイロードの入出力をキャプチャします。デフォルトは false です。
enableSourceCodeIntegration関数の Datadog ソースコードインテグレーションを有効にします。デフォルトは true です。
uploadGitMetadataソースコードインテグレーションの一部として、関数の Git メタデータアップロードを有効にします。Datadog Github インテグレーションをインストールしている場合は、これを false に設定すると、Git メタデータのアップロードが不要になります。デフォルトは true です。
subscribeToAccessLogsDatadog Forwarder の API Gateway アクセスロググループへの自動サブスクリプションを有効化します。forwarderArn の設定が必要です。デフォルトは true です。
subscribeToExecutionLogsDatadog Forwarder の HTTP API と Websocket ロググループへの自動サブスクリプションを有効化します。forwarderArn の設定が必要です。デフォルトは true です。
forwarderArnLambda または API Gateway のロググループにサブスクライブされる Datadog Forwarder の ARN。
addLayersDatadog Lambda ライブラリをレイヤーとしてインストールするかどうか。デフォルトは true です。特定のバージョンの Datadog Lambda ライブラリ (Python または Node.js) をインストールできるように Datadog Lambda ライブラリを関数のデプロイパッケージに独自にパッケージ化する場合は、false に設定します。
addExtensionDatadog Lambda 拡張機能をレイヤーとしてインストールするかどうか。デフォルトは true です。有効にすると、apiKeysite を設定する必要があります。
exclude設定後、このプラグインは指定されたすべての関数を無視します。Datadog の機能に含まれてはならない関数がある場合は、このパラメーターを使用します。デフォルトは [] です。
enabledfalse に設定すると、Datadog プラグインが非アクティブ状態になります。デフォルトは true です。たとえば、enabled: ${strToBool(${env:DD_PLUGIN_ENABLED, true})} の環境変数を使用してこのオプションを制御し、デプロイ時にプラグインを有効化 / 無効化することができます。また、--stage を通じて渡された値を使用してこのオプションを制御することもできます。こちらの例をご覧ください。
customHandler設定すると、指定されたハンドラーがすべての関数のハンドラーとして設定されます。
failOnErrorWhen set, this plugin throws an error if any custom Datadog monitors fail to create or update. This occurs after deploy, but will cause the result of serverless deploy to return a nonzero exit code (to fail user CI). Defaults to false.
logLevelログのレベル。拡張ロギングの場合 DEBUG に設定します。
skipCloudformationOutputsスタックに Datadog Cloudformation Outputs を追加するのをスキップしたい場合は、true に設定します。これは、スタックの作成に失敗する原因となる 200 の出力制限に遭遇している場合に有効です。
enableColdStartTracingコールドスタートトレースを無効にするには、false に設定します。NodeJS と Python で使用されます。デフォルトは true です。
coldStartTraceMinDurationコールドスタートトレースでトレースするモジュールロードイベントの最小継続時間 (ミリ秒) を設定します。数値。デフォルトは 3 です。
coldStartTraceSkipLibsオプションで、カンマで区切られたライブラリのリストに対してコールドスタートスパンの作成をスキップすることができます。深さを制限したり、既知のライブラリをスキップするのに便利です。デフォルトはランタイムに依存します。
subdomain出力されるアプリの URL に使用するオプションのサブドメインを設定します。デフォルトは app です。
enableProfilingDatadog Continuous Profiler を true で有効にします。NodeJS と Python のベータ版でサポートされています。デフォルトは false です。
encodeAuthorizerContextLambda オーサライザーで true に設定すると、トレースコンテキストがレスポンスにエンコードされて伝搬されます。NodeJS と Python でサポートされています。デフォルトは true です。
decodeAuthorizerContextLambda オーサライザーで認可された Lambda に対して true を設定すると、エンコードされたトレースコンテキストをパースして使用します (見つかった場合)。NodeJS と Python でサポートされています。デフォルトは true です。
apmFlushDeadlineタイムアウトが発生する前にスパンを送信するタイミングをミリ秒単位で決定するために使用されます。AWS Lambda の呼び出しの残り時間が設定された値よりも小さい場合、トレーサーは、現在のアクティブなスパンとすべての終了したスパンの送信を試みます。NodeJS と Python でサポートされています。デフォルトは 100 ミリ秒です。
enableStepFunctionsTracingDatadog Forwarder の Step Function ロググループと Step Function トレーシングへの自動サブスクリプションを有効にします。Step Function のロググループが構成されていない場合は、自動的に作成されます。forwarderArn の設定が必要です。デフォルトは false です。
propagateUpstreamTracetrue に設定すると、下流の Stepfunction の起動トレースは上流の Stepfunction の起動とマージされます。デフォルトは false です。
redirectHandlersオプションで、false に設定した場合にハンドラーのリダイレクトを無効にします。これは APM が完全に無効になっている場合にのみ false に設定してください。デフォルトは true です。
上記のパラメーターを使用するには、以下の例のように custom > datadog セクションを serverless.yml に追加します。
custom:
  datadog:
    apiKeySecretArn: "{Datadog_API_Key_Secret_ARN}"
    enableXrayTracing: false
    enableDDTracing: true
    enableDDLogs: true
    subscribeToAccessLogs: true
    forwarderArn: arn:aws:lambda:us-east-1:000000000000:function:datadog-forwarder
    exclude:
      - dd-excluded-function

Webpack

webpack などのバンドラーを使用している場合は、サーバーレストレーシングと Webpack を参照してください。

TypeScript

タイプ定義が見つからないというエラーに遭遇することがあります。このエラーを解決するには、プロジェクトの package.json の devDependencies リストに datadog-lambda-jsdd-trace を追加してください。

serverless-typescript を使用している場合は、serverless-datadogserverless.ymlserverless-typescript エントリの上にあることを確認してください。プラグインは自動的に .ts ファイルを検出します。

plugins:
  - serverless-plugin-datadog
  - serverless-typescript

特定の環境にプラグインを無効にする

環境に基づき(--stage を通じて渡された場合など)プラグインを無効にするには、以下の例のような構文を使用できます。

provider:
  stage: ${self:opt.stage, 'dev'}

custom:
  staged: ${self:custom.stageVars.${self:provider.stage}, {}}

  stageVars:
    dev:
      dd_enabled: false

  datadog:
    enabled: ${self:custom.staged.dd_enabled, true}

サーバーレスモニター

デフォルト値が事前構成された 7 つの推奨モニターがあります。

モニターメトリクスしきい値サーバーレスモニター ID
高いエラー率aws.lambda.errors/aws.lambda.invocations>= 10%high_error_rate
タイムアウトaws.lambda.duration.max/aws.lambda.timeout>= 1timeout
メモリ不足aws.lambda.enhanced.out_of_memory> 0out_of_memory
イテレータ経過時間が長いaws.lambda.iterator_age.maximum>= 24 時間high_iterator_age
高いコールドスタート率aws.lambda.enhanced.invocations(cold_start:true)/
aws.lambda.enhanced.invocations
>= 20%high_cold_start_rate
高いスロットルaws.lambda.throttles/aws.lambda.invocations>= 20%high_throttles
コストの増加aws.lambda.enhanced.estimated_cost↑20%increased_cost

推奨されるサーバーレスモニターを有効にして構成するには

推奨モニターを作成するには、それぞれのサーバーレスモニター ID を使用する必要があります。ご使用の環境に、DATADOG_API_KEY および DATADOG_APP_KEY も設定する必要があることにご注意ください。

推奨モニターのパラメーターをさらに構成する場合は、サーバーレスモニター ID の下にパラメーター値を直接定義できます。推奨モニターで指定されていないパラメーターは、デフォルトの推奨値を使用します。推奨モニターの query パラメーターは直接変更できず、デフォルトで上記で定義された値の query を使用します。ただし、options パラメーター内で再定義することにより、query のしきい値を変更できます。モニターを削除するには、serverless.yml テンプレートからモニターを削除します。モニターパラメーターの定義方法の詳細については、Datadog Monitors API を参照してください。

モニターの作成は、関数がデプロイされた後に行われます。モニターの作成に失敗した場合でも、関数は正常にデプロイされます。

デフォルト値で推奨モニターを作成するには

パラメーター値を指定せずに、適切なサーバーレスモニター ID を定義します

custom:
  datadog:
    addLayers: true
    monitors:
      - high_error_rate:
推奨モニターを構成するには
custom:
  datadog:
    addLayers: true
    monitors:
      - high_error_rate:
          name: "High Error Rate with Modified Warning Threshold"
          message: "More than 10% of the function’s invocations were errors in the selected time range. Notify @data.dog@datadoghq.com @slack-serverless-monitors"
          tags: ["modified_error_rate", "serverless", "error_rate"]
          require_full_window: true
          priority: 2
          options:
            include_tags: true
            notify_audit: true
            thresholds:
              warning: 0.05
              critical: 0.1
モニターを削除するには

サーバーレスモニター ID とそのパラメーターを削除すると、モニターが削除されます。

カスタムモニターを有効にして構成するには

カスタムモニターを定義するには、環境で API キーとアプリケーションキー (DATADOG_API_KEYDATADOG_APP_KEY) を渡すことに加えて、一意のサーバーレスモニター ID 文字列を定義する必要があります。query パラメーターは必須ですが、他のすべてのパラメーターはオプションです。一意のサーバーレスモニター ID 文字列を定義し、以下に必要なパラメーターを指定します。モニターパラメーターの詳細については、Datadog Monitors API を参照してください。

custom:
  datadog:
    addLayers: true
    monitors:
      - custom_monitor_id:
          name: "Custom Monitor"
          query: "max(next_1w):forecast(avg:system.load.1{*}, 'linear', 1, interval='60m', history='1w', model='default') >= 3"
          message: "Custom message for custom monitor. Notify @data.dog@datadoghq.com @slack-serverless-monitors"
          tags: ["custom_monitor", "serverless"]
          priority: 3
          options:
            enable_logs_sample: true
            require_full_window: true
            include_tags: false
            notify_audit: true
            notify_no_data: false
            thresholds:
              warning: 2
              critical: 3

変更の分割

v5.0.0

  • Datadog 拡張機能と併用することで、Lambda のリソースタグではなく、環境変数を通して serviceenv タグを設定するプラグインです。
  • enableTags パラメーターは、新しい serviceenv パラメーターに置き換わりました。

v4.0.0

  • Datadog Lambda 拡張機能は、Datadog へテレメトリーを送信するメカニズムのデフォルトになりました。

serverless-plugin-warmup との連携

このライブラリは serverless-plugin-warmup とベストエフォートで互換性があります。Datadog から warmer 関数を除外したい場合は、このライブラリの exclude 機能を使用します。

アプリケーションを適切にパッケージするために、このプラグインは serverless.yml ファイルの serverless-plugin-warmup の_後_に記述する必要があります

plugins:
  - serverless-plugin-warmup
  - serverless-plugin-datadog

問題を開く

このパッケージでバグが発生した場合は、問題を登録してお知らせください。新しい問題を開く前に、重複を避けるために既存の問題を検索してください。

問題を開くときは、Serverless Framework のバージョン、Python/Node.js のバージョン、および取得できる場合はスタックトレースを含めてください。さらに、必要に応じて再現手順を含めてください。

機能リクエストの問題を開くこともできます。

寄稿

このパッケージに問題が見つかり、修正された場合は、手順に従ってプルリクエストを開いてください。

コミュニティ

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

ライセンス

特に明記されていない限り、このリポジトリ内のすべてのファイルは、Apache License Version 2.0 の下でライセンスされます。

この製品には、Datadog(https://www.datadoghq.com/) で開発されたソフトウェアが含まれています。Copyright 2021 Datadog, Inc.