この Datadog CDK コンスタクトライブラリを使用して、AWS CDK .NET Framework を使用してサーバーレスアプリケーションをデプロイします。

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

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

AWS CDK v1 と AWS CDK v2

警告: AWS CDK v1 はサポートが終了し、datadog-cdk-constructs はアップデートを受けられなくなりました。AWS CDK v2 (公式マイグレーションガイド)にアップグレードし、datadog-cdk-constructs-v2 の使用に切り替えることを強く推奨します。

Datadog CDK コンストラクトには、datadog-cdk-constructs と datadog-cdk-constructs-v2 という 2 つのバージョンが存在します。これらは、それぞれ AWS CDK v1 と AWS CDK v2 で動作するように設計されています。

• datadog-cdk-constructs-v2 には Node >= 14 が必要で、datadog-cdk-constructs は Node >= 12 をサポートしています。
• datadog-cdk-constructs-v2 はより多くの機能を含んでいます。
• それ以外は、2 つのパッケージの使用方法は同じです。

npm パッケージのインストール:

AWS CDK v2 で使用する場合:

yarn add --dev datadog-cdk-constructs-v2
# または
npm install datadog-cdk-constructs-v2 --save-dev

AWS CDK v1 で使用する場合:

yarn add --dev datadog-cdk-constructs
# または
npm install datadog-cdk-constructs --save-dev

PyPI パッケージのインストール:

AWS CDK v2 で使用する場合:

pip install datadog-cdk-constructs-v2

AWS CDK v1 で使用する場合:

pip install datadog-cdk-constructs

注:

Datadog CDK Construct Library はピアの依存関係があるので、パッケージマネージャーからの出力に注意してください。

API

AWS CDK

• AWS CDK を初めて使うのであれば、こちらのワークショップをご覧ください。
• 以下の例では、AWS CDK v2 を使用することを想定しています。CDK v1 を使用している場合は、datadog-cdk-constructs-v2 ではなく、datadog-cdk-constructs をインポートします。

これを CDK スタックに追加します。

import { Datadog } from "datadog-cdk-constructs-v2";

const datadog = new Datadog(this, "Datadog", {
  nodeLayerVersion: <LAYER_VERSION>,
  pythonLayerVersion: <LAYER_VERSION>,
  javaLayerVersion: <LAYER_VERSION>,
  dotnetLayerVersion: <LAYER_VERSION>
  addLayers: <BOOLEAN>,
  extensionLayerVersion: "<EXTENSION_VERSION>",
  forwarderArn: "<FORWARDER_ARN>",
  createForwarderPermissions: <BOOLEAN>,
  flushMetricsToLogs: <BOOLEAN>,
  site: "<SITE>",
  apiKey: "{Datadog_API_Key}",
  apiKeySecretArn: "{Secret_ARN_Datadog_API_Key}",
  apiKeySecret: <AWS_CDK_ISECRET>, // datadog-cdk-constructs-v2 でのみ使用可能
  apiKmsKey: "{Encrypted_Datadog_API_Key}",
  enableDatadogTracing: <BOOLEAN>,
  enableMergeXrayTraces: <BOOLEAN>,
  enableDatadogLogs: <BOOLEAN>,
  injectLogContext: <BOOLEAN>,
  logLevel: <STRING>,
  env: <STRING>, //オプション
  service: <STRING>, //オプション
  version: <STRING>, //オプション
  tags: <STRING>, //オプション
});
datadog.addLambdaFunctions([<LAMBDA_FUNCTIONS>])
datadog.addForwarderToNonLambdaLogGroups([<LOG_GROUPS>])

ソースコードインテグレーション

ソースコードインテグレーションは、Lambda の自動タグ付けによりデフォルトで有効であり、以下の場合に動作します。

• Datadog Github Integration がインストールされている。
• Datadog-cdk の依存関係が以下のバージョンのいずれかを満たしている。
  • datadog-cdk-constructs-v2 >= 1.4.0
  • datadog-cdk-constructs >= 0.8.5

ソースコードインテグレーションを可能にする代替方法

自動導入がうまくいかない場合は、以下の 2 つのガイドのいずれかに従ってください。

注: これらの代替ガイドは Typescript にのみ有効です。

const app = new cdk.App();

// パッケージマネージャーで @datadog/datadog-ci を追加することを確認してください
const datadogCi = require("@datadog/datadog-ci");
// Git のメタデータを Datadog に手動でアップロードします。
datadogCi.gitMetadata.uploadGitCommitHash('{Datadog_API_Key}', '<SITE>')

const app = new cdk.App();
new ExampleStack(app, "ExampleStack", {});

app.synth();

async function main() {
  // パッケージマネージャーで @datadog/datadog-ci を追加することを確認してください
  const datadogCi = require("@datadog/datadog-ci");
  const [, gitHash] = await datadogCi.gitMetadata.uploadGitCommitHash('{Datadog_API_Key}', '<SITE>')

  const app = new cdk.App();
  // ExampleStack のコンストラクタにハッシュを渡します
  new ExampleStack(app, "ExampleStack", {}, gitHash);
}

export class ExampleStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps, gitHash?: string) {
    ...
    ...
    datadog.addGitCommitMetadata([<YOUR_FUNCTIONS>], gitHash)
  }
}

ブラウザトラブルシューティング

Datadog のコンストラクトをさらに構成するには、以下のカスタムパラメーターを使用します。

注: 説明では npm パッケージパラメーターを使用していますが、PyPI パッケージパラメーターにも適用されます。

注: 上記のパラメーターを使用すると、対応する関数レベルの DD_XXX 環境変数がオーバーライドされる場合があります。

ヘルプ

Lambda 関数で X-Ray トレーシングを有効にします。詳しくは、CDK ドキュメントを参照してください。

import * as lambda from "aws-cdk-lib/aws-lambda";

const lambda_function = new lambda.Function(this, "HelloHandler", {
  runtime: lambda.Runtime.NODEJS_14_X,
  code: lambda.Code.fromAsset("lambda"),
  handler: "hello.handler",
  tracing: lambda.Tracing.ACTIVE,
});

ネストされたスタック

Datadog CDK コンストラクトを、Datadog でインスツルメントしたい各スタックに追加します。以下の例では、Datadog CDK コンストラクトを初期化し、RootStack と NestedStack の両方で addLambdaFunctions() を呼び出しています。

import { Datadog } from "datadog-cdk-constructs-v2";
import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

class RootStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);
    new NestedStack(this, "NestedStack");

    const datadog = new Datadog(this, "Datadog", {
      nodeLayerVersion: <LAYER_VERSION>,
      pythonLayerVersion: <LAYER_VERSION>,
      javaLayerVersion: <LAYER_VERSION>,
      dotnetLayerVersion: <LAYER-VERSION>,
      addLayers: <BOOLEAN>,
      forwarderArn: "<FORWARDER_ARN>",
      flushMetricsToLogs: <BOOLEAN>,
      site: "<SITE>",
      apiKey: "{Datadog_API_Key}",
      apiKeySecretArn: "{Secret_ARN_Datadog_API_Key}",
      apiKmsKey: "{Encrypted_Datadog_API_Key}",
      enableDatadogTracing: <BOOLEAN>,
      enableMergeXrayTraces: <BOOLEAN>,
      enableDatadogLogs: <BOOLEAN>,
      injectLogContext: <BOOLEAN>
    });
    datadog.addLambdaFunctions([<LAMBDA_FUNCTIONS>]);

  }
}

class NestedStack extends cdk.NestedStack {
  constructor(scope: Construct, id: string, props?: cdk.NestedStackProps) {
    super(scope, id, props);

    const datadog = new Datadog(this, "Datadog", {
      nodeLayerVersion: <LAYER_VERSION>,
      pythonLayerVersion: <LAYER_VERSION>,
      javaLayerVersion: <LAYER_VERSION>,
      dotnetLayerVersion: <LAYER-VERSION>,
      addLayers: <BOOLEAN>,
      forwarderArn: "<FORWARDER_ARN>",
      flushMetricsToLogs: <BOOLEAN>,
      site: "<SITE>",
      apiKey: "{Datadog_API_Key}",
      apiKeySecretArn: "{Secret_ARN_Datadog_API_Key}",
      apiKmsKey: "{Encrypted_Datadog_API_Key}",
      enableDatadogTracing: <BOOLEAN>,
      enableMergeXrayTraces: <BOOLEAN>,
      enableDatadogLogs: <BOOLEAN>,
      injectLogContext: <BOOLEAN>
    });
    datadog.addLambdaFunctions([<LAMBDA_FUNCTIONS>]);

  }
}

Lambda のトレースされた起動の 1 時間単位使用量の取得

コンストラクトにタグを追加します。Datadog のテレメトリーを紐付けるために、env タグと service タグを設定することをお勧めします。詳しくは AWS 公式ドキュメントや CDK ドキュメントを参照してください。

Lambda 実行ロールに AWS シークレット読み取りアクセスを自動で付与する

datadog-cdk-constructs-v2 でのみ使用可能

Lambda 実行ロールに指定したシークレットへの読み取りアクセスを自動的に付与するには、Datadog のコンストラクトを初期化する際に、apiKeySecretArn の代わりに apiKeySecret を渡します。

const { Secret } = require('aws-cdk-lib/aws-secretsmanager');

const secret = Secret.fromSecretPartialArn(this, 'DatadogApiKeySecret', 'arn:aws:secretsmanager:us-west-1:123:secret:DATADOG_API_KEY');

const datadog = new Datadog(this, 'Datadog', {
  ...
  apiKeySecret: secret
  ...
});

addLambdaFunctions が呼び出されると、Datadog CDK コンストラストは、Lambda 実行ロールに与えられた AWS シークレットへの読み取りアクセスを付与します。これは AWS ISecret の grantRead 関数を通して行われます。

UDS の仕組み

Datadog CDK コンストラクトは、Lambda 関数のリストを取り込み、関数に .NET、Java、Node.js、および Python の Lambda Layers をアタッチして、Datadog Lambda Library をインストールするものです。これは、必要なコードの変更なしに Lambda Library を初期化する代替ハンドラーにリダイレクトします。Datadog CDK コンストラクトに追加された構成も、各 Lambda 関数の下でそれぞれの環境変数に変換されます (該当する場合/必要な場合)。

Lambda 関数ベースのロググループは addLambdaFunctions メソッドで自動的に処理されますが、このコンストラクトには追加の関数 addForwarderToNonLambdaLogGroups があり、Forwarder に追加のロググループをサブスクライブさせます。

CDK について学ぶためのリソース

• CDK TypeScript ワークショップ
• CDK by AWS の紹介ビデオ (デモ付き)
• CDK コンセプト

リポジトリの構造

このリポジトリでは、v1 と v2 というフォルダが、パッケージ datadog-cdk-constructs と datadog-cdk-contructs-v2 に対応しています。それぞれは独立したプロジェクトとして扱うことができます (依存関係、コンフィギュレーションファイル、テスト、スクリプトを持つ別々の projen プロジェクトです)。

さらに、v1 と v2 の両パッケージに共通する共有ロジックを格納した common フォルダも用意されています。これは、v1/src と v2/src 内の common フォルダを、リポジトリのルートにある common フォルダにソフトリンクすることによって行われます。

Projen の使用

Datadog CDK コンストラクトライブラリの v1 と v2 は共に、package.json、.gitignore、.npmignore などのプロジェクトコンフィギュレーションファイルを管理するために Projen を使用しています。ほとんどのコンフィギュレーションファイルは、Projen によって読み取り専用権限で保護されています。これらのファイルを変更するには、 v1 または v2 フォルダ内の .projenrc.js ファイルを編集して、npx projen (v1 または v2 内) を実行して新しい変更を反映させます。詳しくは、Projen をチェックしてください。

問題を開く

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

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

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

寄稿

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

テスト

このパッケージに貢献した場合、v1 または v2 フォルダ内の yarn test を使ってテストを実行することができます。このパッケージには、手動テスト用のサンプルアプリケーションも含まれています。

1. 別のターミナルを開き、v1 または v2 に cd します。
2. yarn watch を実行すると、src ディレクトリにある Typescript ファイルが、lib ディレクトリにある Javascript にコンパイルされることを確認できます。
3. src/sample に移動し、ここで index.ts を編集して、手動で貢献をテストすることができます。
4. v1 または v2 ディレクトリのルートで、npx cdk --app lib/sample/index.js <CDK Command> を実行します。<CDK Command> は synth、diff、deploy などの一般的な CDK コマンドに置き換えてください。

• なお、"… is not authorized to perform: …” (…は実行する権限がありません: …) と表示された場合は、AWS の認証情報でコマンドを認証する必要がある場合もあります。

デバッグログ

このライブラリのデバッグログを表示するには、cdk synth を実行するときに DD_CONSTRUCT_DEBUG_LOGS 環境変数を true に設定します (生成されたテンプレートの出力を抑制するには --quiet を使用します)。

例: v1 または v2 ディレクトリのルートにいることを確認します

DD_CONSTRUCT_DEBUG_LOGS=true npx cdk --app lib/sample/index.js synth --quiet

ヘルプ

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

ライセンス

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

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