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

以前に Datadog Forwarder を使用して Lambda 関数をセットアップした場合は、Datadog Forwarder を使用したインスツルメントを参照してください。

Lambda 関数が公共のインターネットにアクセスできない VPC にデプロイされている場合、datadoghq.com Datadog サイトには AWS PrivateLink を、それ以外のサイトにはプロキシを使用してデータを送信することができます。

webpack や esbuild を使ってバンドルしている場合、Datadog のライブラリを external としてマークする必要があるかもしれません。

インストール

Datadog は、サーバーレスアプリケーションのインスツルメンテーションを有効にするためのさまざまな方法を提供しています。以下からニーズに合った方法を選択してください。Datadog では、一般的に Datadog CLI の使用を推奨しています。

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

Datadog CLI クライアントをインストールする
```
npm install -g @datadog/datadog-ci
```
Datadog サーバーレスモニタリングに慣れていない場合は、クイックスタートとして最初のインストールを導くためにインタラクティブモードで Datadog CLI を起動し、残りのステップを無視することができます。本番アプリケーションに Datadog を恒久的にインストールするには、このステップをスキップし、残りのステップに従って通常のデプロイの_後に_ CI/CD パイプラインで Datadog CLI コマンドを実行します。
```
datadog-ci lambda instrument -i
```
AWS の認証情報を構成する
Datadog CLI は、AWS Lambda サービスへのアクセスを必要とし、AWS JavaScript SDK に依存して資格情報を解決します。AWS CLI を呼び出すときに使用するのと同じ方法を使用して、AWS の資格情報が構成されていることを確認します。
Datadog サイトを構成する
テレメトリーの送信先である Datadog サイトを指定します。デフォルトは datadoghq.com です。
```
export DATADOG_SITE="<DD_SITE>" # such as datadoghq.com, datadoghq.eu or ddog-gov.com
```
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>"
```
Lambda 関数をインスツルメントする
注: Lambda 関数は、まず開発環境またはステージング環境でインスツルメントしてください。インスツルメンテーションの結果が思わしくない場合は、同じ引数で uninstrument を実行し、変更を元に戻してください。
Lambda 関数をインスツルメントするには、次のコマンドを実行します。
```
datadog-ci lambda instrument -f <functionname> -f <another_functionname> -r <aws_region> -v 80 -e 23
```
プレースホルダーを埋めるには
- <functionname> と <another_functionname> は Lambda 関数の名前に置き換えます。また、--functions-regex を使用すると、指定した正規表現にマッチする名前を持つ複数の関数を自動的にインスツルメントすることができます。
- <aws_region> を AWS リージョン名に置き換えます。
その他のパラメーターは、CLI ドキュメントに記載されています。

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

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

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

Datadog サーバーレスプラグインをインストールします。
```
serverless plugin install --name serverless-plugin-datadog
```
serverless.yml を更新します:
```
custom:
  datadog:
    site: <DATADOG_SITE>
    apiKeySecretArn: <DATADOG_API_KEY_SECRET_ARN>
```
プレースホルダーを埋めるには
- <DATADOG_SITE> を、テレメトリーの送信先となる Datadog サイトに置き換えます。
- <DATADOG_API_KEY_SECRET_ARN> を、Datadog API キーが安全に保存されている AWS シークレットの ARN に置き換えます。キーはプレーンテキスト文字列として保存する必要があります (JSON blob ではありません)。また、secretsmanager:GetSecretValue権限が必要です。迅速なテストのために、代わりに apiKey を使用して、Datadog API キーをプレーンテキストで設定することができます。
詳細および追加設定については、プラグインドキュメントを参照してください。

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

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
```
マクロが表示され、使用を開始できます。
Lambda 関数をインスツルメントする
SAM の template.yml の Transform セクションで、 AWS::Serverless 変換の後に DatadogServerless 変換を追加します。
```
Transform:
  - AWS::Serverless-2016-10-31
  - Name: DatadogServerless
    Parameters:
      stackName: !Ref "AWS::StackName"
      nodeLayerVersion: 80
      extensionLayerVersion: 23
      site: "<DATADOG_SITE>"
      apiKeySecretArn: "<DATADOG_API_KEY_SECRET_ARN>"
```
プレースホルダーを埋めるには
- <DATADOG_SITE> を、テレメトリーの送信先となる Datadog サイトに置き換えます。
- <DATADOG_API_KEY_SECRET_ARN> を、Datadog API キーが安全に保存されている AWS シークレットの ARN に置き換えます。キーはプレーンテキスト文字列として保存する必要があります (JSON blob ではありません)。また、secretsmanager:GetSecretValue権限が必要です。迅速なテストのために、代わりに apiKey を使用して、Datadog API キーをプレーンテキストで設定することができます。
マクロのドキュメントに詳細と追加のパラメーターがあります。

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

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

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: 80,
    extensionLayerVersion: 23,
    site: "<DATADOG_SITE>",
    apiKeySecretArn: "<DATADOG_API_KEY_SECRET_ARN>"
});
datadog.addLambdaFunctions([<LAMBDA_FUNCTIONS>])
```
プレースホルダーを埋めるには
- <DATADOG_SITE> を、テレメトリーの送信先となる Datadog サイトに置き換えます。
- <DATADOG_API_KEY_SECRET_ARN> を、Datadog API キーが安全に保存されている AWS シークレットの ARN に置き換えます。キーはプレーンテキスト文字列として保存する必要があります (JSON blob ではありません)。また、secretsmanager:GetSecretValue権限が必要です。迅速なテストのために、代わりに apiKey を使用して、Datadog API キーをプレーンテキストで設定することができます。
Datadog CDK のドキュメントに詳細と追加のパラメーターがあります。

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 のコンテンツに一致します。
Datadog Lambda 拡張機能のインストール
Dockerfile に以下を追加して、Datadog Lambda 拡張機能をコンテナイメージに追加します。
```
COPY --from=public.ecr.aws/datadog/lambda-extension:<TAG> /opt/extensions/ /opt/extensions
```
<TAG> を特定のバージョン番号 (たとえば 23) または latest に置き換えます。利用可能なタグのリストは、Amazon ECR リポジトリで確認できます。
ハンドラー関数のリダイレクト
- イメージの CMD 値を node_modules/datadog-lambda-js/dist/handler.handler に設定します。AWS で設定するか、Dockerfile 内で直接設定します。なお、両方の値を設定した場合、AWS で設定した値が Dockerfile 内の値をオーバーライドします。
- 元のハンドラーに、環境変数 DD_LAMBDA_HANDLER を設定します。例: myfunc.handler。
注: Lambda 関数が arm64 で実行する場合、コンテナイメージを arm64 ベースの Amazon Linux 環境で構築するか、代わりに関数コードで Datadog ラッパーを適用する必要があります。また、Datadog ハンドラーのリダイレクトと互換性のないサードパーティのセキュリティツールや監視ツールを使用している場合、そのようなことが必要になる場合があります。
Datadog サイトと API キーの構成
- 環境変数 DD_SITE に、テレメトリー送信先の Datadog サイトを設定します。
- 環境変数 DD_API_KEY_SECRET_ARN を、Datadog API キーが安全に保存されている AWS シークレットの ARN で設定します。キーはプレーンテキスト文字列として保存する必要があります (JSON blob ではありません)。また、secretsmanager:GetSecretValue権限が必要です。迅速なテストのために、代わりに DD_API_KEY を使用して、Datadog API キーをプレーンテキストで設定することができます。

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

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>:80

# Use this format for AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-<RUNTIME>:80
```
  <AWS_REGION> を us-east-1 などの有効な AWS リージョンに置き換えてください。RUNTIME オプションは、Node12-x、Node14-x または Node16-x が利用可能です。
- オプション B: もし、ビルド済みの Datadog Lambda レイヤーを使用できない場合は、お気に入りのパッケージマネージャーを使用して、パッケージ datadog-lambda-js と dd-trace をインストールすることができます。
```
npm install datadog-lambda-js dd-trace
```

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:23

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

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

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

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

ハンドラー関数のリダイレクト
- 関数のハンドラーを、レイヤーを使用する場合は /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 ハンドラーのリダイレクトと互換性のないサードパーティのセキュリティツールや監視ツールを使用している場合、そのようなことが必要になる場合があります。
Datadog サイトと API キーの構成
- 環境変数 DD_SITE に、テレメトリー送信先の Datadog サイトを設定します。
- 環境変数 DD_API_KEY_SECRET_ARN を、Datadog API キーが安全に保存されている AWS シークレットの ARN で設定します。キーはプレーンテキスト文字列として保存する必要があります (JSON blob ではありません)。また、secretsmanager:GetSecretValue権限が必要です。迅速なテストのために、代わりに DD_API_KEY を使用して、Datadog API キーをプレーンテキストで設定することができます。

次のステップ

おめでとうございます。Serverless Homepage でメトリクス、ログ、トレースを見ることができるようになりました。
カスタムビジネスロジックの監視のサンプルコードを参照してください
テレメトリーの収集に問題がある場合は、トラブルシューティングガイドを参照してください
高度な構成を参照して以下のことを行ってください。
- タグを使ったテレメトリー接続
- AWS 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;
};