Datadog サーバーレスフレームワークプラグイン

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.com、または ddog-gov.com などに設定します。このパラメーターは、Datadog Lambda 拡張機能を使用してテレメトリーを収集する場合に必要です。
apiKeyDatadog API キー。このパラメーターは、Datadog Lambda 拡張機能を使用してテレメトリーを収集する際に必要です。また、デプロイ環境で DATADOG_API_KEY 環境変数を設定することも可能です。
appKeyDatadog アプリキー。monitors フィールドが定義されている場合のみ必要です。また、デプロイ環境で DATADOG_APP_KEY 環境変数を設定することも可能です。
apiKeySecretArnapiKey フィールドを使用する代替です。AWS Secrets Manager に Datadog API キーを保存しているシークレットの ARN です。Lambda の実行ロールに secretsmanager:GetSecretValue 権限を追加することを忘れないようにします。
apiKMSKeyapiKey フィールドを使用する代替です。Datadog API キーは KMS を使用して暗号化されています。Lambda の実行ロールに kms:Decrypt 権限を追加することを忘れないようにします。
envDatadog のテレメトリーに、目的の env をタグ付けします。
serviceDatadog のテレメトリーに、目的の service をタグ付けします。
versionDatadog のテレメトリーに、目的の version をタグ付けします。
enableXrayTracingLambda 関数と API Gateway 統合で X-Ray トレーシングを有効にするには、true に設定します。デフォルトは false です。
enableDDTracingLambda 関数で Datadog トレースを有効にします。デフォルトは true です。
enableDDLogsLambda 拡張機能を使用して Datadog のログ収集を有効にします。デフォルトは true です。注: この設定は、Datadog Forwarder から送信されるログには影響しません。
monitors定義すると、Datadog プラグインはデプロイされた関数のモニターを構成します。ご使用の環境で、DATADOG_API_KEY および DATADOG_APP_KEY を設定する必要があります。モニターの定義方法については、推奨されるサーバーレスモニターを有効にして構成するにはを参照してください。
captureLambdaPayloadDatadog APM のスパンで、Lambda の呼び出しに対する AWS Lambda のペイロードの入出力をキャプチャします。デフォルトは false です。
enableSourceCodeIntegration関数の Datadog ソースコードインテグレーションを有効にします。デフォルトは true です。
subscribeToApiGatewayLogsDatadog Forwarder の API Gateway ロググループへの自動サブスクリプションを有効化します。forwarderArn の設定が必要です。デフォルトは true です。
subscribeToHttpApiLogsDatadog Forwarder の HTTP API ロググループへの自動サブスクリプションを有効化します。forwarderArn の設定が必要です。デフォルトは true です。
subscribeToWebsocketLogsDatadog Forwarder の 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設定すると、指定されたハンドラーがすべての関数のハンドラーとして設定されます。
failOnErrorこのプラグインを設定すると、Datadog カスタムモニターの作成または更新が失敗した場合にエラーが生成されます。これは、デプロイ後に発生しますが、serverless deploy の結果が 0 以外の終了コードを返す原因になります(ユーザー CI を失敗にするため)。デフォルトは false です。
integrationTestingインテグレーションテストを実行するときに true に設定します。これにより、Forwarder ARN と追加した Datadog モニターの出力リンクの検証要件がバイパスされます。デフォルトは false です。
logLevelログのレベル。拡張ロギングの場合 DEBUG に設定します。

上記のパラメーターを使用するには、以下の例のように 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
Out of Memoryaws.lambda.enhanced.out_of_memory> 0out_of_memory
High Iterator Ageaws.lambda.iterator_age.maximum>= 24 hrshigh_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:
              ok: 0.025
              warning: 0.05
モニターを削除するには

サーバーレスモニター 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:
              ok: 1
              warning: 2

変更の分割

v5.0.0

  • このプラグインは、Service と ENV のタグの設定を止め、代わりに環境変数を使用します (Datadog 拡張機能と併用する場合)。

v5.0 は、Datadog 拡張機能の v10 以上、および Datadog Forwarder の全バージョンと互換性があります。

v4.0.0

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

問題を開く

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

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

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

寄稿

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

コミュニティ

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

ライセンス

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

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