Node.js サーバーレスアプリケーションのインスツルメンテーション

以前に Datadog Forwarder を使用して Lambda 関数をセットアップした場合は、Datadog Forwarder を使用したインスツルメントを参照してください。それ以外の場合は、このガイドの指示に従って、Datadog Lambda 拡張機能を使用してインスツルメンテーションを行います。
If your Lambda functions are deployed in VPC without access to the public internet, you can send data either using AWS PrivateLink for the datadoghq.com Datadog site, or using a proxy for all other sites.
webpack や esbuild を使ってバンドルしている場合、Datadog のライブラリを external としてマークする必要があるかもしれません。

インストール

Datadog は、サーバーレスアプリケーションのインスツルメンテーションを有効にするためのさまざまな方法を提供しています。以下からニーズに合った方法を選択してください。Datadog では、一般的に Datadog CLI の使用を推奨しています。アプリケーションがコンテナイメージとしてデプロイされる場合は、「コンテナイメージ」の指示に従うことが必要です。

Datadog CLI は、既存の Lambda 関数のコンフィギュレーションを修正し、新しいデプロイを必要とせずにインスツルメンテーションを可能にします。Datadog のサーバーレスモニタリングをすばやく開始するための最適な方法です。

  1. Datadog CLI クライアントをインストールする

    npm install -g @datadog/datadog-ci

  2. Datadog サーバーレスモニタリングに慣れていない場合は、クイックスタートとして最初のインストールを導くためにインタラクティブモードで Datadog CLI を起動し、残りのステップを無視することができます。本番アプリケーションに Datadog を恒久的にインストールするには、このステップをスキップし、残りのステップに従って通常のデプロイの_後に_ CI/CD パイプラインで Datadog CLI コマンドを実行します。

    datadog-ci lambda instrument -i

  3. AWS の認証情報を構成する

    Datadog CLI は、AWS Lambda サービスへのアクセスを必要とし、AWS JavaScript SDK に依存して資格情報を解決します。AWS CLI を呼び出すときに使用するのと同じ方法を使用して、AWS の資格情報が構成されていることを確認します。

  4. Datadog サイトを構成する

    export DATADOG_SITE="<DATADOG_SITE>"

    <DATADOG_SITE> を datadoghq.com に置き換えます。(右側で正しい SITE が選択されていることを確認してください)。

  5. Datadog API キーを構成する

    Datadog は、セキュリティと簡単なローテーションのために、AWS Secrets Manager に Datadog API キーを保存することを推奨します。キーはプレーンテキスト文字列として保存する必要があります (JSON blob ではありません)。Lambda 関数に必要な secretsmanager:GetSecretValue IAM 権限があることを確認します。

    export DATADOG_API_KEY_SECRET_ARN="<DATADOG_API_KEY_SECRET_ARN>"

    迅速なテスト目的のために、Datadog API キーをプレーンテキストで設定することも可能です。

    export DATADOG_API_KEY="<DATADOG_API_KEY>"

  6. Lambda 関数をインスツルメントする

    注: Lambda 関数は、まず開発環境またはステージング環境でインスツルメントしてください。インスツルメンテーションの結果が思わしくない場合は、同じ引数で uninstrument を実行し、変更を元に戻してください。

    Lambda 関数をインスツルメントするには、次のコマンドを実行します。

    datadog-ci lambda instrument -f <functionname> -f <another_functionname> -r <aws_region> -v 121 -e 75

    プレースホルダーを埋めるには

    • <functionname> と <another_functionname> は Lambda 関数の名前に置き換えます。また、--functions-regex を使用すると、指定した正規表現にマッチする名前を持つ複数の関数を自動的にインスツルメントすることができます。
    • <aws_region> を AWS リージョン名に置き換えます。

    その他のパラメーターは、CLI ドキュメントに記載されています。

代わりに、JavaScript ファイルから JSON オブジェクトをネイティブにエクスポートして (たとえば serverless.ts ファイルを使用して) Serverless Framework アプリをデプロイする場合は、カスタムインストール手順に従います。

Datadog Serverless Plugin は、Datadog Lambda 拡張機能 を介してメトリクス、トレース、ログを Datadog に送信するように関数を自動的に構成します。

Datadog サーバーレスプラグインをインストールして構成するには、次の手順に従います。

  1. Datadog サーバーレスプラグインをインストールします。

    serverless plugin install --name serverless-plugin-datadog

  2. serverless.yml を更新します:

    custom:
  datadog:
    site: <DATADOG_SITE>
    apiKeySecretArn: <DATADOG_API_KEY_SECRET_ARN>

    プレースホルダーを埋めるには

    • <DATADOG_SITE> を datadoghq.com に置き換えます。(右側で正しい SITE が選択されていることを確認してください)。
    • <DATADOG_API_KEY_SECRET_ARN> を、Datadog API キーが安全に保存されている AWS シークレットの ARN に置き換えます。キーはプレーンテキスト文字列として保存する必要があります (JSON blob ではありません)。また、secretsmanager:GetSecretValue権限が必要です。迅速なテストのために、代わりに apiKey を使用して、Datadog API キーをプレーンテキストで設定することができます。

    詳細および追加設定については、プラグインドキュメントを参照してください。

Datadog CloudFormation マクロは、SAM アプリケーションのテンプレートを自動的に変換して Lambda レイヤーを使用して関数に Datadog をインストールし、Datadog Lambda 拡張機能を通じて Datadog にメトリクス、トレース、ログを送信するように関数を構成します。

  1. Datadog CloudFormation マクロのインストール

    AWS 認証情報で次のコマンドを実行して、マクロ AWS リソースをインストールする CloudFormation スタックをデプロイします。アカウントの特定のリージョンに一度だけマクロをインストールする必要があります。マクロを最新バージョンに更新するには、create-stack を update-stack に置き換えます。

    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

    マクロが表示され、使用を開始できます。

  2. Lambda 関数をインスツルメントする

    SAM の template.yml の Transform セクションで、 AWS::Serverless 変換の後に DatadogServerless 変換を追加します。

    Transform:
  - AWS::Serverless-2016-10-31
  - Name: DatadogServerless
    Parameters:
      stackName: !Ref "AWS::StackName"
      nodeLayerVersion: 121
      extensionLayerVersion: 75
      site: "<DATADOG_SITE>"
      apiKeySecretArn: "<DATADOG_API_KEY_SECRET_ARN>"

    プレースホルダーを埋めるには

    • <DATADOG_SITE> を datadoghq.com に置き換えます。(右側で正しい SITE が選択されていることを確認してください)。
    • <DATADOG_API_KEY_SECRET_ARN> を、Datadog API キーが安全に保存されている AWS シークレットの ARN に置き換えます。キーはプレーンテキスト文字列として保存する必要があります (JSON blob ではありません)。また、secretsmanager:GetSecretValue権限が必要です。迅速なテストのために、代わりに apiKey を使用して、Datadog API キーをプレーンテキストで設定することができます。

    マクロのドキュメントに詳細と追加のパラメーターがあります。

Datadog CDK コンストラクト は、Lambda レイヤーを使用して Datadog を関数に自動的にインストールし、Datadog Lambda 拡張機能を介してメトリクス、トレース、ログを Datadog に送信するように関数を構成します。

  1. Datadog CDK コンストラクトライブラリのインストール

    # For AWS CDK v1
npm install datadog-cdk-constructs --save-dev

# For AWS CDK v2
npm install datadog-cdk-constructs-v2 --save-dev

  2. Lambda 関数をインスツルメントする

    // For AWS CDK v1
import { Datadog } from "datadog-cdk-constructs";

// For AWS CDK v2
import { Datadog } from "datadog-cdk-constructs-v2";

const datadog = new Datadog(this, "Datadog", {
    nodeLayerVersion: 121,
    extensionLayerVersion: 75,
    site: "<DATADOG_SITE>",
    apiKeySecretArn: "<DATADOG_API_KEY_SECRET_ARN>"
});
datadog.addLambdaFunctions([<LAMBDA_FUNCTIONS>])

    プレースホルダーを埋めるには

    • <DATADOG_SITE> を datadoghq.com に置き換えます。(右側で正しい SITE が選択されていることを確認してください)。
    • <DATADOG_API_KEY_SECRET_ARN> を、Datadog API キーが安全に保存されている AWS シークレットの ARN に置き換えます。キーはプレーンテキスト文字列として保存する必要があります (JSON blob ではありません)。また、secretsmanager:GetSecretValue権限が必要です。迅速なテストのために、代わりに apiKey を使用して、Datadog API キーをプレーンテキストで設定することができます。

    Datadog CDK のドキュメントに詳細と追加のパラメーターがあります。

  1. Datadog Lambda ライブラリのインストール

    Lambda 関数をコンテナイメージとしてデプロイする場合は、Datadog Lambda ライブラリを Lambda レイヤーとして使用できません。代わりに、イメージ内に Datadog Lambda とトレーシングライブラリをパッケージ化する必要があります。

    npm install datadog-lambda-js dd-trace

    datadog-lambda-js パッケージのマイナーバージョンは、常にレイヤーのバージョンに一致します。たとえば、datadog-lambda-js v0.5.0 は、レイヤーバージョン 5 のコンテンツに一致します。

  2. Datadog Lambda 拡張機能のインストール

    Dockerfile に以下を追加して、Datadog Lambda 拡張機能をコンテナイメージに追加します。

    COPY --from=public.ecr.aws/datadog/lambda-extension:<TAG> /opt/. /opt/

    <TAG> を特定のバージョン番号 (例えば 75) または latest に置き換えてください。Alpine も特定のバージョン番号 (例えば 75-alpine) または latest-alpine でサポートされています。Amazon ECR リポジトリで、使用可能なタグの完全なリストを見ることができます。

  3. ハンドラー関数のリダイレクト

    • イメージの CMD 値を node_modules/datadog-lambda-js/dist/handler.handler に設定します。AWS で設定するか、Dockerfile 内で直接設定します。なお、両方の値を設定した場合、AWS で設定した値が Dockerfile 内の値をオーバーライドします。
    • 元のハンドラーに、環境変数 DD_LAMBDA_HANDLER を設定します。例: myfunc.handler。
    • コンテナで ESModule を使用している場合、handler.js ファイルを削除する必要があります。このファイルは Node 12 用に存在し、AWS が Node 12 のサポートを非推奨にしたときに削除されます。
      RUN rm node_modules/datadog-lambda-js/dist/handler.js
CMD ["node_modules/datadog-lambda-js/dist/handler.handler"]

    注: Lambda 関数が arm64 で実行される場合、コンテナイメージを arm64 ベースの Amazon Linux 環境で構築するか、代わりに関数コードで Datadog ラッパーを適用する必要があります。また、Datadog ハンドラーのリダイレクトと互換性のないサードパーティのセキュリティツールや監視ツールを使用している場合、そのようなことが必要になる場合があります。

  4. Datadog サイトと API キーの構成

    • 環境変数 DD_SITE に datadoghq.com を設定します。(右側で正しい SITE が選択されていることを確認してください)。
    • 環境変数 DD_API_KEY_SECRET_ARN を、Datadog API キーが安全に保存されている AWS シークレットの ARN で設定します。キーはプレーンテキスト文字列として保存する必要があります (JSON blob ではありません)。また、secretsmanager:GetSecretValue権限が必要です。迅速なテストのために、代わりに DD_API_KEY を使用して、Datadog API キーをプレーンテキストで設定することができます。

lambda-datadog Terraform モジュールは aws_lambda_function リソースをラップし、Datadog サーバーレスモニタリング用に以下の方法で Lambda 関数を自動的に設定します。

  • Datadog Lambda レイヤーを追加する
  • Lambda ハンドラーをリダイレクトする
  • メトリクス、トレース、ログの収集と Datadog への送信を有効にする
module "lambda-datadog" {
  source  = "DataDog/lambda-datadog/aws"
  version = "2.0.0"

  environment_variables = {
    "DD_API_KEY_SECRET_ARN" : "<DATADOG_API_KEY_SECRET_ARN>"
    "DD_ENV" : "<ENVIRONMENT>"
    "DD_SERVICE" : "<SERVICE_NAME>"
    "DD_SITE": "<DATADOG_SITE>"
    "DD_VERSION" : "<VERSION>"
  }

  datadog_extension_layer_version = 67
  datadog_node_layer_version = 117

  # aws_lambda_function arguments
}

  1. aws_lambda_function リソースを lambda-datadog Terraform モジュールに置き換えます。次に、モジュールの source と version を指定します。

  2. aws_lambda_function 引数を設定します。

    aws_lambda_function リソースで利用可能なすべての引数は、この Terraform モジュールでも使用できます。aws_lambda_function リソースでブロックとして定義された引数は、ネストされた引数を含む変数として再定義されます。

    たとえば、aws_lambda_function では、environment は variables 引数を持つブロックとして定義されています。lambda-datadog Terraformモジュールでは、environment_variables の値が aws_lambda_function の environment.variables 引数に渡されます。このモジュールの変数の完全なリストは Inputs を参照してください。

  3. 環境変数のプレースホルダーを埋めます。

    • <DATADOG_API_KEY_SECRET_ARN> を、Datadog API キーが安全に保存されている AWS シークレットの ARN に置き換えます。キーはプレーンテキスト文字列として保存する必要があります (JSON blob ではありません)。また、secretsmanager:GetSecretValue権限が必要です。迅速なテストのために、代わりに環境変数 DD_API_KEY を使用して、Datadog API キーをプレーンテキストで設定することができます。
    • <ENVIRONMENT> を prod や staging などの Lambda 関数の環境に置き換えます。　
    • <SERVICE_NAME> を Lambda 関数のサービス名に置き換えます。
    • <DATADOG_SITE> を datadoghq.com に置き換えます。(このページで正しい Datadog サイトが選択されていることを確認してください。)
    • <VERSION> を Lambda 関数のバージョン番号に置き換えます。

  4. 使用する Datadog 拡張機能 Lambda レイヤーと Datadog Node.js Lambda レイヤーのバージョンを選択します。デフォルトは、レイヤーの最新バージョンになります。

  datadog_extension_layer_version = 67
  datadog_node_layer_version = 117
Datadog がサポートする Serverless Framework や AWS CDK などのサーバーレス開発ツールを使用していない場合、Datadog は Datadog CLI を使用してサーバーレスアプリケーションをインスツルメントすることを強く推奨します。

  1. Datadog Lambda ライブラリのインストール

    Datadog Lambda ライブラリは、レイヤー (推奨) または JavaScript パッケージのどちらかとしてインポートすることができます。

    datadog-lambda-js パッケージのマイナーバージョンは、常にレイヤーのバージョンに一致します。たとえば、datadog-lambda-js v0.5.0 は、レイヤーバージョン 5 のコンテンツに一致します。

    • オプション A: 以下のフォーマットで、ARN を使用して Lambda 関数にレイヤーを構成します。

      # Use this format for AWS commercial regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-<RUNTIME>:121

# Use this format for AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-<RUNTIME>:121

      <AWS_REGION> を us-east-1 などの有効な AWS リージョンに置き換えます。<RUNTIME> オプションは、Node18-x, Node20-x, Node22-x が利用可能です。

    • オプション B: もし、ビルド済みの Datadog Lambda レイヤーを使用できない場合は、お気に入りのパッケージマネージャーを使用して、パッケージ datadog-lambda-js と dd-trace をインストールすることができます。

      npm install datadog-lambda-js dd-trace

  2. Datadog Lambda 拡張機能のインストール

    以下のフォーマットで、ARN を使用して Lambda 関数にレイヤーを構成します。

    # Use this format for x86-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-Extension:75

# Use this format for arm64-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-Extension-ARM:75

# Use this format for x86-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-Extension:75

# Use this format for arm64-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-Extension-ARM:75

    <AWS_REGION> を us-east-1 などの有効な AWS リージョンに置き換えてください。

  3. ハンドラー関数のリダイレクト

    • 関数のハンドラーを、レイヤーを使用する場合は /opt/nodejs/node_modules/datadog-lambda-js/handler.handler に、パッケージを使用する場合は node_modules/datadog-lambda-js/dist/handler.handler に設定します。
    • 元のハンドラーに、環境変数 DD_LAMBDA_HANDLER を設定します。例: myfunc.handler。

    注: Lambda 関数が arm64 で実行され、datadog-lambda-js ライブラリが NPM パッケージとしてインストールされている場合 (ステップ 1 のオプション B)、代わりに関数コードで Datadog ラッパーを適用する必要があります。また、Datadog ハンドラーのリダイレクトと互換性のないサードパーティのセキュリティツールや監視ツールを使用している場合、そのようなことが必要になる場合があります。

  4. Datadog サイトと API キーの構成

    • 環境変数 DD_SITE に datadoghq.com を設定します。(右側で正しい SITE が選択されていることを確認してください)。
    • 環境変数 DD_API_KEY_SECRET_ARN を、Datadog API キーが安全に保存されている AWS シークレットの ARN で設定します。キーはプレーンテキスト文字列として保存する必要があります (JSON blob ではありません)。また、secretsmanager:GetSecretValue権限が必要です。迅速なテストのために、代わりに DD_API_KEY を使用して、Datadog API キーをプレーンテキストで設定することができます。

次のステップ

  • おめでとうございます。Serverless Homepage でメトリクス、ログ、トレースを見ることができるようになりました。
  • サービスを標的にしている攻撃者についてアラートを受け取るには、脅威の監視を有効にします。
  • カスタムビジネスロジックの監視のサンプルコードを参照してください
  • テレメトリーの収集に問題がある場合は、トラブルシューティングガイドを参照してください
  • 高度な構成を参照して以下のことを行ってください。
    • タグを使ったテレメトリー接続
    • Amazon API Gateway、SQS などのテレメトリーを収集する
    • Lambda のリクエストとレスポンスのペイロードを取得する
    • Lambda 関数のエラーをソースコードにリンクする
    • ログまたはトレースから機密情報をフィルタリングまたはスクラブする

カスタムビジネスロジックの監視

カスタムビジネスロジックを監視するには、以下のサンプルコードを使用してカスタムメトリクスまたはスパンを送信します。その他のオプションについては、サーバーレスアプリケーションのためのカスタムメトリクスの送信およびカスタムインスツルメンテーションのための APM ガイドを参照してください。

const { sendDistributionMetric, sendDistributionMetricWithDate } = require('datadog-lambda-js');
const tracer = require('dd-trace');

// カスタムスパン "sleep" を送信
const sleep = tracer.wrap('sleep', (ms) => {
    return new Promise((resolve) => setTimeout(resolve, ms));
});

exports.handler = async (event) => {
    // Lambda 関数 span にカスタムタグを追加
    // X-Rayトレースが有効な場合、動作しない
    const span = tracer.scope().active();
    span.setTag('customer_id', '123456');

    await sleep(100);

    // カスタムスパンを送信
    const sandwich = tracer.trace('hello.world', () => {
        console.log('Hello, World!');
    });

    // カスタムメトリクスを送信
    sendDistributionMetric(
        'coffee_house.order_value', // メトリクス名
        12.45, // メトリクス値
        'product:latte', // タグ
        'order:online' // 他のタグ
    );

    const response = {
        statusCode: 200,
        body: JSON.stringify('Hello from serverless!')
    };
    return response;
};

その他の参考資料

お役に立つドキュメント、リンクや記事:

サーバーレスモニタリングの構成ドキュメント more more Node.js Lambda トレースとバンドラーの互換性ドキュメント more more サーバーレスモニタリングのトラブルシューティングドキュメント more more サーバーレスアプリケーションからのカスタムメトリクスの送信ドキュメント more more
PREVIEWING: jen.gilbert/cdocs-build