Construcción de Datadog CDK

NPM NPM PyPI PyPI Licencia

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.

Datadog-cdk versión satisfecha, pero integración de Datadog Github NO instalada

Si la integración de Datadog Github no está instalada, necesitas importar el paquete datadog-ci y cargar manualmente tus metadatos de Git a Datadog. Te recomendamos que hagas esto cuando se inicialice tu CDK Stack.

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

Cambia tu función de inicialización de la siguiente manera (nota: estamos cambiando esto para pasar solo el valor gitHash al CDK):

``typescript async función main() { // Asegúrate de añadir @datadog/datadog-ci a través de tu administrador de paquete const datadogCi = require("@datadog/datadog-ci"); const [, gitHash] = await datadogCi.gitMetadata.uploadGitCommitHash(’{Datadog_API_Key}’, ‘’)

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.

Parámetro de paquete de npmParámetro de paquete de PyPIDescripción
addLayersadd_layersSi se añaden las Lambda Layers o se espera que el usuario traiga las suyas propias. Por defecto es true. Cuando es true, también se requieren las variables de la versión de la biblioteca Lambda. Cuando es false, debes incluir la biblioteca Datadog Lambda en los paquetes de despliegue de tus funciones.
pythonLayerVersionpython_layer_versionVersión de la capa Lambda Python que se va a instalar, como 83. Es necesario si estás desplegando al menos una función Lambda escrita en Python y addLayers es true. Encuentra el número de la última versión aquí.
nodeLayerVersionnode_layer_versionVersión de la capa Lambda de Node.js que se va a instalar, como 100. Es necesario si estás desplegando al menos una función Lambda escrita en Node.js y addLayers es true. Encuentra el número de la última versión en aquí.
javaLayerVersionjava_layer_versionVersión de la capa de Java que se va a instalar, como 8. Es necesario si estás desplegando al menos una función Lambda escrita en Java y addLayers es true. Encuentra el número de la última versión en la Documentación de instalación de Serverless Java. Nota: extensionLayerVersion >= 25 y javaLayerVersion >= 5 son necesarios para que la construcción de Datadog para instrumentar tus funciones de Java correctamente.
dotnetLayerVersiondotnet_layer_versionVersión de la capa de .NET que se va a instalar, como 13. Es necesario si estás desplegando al menos una función Lambda escrita en .NET y addLayers es true. Busca el número de la última versión en aquí.
extensionLayerVersionextension_layer_versionVersión de la capa de la extensión Datadog Lambda que se va a instalar, como por ejemplo 5. Cuando se configura extensionLayerVersion, también es necesario configurar apiKey (o si está cifrada, apiKMSKey o apiKeySecretArn). Cuando está activada, el Forwarder no se suscribirá a los grupos de logs de las funciones lambda. Más información sobre la extensión Lambda aquí.
forwarderArnforwarder_arnCuando se configura, el complemento suscribirá automáticamente el Datadog Forwarder a los grupos de logs de las funciones. No configures forwarderArn cuando extensionLayerVersion esté configurado.
createForwarderPermissionscreateForwarderPermissionsCuando se configura en true, crea un permiso Lambda en el Datadog Forwarder por cada grupo de logs. Dado que el Datadog Forwarder tiene permisos configurados por defecto, esto es innecesario en la mayoría de los casos de uso.
flushMetricsToLogsflush_metrics_to_logsEnvía métricas personalizadas utilizando logs de CloudWatch con la función lambda de Datadog Forwarder (recomendado). Por defecto es true. Si desactivas este parámetro, es necesario configurar apiKey (o si está cifrado, apiKMSKey o apiKeySecretArn).
sitesiteConfigura el sitio Datadog al cual se enviarán los datos. Solo se utiliza cuando flushMetricsToLogs es false o extensionLayerVersion está configurado. Los valores posibles son datadoghq.com, datadoghq.eu, us3.datadoghq.com, us5.datadoghq.com, ap1.datadoghq.com y ddog-gov.com. El valor por defecto es datadoghq.com.
apiKeyapi_keyLa clave de la API de Datadog, solo es necesaria cuando flushMetricsToLogs es false o extensionLayerVersion está configurado. Para obtener más información sobre cómo obtener una clave de la API de Datadog, consulta la documentación sobre la clave de la API.
apiKeySecretArnapi_key_secret_arnEl ARN del secreto que almacena la clave de la API de Datadog en AWS Secrets Manager. Utiliza este parámetro en lugar de apiKey cuando flushMetricsToLogs sea false o extensionLayer esté configurada. Recuerda añadir el permiso secretsmanager:GetSecretValue al rol de la ejecución Lambda.
apiKeySecretapi_key_secretUn AWS CDK ISecret que representa un secreto que almacena la clave de la API de Datadog en AWS Secrets Manager. Utiliza este parámetro en lugar de apiKeySecretArn para conceder automáticamente a los roles de ejecución de Lambda acceso de lectura al secreto indicado. Consulta aquí para ver un ejemplo. Solo está disponible en datadog-cdk-constructs-v2.
apiKmsKeyapi_kms_keyClave de la API de Datadog cifrada mediante KMS. Utiliza este parámetro en lugar de apiKey cuando flushMetricsToLogs es false o extensionLayerVersion está configurada y estás utilizando el cifrado KMS.
enableDatadogTracingenable_datadog_tracingActiva el rastreo de Datadog en tus funciones Lambda. Por defecto es true.
enableMergeXrayTracesenable_merge_xray_tracesActiva la fusión de trazas (traces) X-Ray en tus funciones Lambda. Por defecto es false.
enableDatadogLogsenable_datadog_logsEnvía los logs de las funciones Lambda a Datadog a través de la extensión Datadog Lambda. El valor por defecto es true. Nota: Esta configuración no tiene ningún efecto en los logs enviados a través de Datadog Forwarder .
enableSourceCodeIntegrationenable_source_code_integrationActiva la integración del código fuente de Datadog, conectando tu telemetría con el código de la aplicación en tus repositorios Git. Esto necesita la integración de Datadog Github para funcionar, de otro modo, sigue el método alternativo. Más información aquí. Por defecto es true.
injectLogContextinject_log_contextCuando se configura, la capa Lambda aplica un parche automáticamente a console.log con los identificadores de rastreo de Datadog. Por defecto es true.
logLevellog_levelCuando se configura en debug, la biblioteca y la extensión Datadog Lambda registra información adicional para ayudar a solucionar problemas.
envenvCuando se configura junto con extensionLayerVersion, se añade una variable de entorno DD_ENV a todas las funciones Lambda con el valor proporcionado. Cuando se configura junto con forwarderArn, se añade una etiqueta (tag) env a todas las funciones Lambda con el valor proporcionado.
serviceserviceCuando se configura junto con extensionLayerVersion, se añade una variable de entorno DD_SERVICE a todas las funciones Lambda con el valor proporcionado. Cuando se configura junto con forwarderArn, se añade una etiqueta service a todas las funciones Lambda con el valor proporcionado.
versionversionCuando se configura junto con extensionLayerVersion, se añade una variable de entorno DD_VERSION a todas las funciones Lambda con el valor proporcionado. Cuando se configura junto con forwarderArn, se añade una etiqueta version a todas las funciones Lambda con el valor proporcionado.
tagstagsUna lista separada por comas lista de pares clave:valor como una sola cadena. Cuando se configura junto con extensionLayerVersion, se añade una variable de entorno DD_TAGS a todas las funciones Lambda con el valor proporcionado. Cuando se configura junto con forwarderArn, el cdk analiza la cadena y configura cada par clave:valor como una etiqueta en todas las funciones Lambda.
enableColdStartTracingenable_cold_start_tracingConfigúralo en false para desactivar el rastreo de inicio en frío. Se utiliza en Node.js y Python. Por defecto es true.
coldStartTraceMinDurationmin_cold_start_trace_durationConfigura la duración mínima (en milisegundos) de un evento de carga de un módulo que se va a rastrear a través del rastreo de inicio en frío. Número. Por defecto es 3.
coldStartTraceSkipLibscold_start_trace_skip_libsOpcionalmente, omite la creación de tramos (spans) de inicio en frío para una lista separada por comas de bibliotecas. Es útil para limitar la profundidad u omitir bibliotecas conocidas. El valor por defecto depende del tiempo de ejecución.
enableProfilingenable_profilingActiva Datadog Continuous Profiler con true. Es compatible en Beta con Node.js y Python. Por defecto es false.
encodeAuthorizerContextencode_authorizer_contextCuando se configura en true para autorizadores Lambda, el contexto de rastreo se codificará en la respuesta para la propagación. Es compatible con Node.js y Python. Por defecto es true.
decodeAuthorizerContextdecode_authorizer_contextCuando se configura en true para Lambdas que están autorizadas a través de autorizadores Lambda, analizará y utilizará el contexto de rastreo codificado (si se encuentra). Es compatible con Node.js y Python. Por defecto es true.
apmFlushDeadlineapm_flush_deadlineSe utiliza para determinar cuándo enviar tramos antes de que se agote el tiempo, en milisegundos. Cuando el tiempo restante en una invocación de AWS lambda es inferior al valor configurado, el rastreador intenta enviar tramos activos actuales y todos los tramos finalizados. Es compatible con Node.js y Python. El valor por defecto es 100 milisegundos.
redirectHandlerredirect_handlerCuando se configura en false, omite la redirección del controlador al controlador de la biblioteca Datadog Lambda. Es útil cuando sólo se instrumenta con la extensión Datadog Lambda. Por defecto es true.

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

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.