Utiliza esta biblioteca de construcciones de Datadog CDK para desplegar aplicaciones serverless utilizando AWS CDK .

Esta biblioteca CDK configura automáticamente la ingesta de métricas, trazas (traces) y logs desde tus aplicaciones serverless mediante:

• Instalación y configuración de las capas Lambda de Datadog para tus funciones Lambda de .NET, Java, Node.js y Python.
• Activación de la recopilación de trazas y métricas personalizadas de tus funciones Lambda.
• Administración de suscripciones desde Datadog Forwarder a tus grupos de logs Lambda y no Lambda.

AWS CDK v1 frente a AWS CDK v2

ADVERTENCIA: AWS CDK v1 ha llegado al final de su soporte técnico y datadog-cdk-constructs ya no recibirá actualizaciones. Se recomienda encarecidamente actualizar a AWS CDK v2 (guía oficial de migración ) y cambiar para utilizar datadog-cdk-constructs-v2.

Existen dos versiones distintas de Datadog CDK Constructs; datadog-cdk-constructs y datadog-cdk-constructs-v2. Están diseñadas para funcionar con AWS CDK v1 y AWS CDK v2, respectivamente.

• datadog-cdk-constructs-v2 requiere Node >= 14, mientras que datadog-cdk-constructs admite Node >= 12.
• datadog-cdk-constructs-v2 contiene más funciones.
• Por lo demás, el uso de los dos paquetes es idéntico.

Instalación del paquete de npm:

Para uso con AWS CDK v2:

yarn añadir --dev datadog-cdk-constructs-v2
# o
npm instalar datadog-cdk-constructs-v2 --save-dev

Para uso con AWS CDK v1:

yarn añadir --dev datadog-cdk-constructs
# o
npm instalar datadog-cdk-constructs --save-dev

Instalación del paquete de PyPI:

Para uso con AWS CDK v2:

pip instalar datadog-cdk-constructs-v2

Para uso con AWS CDK v1:

pip instalar datadog-cdk-constructs

Nota:

Presta atención a la salida de su administrador de paquete, ya que Datadog CDK Construct Library tiene dependencias de mismo nivel.

Uso

AWS CDK

• _Si no conoces AWS CDK, consulta este taller.
• Los siguientes ejemplos suponen el uso de AWS CDK v2. Si utilizas CDK v1, importa datadog-cdk-constructs en lugar de datadog-cdk-constructs-v2.

Añade esto a tu stack de CDK:

importa { Datadog } desde "datadog-cdk-constructs-v2";

const datadog = nuevo 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>,
  sitio: "<SITE>",
  apiKey: "{Datadog_API_Key}",
  apiKeySecretArn: "{Secret_ARN_Datadog_API_Key}",
  apiKeySecret: <AWS_CDK_ISECRET>, // Está disponible solo en datadog-cdk-constructs-v2
  apiKmsKey: "{Encrypted_Datadog_API_Key}",
  enableDatadogTracing: <BOOLEAN>,
  enableMergeXrayTraces: <BOOLEAN>,
  enableDatadogLogs: <BOOLEAN>,
  injectLogContext: <BOOLEAN>,
  logLevel: <STRING>,
  variable de entorno: <STRING>, //Opcional
  servicio: <STRING>, //Opcional
  versión: <STRING>, //Opcional
  etiquetas (tags): <STRING>, //Opcional
});
datadog.addLambdaFunctions([<LAMBDA_FUNCTIONS>])
datadog.addForwarderToNonLambdaLogGroups([<LOG_GROUPS>])

Integración del código fuente

Integración del código fuente se activa por defecto mediante el etiquetado lambda automático y funcionará si:

• La integración de Datadog Github está instalada.
• Tu dependencia de datadog-cdk satisface cualquiera de las versiones siguientes:
  • datadog-cdk-constructs-v2 >= 1.4.0
  • datadog-cdk-constructs >= 0.8.5

Métodos alternativos para activar la integración del código fuente

Si la aplicación automática no funciona en tu caso, sigue una de las dos guías siguientes.

Nota: estas otras guías solo funcionan para Typescript.

const app = nueva cdk.App();

// Asegúrate de añadir @datadog/datadog-ci a través de tu administrador de paquete 
const datadogCi = require("@Datadog/Datadog-ci");
// Cargar manualmente los metadatos de Git a Datadog.
datadogCi.gitMetadata.uploadGitCommitHash('{Datadog_API_Key}', '<SITE>')

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

app.synth();

const app = nueva cdk.App();
// Pasa el hash al constructor ExampleStack
new ExampleStack(app, "ExampleStack", {}, gitHash);

Asegúrate de llamar a este función para inicializar tu stack.

En tu constructor de stack, cambia para añadir un parámetro opcional `gitHash` y llama a `addGitCommitMetadata()`:

``typescript
exporta clase ExampleStack extends cdk.Stack {
  constructor(contexto: cdk.App, id: string, props?: cdk.StackProps, gitHash?: string) {
    ...
    ...
   datadog.addGitCommitMetadata([<YOUR_FUNCTIONS>], gitHash)
  }
}

Configuración

Para configurar aún más tu construcción de Datadog, utiliza los siguientes parámetros personalizados:

Nota: En las descripciones, se utilizan los parámetros de paquetes de npm, pero también se aplican a los parámetros de paquetes de PyPI.

Nota: El uso de los parámetros anteriores puede sustituir las variables de entorno DD_XXX del nivel de función correspondiente.

Rastreo

Activa el rastreo X-Ray en tus funciones Lambda. Para más información, consulta la documentación de CDK.

importar * como lambda en "aws-cdk-lib/aws-lambda";

const lambda_function = nueva lambda.Function(this, "HelloHandler", {
  tiempo de ejecución: lambda.Runtime.NODEJS_14_X,
  código: lambda.Code.fromAsset("lambda"),
  controlador: "hello.handler",
  rastreo: lambda.Tracing.ACTIVE,
});

Stacks anidados

Añade la construcción de Datadog CDK a cada stack que desees instrumentar con Datadog. En el ejemplo siguiente, inicializamos la construcción de Datadog CDK y llamamos a addLambdaFunctions() tanto en RootStack como en NestedStack.

importar { Datadog } de "datadog-cdk-constructs-v2";
importar * como cdk de "aws-cdk-lib";
importar { Construcción } de "constructs";

clase RootStack extiende cdk.Stack {
  constructor(contexto: cdk.App, id: string, props?: cdk.StackProps) {
    super(contexto, id, props);
    nuevo NestedStack(this, "NestedStack");

    const datadog = nuevo Datadog(this, "Datadog", {
      nodeLayerVersion: <LAYER_VERSION>,
      pythonLayerVersion: <LAYER_VERSION>,
      javaLayerVersion: <LAYER_VERSION>,
      dotnetLayerVersion: <LAYER-VERSION>,
      addLayers: <BOOLEAN>,
      forwarderArn: "<FORWARDER_ARN>",
      flushMetricsToLogs: <BOOLEAN>,
      sitio: "<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>]);

  }
}

clase NestedStack extiende cdk.NestedStack {
  constructor(contexto: Construct, id: string, props?: cdk.NestedStackProps) {
    super(contexto, id, props);

    const datadog = nuevo Datadog(this, "Datadog", {
      nodeLayerVersion: <LAYER_VERSION>,
      pythonLayerVersion: <LAYER_VERSION>,
      javaLayerVersion: <LAYER_VERSION>,
      dotnetLayerVersion: <LAYER-VERSION>,
      addLayers: <BOOLEAN>,
      forwarderArn: "<FORWARDER_ARN>",
      flushMetricsToLogs: <BOOLEAN>,
      sitio: "<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>]);

  }
}

Etiquetas

Añade etiquetas a tus construcciones. Recomendamos configurar una etiqueta de env y service para unir la telemetría Datadog. Para más información consulta la documentación oficial de AWS y la documentación del CDK.

Concede automáticamente a AWS acceso de lectura a secretos al rol de ejecución de Lambda.

Sólo está disponible en datadog-cdk-constructs-v2

Para conceder automáticamente a los roles de ejecución de Lambda acceso de lectura a un secreto determinado, introduce apiKeySecret en lugar de apiKeySecretArn al inicializar la construcción de Datadog.

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

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

const datadog = nuevo Datadog(this, 'Datadog', {
  ...
  apiKeySecret: secreto
  ...
});

Cuando se llama a addLambdaFunctions, la construcción Datadog CDK concede a tus roles de ejecución Lambda acceso de lectura al secreto AWS dado. Esto se hace a través de la función grantRead de AWS ISecret.

Cómo funciona

La construcción de Datadog CDK toma una lista de funciones lambda e instala la biblioteca Datadog Lambda adjuntando las Lambda Layers para .NET, Java, Node.js y Python a tus funciones. Redirige a un controlador de sustitución que inicializa la biblioteca Lambda sin necesidad de ningún cambio de código. Las configuraciones adicionales añadidas a la construcción de Datadog CDK también se traducirán en sus respectivas variables de entorno en cada función lambda (si es aplicable/necesario).

Los grupos de logs basados en funciones Lambda están se controlan en forma automática mediante el método de addLambdaFunctions, mientras que la construcción tiene un función addForwarderToNonLambdaLogGroups adicional que suscribe el Forwarder a cualquier grupo de logs adicional de tu elección.

Recursos para aprender sobre CDK

• Taller de CDK TypeScript
• Vídeo de presentación del CDK por AWS con demostración
• Conceptos de CDK

Utilizar Projen

Las bibliotecas de Datadog CDK Construct utilizan Projen para mantener los archivos de configuración del proyecto, como package.json, .gitignore, .npmignore, etc. La mayoría de los archivos de configuración estarán protegidos por Projen mediante permisos de solo lectura. Para cambiar estos archivos, edita el archivo .projenrc.js, luego ejecuta npx projen para sintetizar los nuevos cambios. Haz un check en Projen para más detalles.

Problemas de apertura

Si encuentras un error en este paquete, queremos saberlo. Antes de abrir un nuevo problema, busca los problemas existentes para evitar duplicados.

Cuando abras un problema, incluye la versión de Datadog CDK Construct, la versión de Node y la traza del stack si está disponible. Además, incluye los pasos para la reproducción cuando corresponda.

También puedes abrir un problema para solicitar una función.

Colaboración

Si encuentras un problema en este paquete y tienes una solución, abre una solicitud de incorporación de cambios siguiendo los procedimientos.

Tests

Si contribuyes a este paquete puedes ejecutar los tests utilizando yarn test. Este paquete también incluye una aplicación de ejemplo para tests manuales:

1. Abre un terminal independiente.
2. Ejecuta yarn watch, esto asegurará que los archivos Typescript en el directorio src se recopilen a Javascript en el directorio lib.
3. Ve a src/sample, aquí puedes editar index.ts para hacer un test de tus contribuciones en forma manual.
4. En el directorio raíz, ejecuta npx cdk --app lib/sample/index.js <CDK Command>, sustituyendo <CDK Command> por comandos CDK frecuentes como synth, diff o deploy.

• Nota, si recibes “… no estás autorizado a realizar: …” puede que también necesites autorizar los comandos con tus credenciales de AWS.

Depurar logs

Para mostrar la depuración de logs para este biblioteca, configura la variable de entorno DD_CONSTRUCT_DEBUG_LOGS en true cuando ejecutes cdk synth (utiliza --quiet para suprimir la salida de plantilla generada).

Ejemplo: Asegúrate de estar en el directorio raíz

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

Comunidad

Si tienes preguntas o comentarios sobre el producto, únete al canal #serverless en la comunidad Datadog en Slack.

Licencia

A menos que se indique explícitamente lo contrario, todos los archivos de este repositorio tienen Licencia de Apache Versión 2.0.

Este producto incluye el software desarrollado en Datadog (https://www.datadoghq.com/). Copyright 2021 Datadog, Inc.