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

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

必須セットアップ

未構成の場合:

  • AWS インテグレーションをインストールします。これにより、Datadog は AWS から Lambda メトリクスを取り込むことができます。
  • AWS Lambda トレース、拡張メトリクス、カスタムメトリクス、ログの取り込みに必要な Datadog Forwarder Lambda 関数をインストールします。

AWS インテグレーションDatadog Forwarder をインストールしたら、手順に従ってアプリケーションをインスツルメントし、Datadog にメトリクス、ログ、トレースを送信します。

コンフィギュレーション

Datadog Serverless Plugin は、レイヤーを使用して Datadog Lambda ライブラリを関数に自動的に追加し、Datadog Forwarder を介してメトリクス、トレース、ログを Datadog に送信するように関数を構成します。

Lambda 関数が、コード署名を使用するよう構成してある場合、Datadog Serverless Plugin をインストールする前に Datadog の署名プロフィール ARN (arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc) を関数のコード署名コンフィギュレーションに追加する必要があります。

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

  1. Datadog サーバーレスプラグインをインストールします。
    yarn add --dev serverless-plugin-datadog
    
  2. serverless.yml に以下を追加します。
    plugins:
      - serverless-plugin-datadog
    
  3. serverless.yml に、以下のセクションも追加します。
    custom:
      datadog:
        forwarder: # The Datadog Forwarder ARN goes here.
    

    Datadog Forwarder ARN またはインストールの詳細については、こちらを参照してください。追加の設定については、プラグインのドキュメントを参照してください。

Datadog CloudFormation マクロは、SAM アプリケーションテンプレートを自動的に変換して、レイヤーを使用して Datadog Lambda ライブラリを関数に追加し、Datadog Forwarder を介してメトリクス、トレース、ログを Datadog に送信するように関数を構成します。

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

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

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

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

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

Transform:
  - AWS::Serverless-2016-10-31
  - Name: DatadogServerless
    Parameters:
      stackName: !Ref "AWS::StackName"
      nodeLayerVersion: "<LAYER_VERSION>"
      forwarderArn: "<FORWARDER_ARN>"
      service: "<SERVICE>" # オプション
      env: "<ENV>" # オプション

<SERVICE><ENV> を適切な値に置き換え、<LAYER_VERSION> を目的のバージョンの Datadog Lambda レイヤーに置き換え (最新リリースを参照)、<FORWARDER_ARN> を Forwarder ARN に置き換えます (Forwarder のドキュメントを参照)。

Lambda 関数が、コード署名を使用するよう構成してある場合、マクロを使用するには事前に Datadog の署名プロフィール ARN (arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc) を関数のコード署名コンフィギュレーションに追加する必要があります。

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

以下を行うことで、Datadog CDK コンストラクトでサーバーレスアプリケーションからのメトリクス、トレース、ログの収集を自動的に構成できます。

  • Python および Node.js Lambda 関数用に Datadog Lambda ライブラリをインストールし構成。
  • Lambda 関数からのトレースおよびカスタムメトリクスの収集を有効化。
  • Datadog Forwarder から Lambda 関数ロググループへのサブスクリプションを管理。

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

CDK プロジェクトで以下の Yarn または NPM コマンドを実行します。

#Yarn
yarn add --dev datadog-cdk-constructs

#NPM
npm install datadog-cdk-constructs --save-dev

Datadog CDK コンストラクトライブラリがダウンロードされ、使用の準備ができました。

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

AWS CDK アプリで datadog-cdk-construct モジュールをインポートして、以下のコンフィギュレーションを追加します(この例では TypeScript ですが、他の言語でも使用する場合も同様です)。

import * as cdk from "@aws-cdk/core";
import { Datadog } from "datadog-cdk-constructs";

class CdkStack extends cdk.Stack {
  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);
    const datadog = new Datadog(this, "Datadog", {
      nodeLayerVersion: <LAYER_VERSION>,
      pythonLayerVersion: <LAYER_VERSION>,
      addLayers: <BOOLEAN>,
      forwarderArn: "<FORWARDER_ARN>",
      flushMetricsToLogs: <BOOLEAN>,
      site: "<SITE>",
      apiKey: "{Datadog_API_Key}",
      apiKMSKey: "{Encrypted_Datadog_API_Key}",
      enableDDTracing: <BOOLEAN>,
      injectLogContext: <BOOLEAN>
    });
    datadog.addLambdaFunctions([<LAMBDA_FUNCTIONS>])
  }
}

<SERVICE> および <ENV> を適切な値に、<LAYER_VERSION> を Datadog Lambda レイヤーの希望バージョン(最新リリースを参照)に、<FORWARDER_ARN> を Forwarder ARN(Forwarder ドキュメントを参照)に置き換えます。

Lambda 関数が、コード署名を使用するよう構成してある場合、マクロを使用するには事前に Datadog の署名プロフィール ARN (arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc) を関数のコード署名コンフィギュレーションに追加する必要があります。

さらに詳しい情報や、追加パラメーターについては、Datadog CDK NPM ページをご覧ください。

このサービスは公開ベータ版です。フィードバックがございましたら、Datadog サポートチームまでお寄せください。

Datadog CLI を使用して、CI/CD パイプラインの Lambda 関数にインスツルメンテーションを設定します。CLI コマンドは、レイヤーを使用して Datadog Lambda ライブラリを関数に自動的に追加し、メトリクス、トレース、ログを Datadog に送信するように関数を構成します。

Datadog CLI のインストール

NPM または Yarn を使用して Datadog CLI をインストールします。

# NPM
npm install -g @datadog/datadog-ci

# Yarn
yarn global add @datadog/datadog-ci

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

AWS 認証情報を使用して次のコマンドを実行します。<functionname><another_functionname> を Lambda 関数名に置き換え、<aws_region> を AWS リージョン名に置き換え、<layer_version> を目的のバージョンの Datadog Lambda レイヤーに置き換え (最新リリースを参照)、<forwarder_arn> を Forwarder ARN に置き換えます (Forwarder のドキュメントを参照)。

datadog-ci lambda instrument -f <functionname> -f <another_functionname> -r <aws_region> -v <layer_version> --forwarder <forwarder_arn>

例:

datadog-ci lambda instrument -f my-function -f another-function -r us-east-1 -v 26 --forwarder arn:aws:lambda:us-east-1:000000000000:function:datadog-forwarder

Lambda 関数が、コード署名を使用するよう構成してある場合、Datadog CLI でインスツルメントするには事前に Datadog の署名プロフィール ARN (arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc) を関数のコード署名コンフィギュレーションに追加する必要があります。

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

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

Lambda 関数をコンテナイメージとしてデプロイする場合は、Datadog Lambda ライブラリをレイヤーとして使用できません。代わりに、Datadog Lambda ライブラリを直接イメージ内にインストールする必要があります。Datadog トレーシングを使用している場合は、dd-trace もインストールする必要があります。

NPM:

npm install --save datadog-lambda-js dd-trace

Yarn:

yarn add datadog-lambda-js dd-trace

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

関数の構成

  1. イメージの CMD 値を node_modules/datadog-lambda-js/dist/handler.handler に設定します。Dockerfile で直接設定するか、AWS を使用して値を上書きします。
  2. 元のハンドラーに、環境変数 DD_LAMBDA_HANDLER を設定します。例: myfunc.handler
  3. 環境変数 DD_TRACE_ENABLEDtrue に設定します。
  4. 環境変数 DD_FLUSH_TO_LOGtrue に設定します。
  5. オプションで、関数に service および env タグを適切な値とともに追加します。

Datadog Forwarder をロググループにサブスクライブ

メトリクス、トレース、ログを Datadog へ送信するには、関数の各ロググループに Datadog Forwarder Lambda 関数をサブスクライブする必要があります。

  1. まだの場合は、Datadog Forwarder をインストールします
  2. Datadog Forwarder を関数のロググループにサブスクライブします

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

Datadog Lambda ライブラリは、レイヤーまたは JavaScript パッケージとしてインポートすることができます。

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

レイヤーの使用

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

# 通常のリージョンの場合
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-<RUNTIME>:<VERSION>

# 米国政府リージョンの場合
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-<RUNTIME>:<VERSION>

使用できる RUNTIME オプションは、Node10-xNode12-x です。VERSION については、最新リリースを参照してください。例:

arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Node12-x:25

Lambda 関数が、コード署名を使用するよう構成してある場合、Datadog Lambda ライブラリをレイヤーとして追加するには事前に Datadog の署名プロフィール ARN (arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc) を関数のコード署名コンフィギュレーションに追加する必要があります。

パッケージの使用

NPM:

npm install --save datadog-lambda-js

Yarn:

yarn add datadog-lambda-js

最新リリースを参照。

関数の構成

  1. 関数のハンドラーを、レイヤーを使用する場合は /opt/nodejs/node_modules/datadog-lambda-js/handler.handler に、パッケージを使用する場合は node_modules/datadog-lambda-js/dist/handler.handler に設定します。
  2. 元のハンドラーに、環境変数 DD_LAMBDA_HANDLER を設定します。例: myfunc.handler
  3. 環境変数 DD_TRACE_ENABLEDtrue に設定します。
  4. 環境変数 DD_FLUSH_TO_LOGtrue に設定します。
  5. オプションで、関数に service および env タグを適切な値とともに追加します。

Datadog Forwarder をロググループにサブスクライブ

メトリクス、トレース、ログを Datadog へ送信するには、関数の各ロググループに Datadog Forwarder Lambda 関数をサブスクライブする必要があります。

  1. まだの場合は、Datadog Forwarder をインストールします
  2. Datadog Forwarder を関数のロググループにサブスクライブします

統合サービスタグ付け

これはオプションですが、Datadog は、統合サービスタグ付けのドキュメントに従って、サーバーレスアプリケーションに envserviceversion タグをタグ付けすることを強くお勧めします。

Datadog サーバーレスモニタリングの利用

以上の方法で関数を構成すると、Serverless Homepage でメトリクス、ログ、トレースを確認できるようになります。

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

カスタムメトリクスまたはスパンの送信をご希望の場合は、以下のコード例をご参照ください。

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 関数スパンにカスタムタグを追加します
  // 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", // タグ
  );

  // タイムスタンプ付きのカスタムメトリクスを送信します
  sendDistributionMetricWithDate(
    "coffee_house.order_value", // メトリクス名
    12.45, // メトリクス値
    new Date(Date.now()), // 日付、過去 20 分以内である必要があります
    "product:latte", // タグ
    "order:online", // タグ
  );

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

カスタムメトリクス送信の詳細については、ここを参照してください。カスタムインスツルメンテーションの詳細については、カスタムインスツルメンテーションの Datadog APM ドキュメントを参照してください。

その他の参考資料