NPM NPM PyPI PyPI License

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-constructsdatadog-cdk-constructs-v2가 있습니다. 이들은 각각 AWS CDK v1AWS 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에서만 사용할 수 있습니다.

datadog-cdk version satisfied, but Datadog Github Integration NOT installed

If the Datadog Github Integration is not installed, you need to import the datadog-ci package and manually upload your Git metadata to Datadog. We recommend you do this where your CDK Stack is initialized.

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();
datadog-cdk version NOT satisfied

Change your initialization function as follows (note: we’re changing this to pass just the gitHash value to the CDK):

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);
}

Ensure you call this function to initialize your stack.

In your stack constructor, change to add an optional gitHash parameter, and call addGitCommitMetadata():

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 패키지 파라미터에도 적용됩니다.

npm 패키지 파라미터PyPI 패키지 파라미터설명
addLayersadd_layersLambda 레이어를 추가할지 또는 사용자가 자신의 레이어를 가져올 것으로 예상할지 여부입니다. 기본값은 true입니다. true인 경우 람다 라이브러리 버전 변수도 필요합니다. false인 경우 함수의 배포 패키지에 Datadog 람다 라이브러리를 포함해야 합니다.
pythonLayerVersionpython_layer_version설치할 Python Lambda 레이어의 버전(예: 21)입니다. Python으로 작성된 Lambda 함수를 하나 이상 배포하는 경우 에 필요하며 addLayers는 true입니다. 최신 버전 번호는 여기에서 찾을 수 있습니다.
nodeLayerVersionnode_layer_version설치할 Node.js Lambda 레이어의 버전(예: 29)입니다. Node.js로 작성된 Lambda 함수를 하나 이상 배포하는 경우 에 필요하며 addLayers는 true입니다. 최신 버전 번호는 여기에서 찾을 수 있습니다.
javaLayerVersionjava_layer_version설치할 Java 레이어의 버전(예: 8)입니다. Java로 작성된 Lambda 함수를 하나 이상 배포하는 경우에 필요하며 addLayers는 true여야 합니다. 최신 버전 번호는 서버리스 Java 설치 설명서에서 확인할 수 있습니다. 참고: Datadog 컨스트럭트가 Java 함수를 올바르게 계측하려면 extensionLayerVersion >= 25javaLayerVersion >= 5가 필요합니다.
extensionLayerVersionextension_layer_version설치할 Datadog Lambda 확장 레이어의 버전(예: 5)입니다. extensionLayerVersion가 설정된 경우 apiKey(암호화된 경우에는 apiKMSKey 또는 apiKeySecretArn)도 설정해야 합니다. 활성화되면 람다 함수 로그 그룹이 포워더(Forwarder)에 등록되지 않습니다. 람다 확장에 대한 자세한 내용은 여기에서 확인하세요.
forwarderArnforwarder_arn설정되면 플러그인이 자동으로 Datadog 포워더(Forwarder)를 함수의 로그 그룹에 등록합니다. extensionLayerVersion가 설정되어 있으면 forwarderArn는 설정하지 마세요.
createForwarderPermissionscreateForwarderPermissionstrue로 설정하면 로그 그룹별로 Datadog 포워더(Forwarder)에 대한 람다 권한을 생성합니다. Datadog 포워더(Forwarder)에는 기본적으로 설정된 권한이 있기 때문에 대부분의 사용 용도에서는 이 권한이 필요하지 않습니다.
flushMetricsToLogsflush_metrics_to_logsDatadog 포워더 람다 함수와 함께 CloudWatch 로그를 사용하여 커스텀 메트릭을 전송합니다 (권장 사항). 기본값은 true입니다. 이 파라미터를 사용하지 않으면 apiKey를 (암호화된 경우에는 apiKMSKey 또는 apiKeySecretArn) 설정해야 합니다.
sitesite데이터를 보낼 Datadog 사이트를 설정합니다. 이 옵션은flushMetricsToLogsfalse일 때 또는 extensionLayerVersion이 설정된 경우에만 사용됩니다. 가능한 값은datadoghq.com, datadoghq.eu,us3.datadoghq.com, us5.datadoghq.com,ap1.datadoghq.comddog-gov.com 입니다. 기본값은 datadoghq.com입니다.
apiKeyapi_keyDatadog API Key는 flushMetricsToLogsfalse일 경우 또는 extensionLayerVersion이 설정된 경우에만 필요합니다. Datadog API 키를 가져오는 방법에 대한 자세한 내용은 API 키 설명서를 참조하세요.
apiKeySecretArnapi_key_secret_arnAWS 비밀 관리자에서 Datadog API 키를 저장하는 암호의 ARN입니다. flushMetricsToLogsfalse일 경우 또는 extensionLayer가 설정된 경우 apiKey 대신 이 파라미터를 사용합니다. 람다 실행 역할에 secretsmanager:GetSecretValue 권한을 추가해야 합니다.
apiKeySecretapi_key_secretDatadog API 키를 AWS 비밀 관리자에 저장하는 암호를 나타내는 AWS CDK ISecret입니다. 람다 실행 역할에 지정된 암호에 대한 읽기 권한을 자동으로 부여하려면 apiKeySecretArn 대신 이 파라미터를 사용합니다. 관련 예시는 여기에서 확인하세요. datadog-cdk-constructs-v2에서만 사용할 수 있습니다.
apiKmsKeyapi_kms_keyKMS를 사용하여 암호화된 Datadog API 키입니다. flushMetricsToLogsfalse일 경우 또는 extensionLayerVersion가 설정된 경우 그리고 KMS 암호화를 사용하고 있는 경우 apiKey 대신 이 파라미터를 사용합니다.
enableDatadogTracingenable_datadog_tracing람다 함수에서 Datadog 추적을 활성화합니다. 기본값은 true입니다.
enableMergeXrayTracesenable_merge_xray_traces람다 함수에서 X-Ray 트레이스 병합을 활성화합니다. 기본값은 false입니다.
enableDatadogLogsenable_datadog_logsDatadog 람다 확장을 통해 람다 함수 로그를 Datadog으로 전송합니다. 기본값은 true입니다. 참고: 이 설정은 Datadog 포워더(Forwarder)를 통해 전송된 로그에는 적용되지 않습니다.
enableSourceCodeIntegrationenable_source_code_integration텔레메트리와 Git 저장소의 애플리케이션 코드를 연결하여 Datadog 소스 코드 통합을 활성화합니다. 이를 위해서는 Datadog Github 통합이 작동해야 합니다. 그렇지 않으면 대체 방법을 따르세요. 자세한 내용은 여기를 참조하세요. 기본값은 true입니다.
injectLogContextinject_log_context설정하면 람다 레이어가 자동으로 Datadog의 추적 ID와 함께 console.log를 패치합니다. 기본값은 true입니다.
logLevellog_leveldebug로 설정하면 Datadog 람다 라이브러리와 확장이 문제 해결에 도움이 되는 추가 정보를 기록합니다.
envenvextensionLayerVersion와 함께 설정하면 모든 람다 함수에 제공된 값으로 DD_ENV 환경 변수가 추가됩니다.forwarderArn와 함께 설정하면 모든 람다 함수에 제공된 값으로 env 태그가 추가됩니다.
serviceserviceextensionLayerVersion과 함께 설정하면 DD_SERVICE 환경 변수가 제공된 값으로 모든 람다 함수에 추가됩니다. forwarderArn와 함께 설정하면 제공된 값으로 모든 람다 함수에 service 태그가 추가됩니다.
versionversionextensionLayerVersion과 함께 설정하면 DD_VERSION 환경 변수가 제공된 값으로 모든 람다 함수에 추가됩니다. forwarderArn와 함께 설정하면 제공된 값으로 모든 람다 함수에 version 태그가 추가됩니다.
tagstags키:값 쌍을 단일 문자열로써 쉼표로 구분한 목록입니다. extensionLayerVersion와 함께 설정하면 DD_TAGS 환경 변수가 제공된 값으로 모든 람다 함수에 추가됩니다. forwarderArn와 함께 설정하면 cdk는 문자열을 구문 분석하고 각 키:값 쌍을 모든 람다 함수에 태그로 설정합니다.
enableColdStartTracingenable_cold_start_tracing콜드 스타트 추적을 비활성화하려면 false로 설정합니다. NodeJS 및 파이썬(Python)에서 사용됩니다. 기본값은 true입니다.
coldStartTraceMinDurationmin_cold_start_trace_duration콜드 스타트 추적을 통해 추적할 모듈 로드 이벤트의 최소 지속 시간 (밀리초)을 설정합니다. 번호. 기본값은3 입니다.
coldStartTraceSkipLibscold_start_trace_skip_libs(선택 사항) 쉼표로 구분된 라이브러리 목록에 대한 콜드 스타트 스팬 생성을 건너뛸 수 있습니다. 깊이를 제한하거나 알려진 라이브러리를 건너뛸 때 유용합니다. 기본값은 런타임에 따라 다릅니다.
enableProfilingenable_profilingtrue로 설정해 Datadog Continuous Profiler를 활성화합니다. NodeJS 및 파이썬(Python)용은 베타 버전에서 지원됩니다. 기본값은 false입니다.
encodeAuthorizerContextencode_authorizer_context람다 인증자에 대해 true로 설정하면 추적 컨텍스트가 전파를 위해 응답으로 인코딩됩니다. NodeJS 및 파이썬(Python)에서 지원됩니다. 기본값은 true입니다.
decodeAuthorizerContextdecode_authorizer_context람다 인증자를 통해 인증된 람다에 대해 true로 설정하면 인코딩된 추적 컨텍스트를 구문 분석하여 사용합니다 (있는 경우). NodeJS 및 파이썬(Python)에서 지원됩니다. 기본값은 true입니다.
apmFlushDeadline시간 초과가 발생하기 전에 스팬을 제출할 시점을 밀리초 단위로 결정하는 데 사용됩니다. AWS 람다 호출의 남은 시간이 설정된 값보다 작으면 추적기는 현재 활성 스팬과 완료된 모든 스팬을 제출하려고 시도합니다. NodeJS 및 파이썬(Python)에서 지원됩니다. 기본값은 100밀리초입니다.
redirectHandlerredirect_handlerfalse로 설정하면 Datadog 람다 라이브러리의 핸들러로 리디렉션 핸들러를 건너뜁니다. Datadog 람다 확장으로만 계측할 때 유용합니다. 기본값은 true입니다.

참고: 위의 파라미터를 사용하면 해당 함수 수준 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를 초기화하고 RootStackNestedStack 모두에서 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>]);

  }
}

태그

컨스트럭트에 태그를 추가합니다. envservice 태그를 설정하여 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에 대해 알아볼 수 있는 리소스

저장소 구조

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

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

Projen 사용하기

v1v2 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. 별도의 터미널을 열고 cdv1 또는 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.