Datadog CDK Construct

AWS CDK를 사용하여 서버리스 애플리케이션을 배포할 수 있도록 Datadog CDK Construct 라이브러리를 사용합니다.

CDK 라이브러리는 다음과 같은 방법으로 서버리스 애플리케이션에서 메트릭, 트레이스 및 로그 수집을 자동으로 설정합니다:

• 파이썬(Python), Node.js 및 자바(Java)의 람다 함수를 위한 Datadog 람다 레이어를 설치 및 설정합니다.
• 람다 기능/함수에서 트레이스 및 커스텀 메트릭 수집을 활성화합니다.
• Datadog 포워더(Forwarder)에서 람다 및 비 람다 로그 그룹에 대한 구독을 관리합니다.

AWS CDK v1 vs AWS CDK v2

Datadog CDK Constructs에는 두 개의 개별 버전인 datadog-cdk-constructs와 datadog-cdk-constructs-v2가 있습니다. 이들은 각각 AWS CDK v1및 AWS CDK v2와 함께 작동하도록 설계되었습니다.

• datadog-cdk-constructs-v2는 Node >= 14가 필요하며, datadog-cdk-constructs는 Node >= 12를 지원합니다.
• datadog-cdk-constructs-v2는 더 많은 기능을 포함합니다.
• 그렇지 않으면 두 패키지의 사용법은 동일합니다.

npm 패키지 설치:

AWS CDK v2와 함께 사용하는 경우:

yarn add --dev datadog-cdk-constructs-v2
# or
npm install datadog-cdk-constructs-v2 --save-dev

AWS CDK v1과 함께 사용하는 경우:

yarn add --dev datadog-cdk-constructs
# or
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에는 피어 종속성이 있으므로 패키지 관리자의 출력에 주의하세요.

사용법

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>,
  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>, // Only available in datadog-cdk-constructs-v2
  apiKmsKey: "{Encrypted_Datadog_API_Key}",
  enableDatadogTracing: <BOOLEAN>,
  enableMergeXrayTraces: <BOOLEAN>,
  enableDatadogLogs: <BOOLEAN>,
  injectLogContext: <BOOLEAN>,
  logLevel: <STRING>,
  env: <STRING>, //Optional
  service: <STRING>, //Optional
  version: <STRING>, //Optional
  tags: <STRING>, //Optional
});
datadog.addLambdaFunctions([<LAMBDA_FUNCTIONS>])
datadog.addForwarderToNonLambdaLogGroups([<LOG_GROUPS>])

소스 코드 통합

소스 코드 통합 은 자동 람다 태깅을 통해 기본적으로 활성화되며 다음과 같은 경우에 작동합니다:

• Datadog Github 통합이 설치되었습니다.
• datadog-cdk 종속성은 다음 버전 중 하나를 충족합니다:
  • datadog-cdk-constructs-v2 >= 1.4.0
  • datadog-cdk-constructs >= 0.8.5

소스 코드 통합을 활성화하는 다른 방법

자동 구현이 적용되지 않는 경우, 다음 두 가지 가이드 중 하나를 따르세요.

참고: 이 대체 가이드는 Typescript에서만 사용할 수 있습니다.

const app = new cdk.App();

// Make sure to add @datadog/datadog-ci via your package manager
const datadogCi = require("@datadog/datadog-ci");
// Manually uploading Git metadata to Datadog.
datadogCi.gitMetadata.uploadGitCommitHash('{Datadog_API_Key}', '<SITE>')

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

app.synth();

async function main() {
  // Make sure to add @datadog/datadog-ci via your package manager
  const datadogCi = require("@datadog/datadog-ci");
  const [, gitHash] = await datadogCi.gitMetadata.uploadGitCommitHash('{Datadog_API_Key}', '<SITE>')

  const app = new cdk.App();
  // Pass in the hash to the ExampleStack constructor
  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 환경 변수를 재정의할 수 있습니다.

추적하기

람다 함수에서 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을 사용하여 계측하려는 각 스택에 Datadog CDK Construct를 추가합니다. 아래 예제에서는 Datadog CDK Construct를 초기화하고 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>,
      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>,
      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>]);

  }
}

태그

컨스트럭트에 태그를 추가합니다. env 및 service 태그를 설정하여 Datadog 텔레메트리를 함께 연결하는 것이 좋습니다. 자세한 내용은 공식 AWS 설명서 및 CDK 설명서를 참조하세요.

람다 실행 역할에 대한 AWS 비밀 읽기 권한 자동 부여

datadog-cdk-constructs-v2에서만 사용 가능

람다 실행 역할에 지정된 암호에 대한 읽기 권한을 자동으로 부여하려면 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 컨스트럭트가 람다 실행 역할에 지정된 AWS 암호에 대한 읽기 액세스 권한을 부여합니다. 이 작업은 AWS ISecret’s grantRead 함수를 통해 수행됩니다.

작동 방식

Datadog CDK 컨스트럭트는 람다 함수 목록을 가져와서 자바(Java), Node.js 및 파이썬(Python)용 람다 레이어를 함수에 연결하여 Datadog 람다 라이브러리를 설치합니다. 필요한 코드 변경 없이 람다 라이브러리를 초기화하는 교체 핸들러로 리디렉션됩니다. Datadog CDK construct에 추가된 추가 컨스트럭트는 각 람다 함수 아래의 해당 환경 변수로 변환됩니다(해당되는 경우/필요한 경우).

람다 함수 기반 로그 그룹은 addLambdaFunctions 메소드에 의해 자동으로 처리되지만 컨스트럭트에는 선택한 추가 로그 그룹에 포워더(Forwarder)를 등록하는 추가 함수addForwarderToNonLambdaLogGroups이 있습니다.

CDK에 대해 알아볼 수 있는 리소스

• CDK 타입스크립트 워크샵
• 데모와 함께 AWS의 CDK를 소개하는 비디오
• CDK 컨셉

저장소 구조

이 저장소에서 폴더 v1 . v2는 패키지datadog-cdk-constructs와 datadog-cdk-contructs-v2에 해당합니다 . 각각은 별도의 프로젝트로 취급될 수 있습니다 (이들은 별도의 종속성, 설정 파일, 테스트 및 스크립트를 가진 별도의 Projen 프로젝트입니다).

또한 v1 및 v2 패키지 모두에 공통적으로 적용되는 공유 로직이 포함된 common 폴더가 있습니다. 이 작업은 v1/src와 v2/src 내 common 폴더와 저장소 루트에 있는 common 폴더를 소프트 링크하면 됩니다.

Projen 사용하기

v1및 v2 Datadog CDK Construct 라이브러리는 모두 Projen을 사용하여 package.json, .gitignore, .npmignore 등의 프로젝트 설정 파일을 유지 관리합니다. 대부분의 설정 파일은 읽기 전용 권한을 통해 Projen에 의해 보호됩니다. 이러한 파일을 변경하려면 v1 또는 v2 폴더 내에서 .projenrc.js 파일을 편집한 다음 npx projen(v1 또는 v2를 실행한 상태에서)을 실행하여 새 변경 사항을 통합합니다. 자세한 내용은 Projen에서 확인하세요.

오프닝 이슈

이 패키지와 관련된 버그가 발견되면 알려주시기 바랍니다. 새 이슈를 열기 전에 기존 이슈를 검색하여 중복을 피하세요.

이슈를 열 때, 가능하면 Datadog CDK Construct 버전, Node 버전 및 스택 트레이스(stack trace)를 포함하세요. 또한 가능한 경우 재현 단계를 포함하세요.

기능 요청에 대한 이슈를 열 수도 있습니다.

기여하기

이 패키지와 관련된 문제를 발견하고 수정 사항이 있으면 절차에 따라 풀 리퀘스트를 개설해 주세요.

테스트

이 패키지에 기여하면 v1 또는 v2 폴더 내에서 yarn test를 사용하여 테스트를 실행할 수 있습니다. 이 패키지에는 수동 테스트를 위한 샘플 애플리케이션도 포함되어 있습니다:

1. 별도의 터미널을 열고 cd를 v1 또는 v2에 엽니다.
2. yarn watch를 실행하면 src 디렉토리의 타입스크립트 파일이 lib 디렉토리의 자바스크립트로 컴파일됩니다.
3. src/sample으로 이동한 후 index.ts를 편집하여 기여도를 수동으로 테스트할 수 있습니다.
4. v1 또는 v2 디렉토리 (어느 것이든 작업 중인 디렉토리)의 루트에서 synth, diff, deploy와 같은 일반적인 CDK 명령으로 <CDK Command>을 대체하고 npx cdk --app lib/sample/index.js <CDK Command>를 실행합니다.

• “… 를 수행할 권한이 없습니다: …” 라는 메시지가 표시되면 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

커뮤니티

제품 피드백 및 질문이 있는 경우 슬랙의 Datadog 커뮤니티의 #serverless 채널에 가입하세요.

라이센스

명시적으로 규정되지 않은 한 이 저장소의 모든 파일은 Apache License Version 2.0에 따라 라이센스가 부여됩니다.

이 제품에는 Datadog (https://www.datadoghq.com/)에서 개발한 소프트웨어가 포함되어 있습니다. Copyright 2021 Datadog, Inc.