Node.js サーバーレスアプリケーションのインスツルメンテーション
Datadog Lambda Extension バージョン 67 以降では、コールドスタート時間を大幅に短縮するよう最適化されています。
さらに詳しくセットアップ
Datadog CLI は、既存の Lambda 関数の構成を修正し、新しいデプロイを必要とせずにインスツルメンテーションを可能にします。Datadog のサーバーレスモニタリングをすばやく開始するための最適な方法です。
Datadog CLI クライアントをインストールします。
npm install -g @datadog/datadog-ci @datadog/datadog-ci-plugin-lambda
Datadog のサーバーレスモニタリングを初めて使用する場合は、Datadog CLI をインタラクティブモードで起動して初回インストールをガイドできます。その場合、以降のステップは省略できます。本番アプリケーションに Datadog を永続的にインストールするには、このステップをスキップし、残りのステップに従って、通常の_デプロイ後_に CI/CD パイプラインで Datadog CLI コマンドを実行してください。
datadog-ci lambda instrument -i
AWS の認証情報を構成します。
Datadog CLI は AWS Lambda サービスへのアクセスを必要とし、AWS JavaScript SDK に依存して[認証情報を解決][1]します。AWS CLI を呼び出すときと同じ方法で、AWS 認証情報が構成されていることを確認してください。
Datadog サイトを構成します。
export DATADOG_SITE="<DATADOG_SITE>"
Replace <DATADOG_SITE> with (右側で正しいサイトが選択されていることを確認してください)。
Datadog API キーを構成します。
Datadog は、セキュリティと容易なローテーションのために、Datadog API キーを AWS Secrets Manager に保存することを推奨します。キーはプレーンテキストの文字列として保存する必要があります (JSON ブロブではありません)。Lambda 関数に必要な secretsmanager:GetSecretValue IAM 権限があることを確認してください。
export DATADOG_API_KEY_SECRET_ARN="<DATADOG_API_KEY_SECRET_ARN>"
For quick testing purposes, you can also set the Datadog API key in plaintext:
export DATADOG_API_KEY="<DATADOG_API_KEY>"
Lambda 関数をインスツルメントします。
*注: Lambda 関数は、まず開発環境またはステージング環境でインスツルメントしてください。インスツルメンテーションの結果が思わしくない場合は、同じ引数で uninstrument を実行し、変更を元に戻してください。
Lambda 関数をインスツルメントするには、次のコマンドを実行します。
datadog-ci lambda instrument -f <functionname> -f <another_functionname> -r <aws_region> -v 144 -e 103
To fill in the placeholders:
- Replace `<functionname>` and `<another_functionname>` with your Lambda function names. Alternatively, you can use `--functions-regex` to automatically instrument multiple functions whose names match the given regular expression.
- Replace `<aws_region>` with the AWS region name.
Additional parameters can be found in the [CLI documentation][2].
[1]: https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials-node.html
[2]: https://docs.datadoghq.com/ja/serverless/serverless_integrations/cli
Datadog Serverless Plugin は、Datadog Lambda Extension を介してメトリクス、トレース、ログを Datadog に送信するように関数を自動的に構成します。
Datadog サーバーレスプラグインをインストールして構成するには、次の手順に従います。
Datadog サーバーレスプラグインをインストールします。
serverless plugin install --name serverless-plugin-datadog
serverless.yml を更新します。
custom:
datadog:
site: <DATADOG_SITE>
apiKeySecretArn: <DATADOG_API_KEY_SECRET_ARN>
To fill in the placeholders:
- Replace
<DATADOG_SITE> with (右側で正しいサイトが選択されていることを確認してください)。 <DATADOG_API_KEY_SECRET_ARN> を、Datadog API キーが安全に保存されている AWS シークレットの ARN に置き換えてください。キーはプレーンテキストの文字列として保存する必要があります (JSON ブロブではありません)。secretsmanager:GetSecretValue の権限が必要です。迅速なテストのために、代わりに apiKey を使用し、Datadog API キーをプレーンテキストで設定できます。
For more information and additional settings, see the plugin documentation.
Datadog CloudFormation マクロは、SAM アプリケーションのテンプレートを自動的に変換して Lambda レイヤーを使用して関数に Datadog をインストールし、Datadog Lambda Extension を通じて 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
The macro is now deployed and ready to use.
Lambda 関数をインスツルメントします。
Transform セクション内の template.yml ファイルにある AWS::Serverless 変換の後に、DatadogServerless 変換を追加してください(SAM 用)。
Transform:
- AWS::Serverless-2016-10-31
- Name: DatadogServerless
Parameters:
stackName: !Ref "AWS::StackName"
nodeLayerVersion: 144
extensionLayerVersion: 103
site: "<DATADOG_SITE>"
apiKeySecretArn: "<DATADOG_API_KEY_SECRET_ARN>"
To fill in the placeholders:
- Replace
<DATADOG_SITE> with (右側で正しいサイトが選択されていることを確認してください)。 <DATADOG_API_KEY_SECRET_ARN> を、Datadog API キーが安全に保存されている AWS シークレットの ARN に置き換えてください。キーはプレーンテキストの文字列として保存する必要があります (JSON ブロブではありません)。secretsmanager:GetSecretValue の権限が必要です。迅速なテストのために、代わりに apiKey を使用し、Datadog API キーをプレーンテキストで設定できます。
More information and additional parameters can be found in the macro documentation.
Instrumenting Node functions through the Datadog CDK construct is only available for AWS CDK apps written in Typescript, Python, and Go.
The Datadog CDK construct automatically installs Datadog on your functions using Lambda layers. It configures your functions to send metrics, traces, and logs to Datadog through the Datadog Lambda Extension.
TypeScript
Install the Datadog CDK constructs library
For AWS CDK v1:
npm install datadog-cdk-constructs --save-dev
For AWS CDK v2:
npm install datadog-cdk-constructs-v2 --save-dev
Instrument your Lambda functions
For AWS CDK v1:
import { Datadog } from "datadog-cdk-constructs";
const datadog = new Datadog(this, "Datadog", {
nodeLayerVersion: 144,
extensionLayerVersion: 103,
site: "<DATADOG_SITE>",
apiKeySecretArn: "<DATADOG_API_KEY_SECRET_ARN>"
});
datadog.addLambdaFunctions([<LAMBDA_FUNCTIONS>])
For AWS CDK v2:
import { DatadogLambda } from "datadog-cdk-constructs-v2";
const datadogLambda = new DatadogLambda(this, "datadogLambda", {
nodeLayerVersion: 144,
extensionLayerVersion: 103,
site: "<DATADOG_SITE>",
apiKeySecretArn: "<DATADOG_API_KEY_SECRET_ARN>"
});
datadogLambda.addLambdaFunctions([<LAMBDA_FUNCTIONS>])
Python
Install the Datadog CDK constructs library
For AWS CDK v1:
pip install datadog-cdk-constructs
For AWS CDK v2:
pip install datadog-cdk-constructs-v2
Instrument your Lambda functions
For AWS CDK v1:
from datadog_cdk_constructs import Datadog
datadog = Datadog(self, "Datadog",
node_layer_version=144,
extension_layer_version=103,
site="<DATADOG_SITE>",
api_key_secret_arn="<DATADOG_API_KEY_SECRET_ARN>",
)
datadog.add_lambda_functions([<LAMBDA_FUNCTIONS>])
For AWS CDK v2:
from datadog_cdk_constructs_v2 import DatadogLambda
datadog = DatadogLambda(self, "datadogLambda",
node_layer_version=144,
extension_layer_version=103,
site="<DATADOG_SITE>",
api_key_secret_arn="<DATADOG_API_KEY_SECRET_ARN>",
)
datadog.add_lambda_functions([<LAMBDA_FUNCTIONS>])
Go
Note: Go CDK constructs are only available for AWS CDK v2.
Install the Datadog CDK constructs library
go get github.com/DataDog/datadog-cdk-constructs-go/ddcdkconstruct/v3
Instrument your Lambda functions
import (
"github.com/DataDog/datadog-cdk-constructs-go/ddcdkconstruct/v3"
)
datadogLambda := ddcdkconstruct.NewDatadogLambda(
stack,
jsii.String("Datadog"),
&ddcdkconstruct.DatadogLambdaProps{
NodeLayerVersion: jsii.Number(144),
ExtensionLayerVersion: jsii.Number(103),
Site: jsii.String("<DATADOG_SITE>"),
ApiKeySecretArn: jsii.String("<DATADOG_API_KEY_SECRET_ARN>"),
})
datadogLambda.AddLambdaFunctions(&[]interface{}{<LAMBDA_FUNCTIONS>}, nil)
To fill in the placeholders:
- Replace
<DATADOG_SITE> with
(ensure the correct SITE is selected on the right). - Replace
<DATADOG_API_KEY_SECRET_ARN> with the ARN of the AWS secret where your Datadog API key is securely stored. The key needs to be stored as a plaintext string (not a JSON blob). Ensure your Lambda execution role has the secretsmanager:GetSecretValue IAM permission in order to read the secret value. For quick testing, you can use apiKey instead and set the Datadog API key in plaintext.
More information and additional parameters can be found on the Datadog CDK documentation.
Datadog Lambda ライブラリをインストールします。
Datadog Lambda と SDK をイメージ内にパッケージ化します。
npm install datadog-lambda-js dd-trace
Note that the minor version of the datadog-lambda-js package always matches the layer version. For example, datadog-lambda-js v0.5.0 matches the content of layer version 5.
You cannot install the Datadog Lambda Library as a layer if you are deploying your Lambda function as a container image.
Datadog Lambda Extension をインストールする
Dockerfile に以下を追加して、Datadog Lambda Extension をコンテナイメージに追加します。
COPY --from=public.ecr.aws/datadog/lambda-extension:<TAG> /opt/. /opt/
Replace <TAG> with either a specific version number (for example, 103) or with latest. Alpine is also supported with specific version numbers (such as 103-alpine) or with latest-alpine.Amazon ECR リポジトリで、使用可能なタグの完全なリストを確認できます。
ハンドラー関数をリダイレクトします。
- イメージの
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"]
Note: If your Lambda function runs on arm64, you must either build your container image in an arm64-based Amazon Linux environment or apply the Datadog wrapper in your function code instead. You may also need to do that if you are using a third-party security or monitoring tool that is incompatible with the Datadog handler redirection.
Datadog サイトと API キーを構成します。
- 環境変数
DD_SITE を (右側で正しいサイトが選択されていることを確認してください)。 - Datadog API キーが安全に保存されている AWS シークレットの ARN を環境変数
DD_API_KEY_SECRET_ARN に設定します。キーはプレーンテキストの文字列として保存する必要があります (JSON ブロブではありません)。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 = "4.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 = 103
datadog_node_layer_version = 144
# aws_lambda_function arguments
}
aws_lambda_function リソースを lambda-datadog Terraform モジュールに置き換えます。次に、モジュールの source と version を指定します。
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 引数に渡されます。このモジュールの変数の完全なリストについては、入力を参照してください。
環境変数のプレースホルダーを埋めます。
<DATADOG_API_KEY_SECRET_ARN> を、Datadog API キーが安全に保存されている AWS シークレットの ARN に置き換えます。キーはプレーンテキストの文字列として保存する必要があります (JSON ブロブではありません)。secretsmanager:GetSecretValue の権限が必要です。迅速なテストのために、代わりに環境変数 DD_API_KEY を使用し、Datadog API キーをプレーンテキストで設定できます。<ENVIRONMENT> を、prod や staging などの Lambda 関数の環境で置き換えます。<SERVICE_NAME> を、Lambda 関数のサービス名に置き換えます。<DATADOG_SITE> を に置き換えます (このページで正しい Datadog サイトが選択されていることを確認してください)。<VERSION> を Lambda 関数のバージョン番号に置き換えます。
使用する Datadog Extension Lambda レイヤーと Datadog Node.js Lambda レイヤーのバージョンを選択します。デフォルトは、レイヤーの最新バージョンになります。
datadog_extension_layer_version = 103
datadog_node_layer_version = 144
SST v3 を使用して Datadog を構成するには、次のステップに従ってください。
const app = new sst.aws.Function("MyApp", {
handler: "index.handler",
nodejs : {
install: [
"datadog-lambda-js",
"dd-trace",
]
},
environment: {
DD_ENV: "<ENVIRONMENT>",
DD_SERVICE: "<SERVICE_NAME>",
DD_VERSION: "<VERSION>",
DATADOG_API_KEY_SECRET_ARN: "<DATADOG_API_KEY_SECRET_ARN>",
DD_SITE: "<DATADOG_SITE>",
},
layers: [
$interpolate`arn:aws:lambda:${aws.getRegionOutput().name}:464622532012:layer:Datadog-Extension:103`,
$interpolate`arn:aws:lambda:${aws.getRegionOutput().name}:464622532012:layer:Datadog-<RUNTIME>:144`,
],
});
Configure the Datadog Lambda Library and Datadog Lambda Extension layers
- The available
<RUNTIME> options are: Node18-x, Node20-x, Node22-x, Node24-x, Node26-xです。
dd-trace と datadog-lambda-js を nodejs.install リストに追加します。
環境変数のプレースホルダーを埋めます。
<DATADOG_API_KEY_SECRET_ARN> を、Datadog API キーが安全に保存されている AWS シークレットの ARN に置き換えます。キーはプレーンテキストの文字列として保存する必要があります (JSON ブロブではありません)。secretsmanager:GetSecretValue の権限が必要です。迅速なテストのために、代わりに環境変数 DD_API_KEY を使用し、Datadog API キーをプレーンテキストで設定できます。<ENVIRONMENT> を、prod や staging などの Lambda 関数の環境で置き換えます。<SERVICE_NAME> を、Lambda 関数のサービス名に置き換えます。<DATADOG_SITE> を に置き換えます (このページで正しい Datadog サイトが選択されていることを確認してください)。<VERSION>を Lambda 関数のバージョン番号に置き換えます。
関数コードで Datadog ラッパーを適用します。
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 関数に[レイヤーを構成][1]します。
# Use this format for AWS commercial regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-<RUNTIME>:144
# Use this format for AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-<RUNTIME>:144
Replace <AWS_REGION> with a valid AWS region such as us-east-1. The available <RUNTIME> options are: Node18-x, Node20-x, Node22-x, Node24-x, Node26-xです。
Option B: If you cannot use the prebuilt Datadog Lambda layer, alternatively you can install the packages datadog-lambda-js and dd-trace using your favorite package manager.
npm install datadog-lambda-js dd-trace
Datadog Lambda Extension をインストールする
次のフォーマットで、ARN を使用して Lambda 関数に[レイヤーを構成][1]します。
# Use this format for x86-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-Extension:103
# Use this format for arm64-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-Extension-ARM:103
# Use this format for x86-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-Extension:103
# Use this format for arm64-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-Extension-ARM:103
Replace `<AWS_REGION>` with a valid AWS region, such as `us-east-1`.
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 ラッパーを適用][2]する必要があります。また、Datadog ハンドラーのリダイレクトと互換性のないサードパーティのセキュリティツールや監視ツールを使用している場合、そのようなことが必要になる場合があります。
4. Datadog サイトと API キーを構成します。
- 環境変数 `DD_SITE` を <code class="js-region-param region-param" data-region-param="dd_site"></code> (右側で正しいサイトが選択されていることを確認してください)。
- [Datadog API キー][3]が安全に保存されている AWS シークレットの ARN を環境変数 `DD_API_KEY_SECRET_ARN` に設定します。キーはプレーンテキストの文字列として保存する必要があります (JSON ブロブではありません)。`secretsmanager:GetSecretValue` の権限が必要です。迅速なテストのために、代わりに `DD_API_KEY` を使用し、Datadog API キーをプレーンテキストで設定できます。
[1]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html
[2]: https://docs.datadoghq.com/ja/serverless/guide/handler_wrapper
[3]: https://app.datadoghq.com/organization-settings/api-keys
Do not set the following environment variables in your serverless environment. They should only be set in non-serverless environments.
DD_AGENT_HOSTDD_TRACE_AGENT_URL
Datadog Lambda ライブラリは、レイヤーとしても JavaScript パッケージとしてもインストールしないでください。Datadog Lambda ライブラリをレイヤーとしてインストールした場合は、 datadog-lambda-js を package.jsonに含めないでください。あるいは、開発依存としてインストールして npm install --production を実行してからデプロイしてください。
FIPS コンプライアンス
Datadog provides FIPS-compliant monitoring for AWS Lambda functions. For AWS GovCloud environments, the DD_LAMBDA_FIPS_MODE environment variable is enabled by default. When FIPS mode is enabled, AWS FIPS endpoints are used for Datadog API key lookups, and the Lambda metric helper function lambda_metric requires the FIPS-compliant extension for metric submission. While the FIPS-compliant Lambda components work with any Datadog site, end-to-end FIPS compliance requires using the US1-FED site. See AWS Lambda FIPS Compliance for more details.
AWS Lambda と VPC
If your Lambda functions are deployed in a Virtual Private Cloud (VPC) without access to the public internet, and you are using the datadoghq.com Datadog site, you can use AWS PrivateLink to send data.
If your Lambda functions are deployed in a VPC, and you are using a Datadog site that is not datadoghq.com, you can use a proxy to send data.
Durable Function
Datadog APM supports AWS Lambda Durable Functions. To maintain retention consistency for spans across a long-running durable execution, create a retention filter with the retention query operation_name:aws.durable.execute. Note that standard trace retention limits still apply.
By default, the tracer creates additional checkpoints named _datadog_{N} to propagate trace context across function invocations. This keeps spans from multiple invocations in a single intact trace for each durable execution. To disable this behavior and treat each invocation as an individual trace, set the environment variable DD_DURABLE_CROSS_INVOCATION_TRACING_ENABLED to false.
次のステップ
- 環境変数
DD_TAGS を使用して、テレメトリにカスタムタグを追加します。 - ペイロード収集を構成して、関数の JSON リクエストおよびレスポンスペイロードをキャプチャします。
- Datadog Lambda Extension を使用している場合、Datadog Forwarder の Lambda ログをオフにします。
- さらなる機能については、AWS Lambda 向けサーバーレスモニタリングの構成を参照してください。
カスタムビジネスロジックの監視
カスタムビジネスロジックを監視するには、次のサンプルコードを使用してカスタムメトリクスまたはスパンを送信します。追加のオプションについては、サーバーレスアプリケーション向けカスタムメトリクス送信および APM ガイドのカスタムインスツルメンテーションを参照してください。
const { sendDistributionMetric, sendDistributionMetricWithDate } = require('datadog-lambda-js');
const tracer = require('dd-trace');
// submit a custom span named "sleep"
const sleep = tracer.wrap('sleep', (ms) => {
return new Promise((resolve) => setTimeout(resolve, ms));
});
exports.handler = async (event) => {
// add custom tags to the lambda function span,
// does NOT work when X-Ray tracing is enabled
const span = tracer.scope().active();
span.setTag('customer_id', '123456');
await sleep(100);
// submit a custom span
const sandwich = tracer.trace('hello.world', () => {
console.log('Hello, World!');
});
// submit a custom metric
sendDistributionMetric(
'coffee_house.order_value', // metric name
12.45, // metric value
'product:latte', // tag
'order:online' // another tag
);
const response = {
statusCode: 200,
body: JSON.stringify('Hello from serverless!')
};
return response;
};
参考資料