Instrumentación de aplicaciones serverless de Node.js mediante el Datadog Forwarder

Información general

Si recién empiezas a utilizar Datadog Serverless, sigue las instrucciones para instrumentar tus funciones de Lambda mediante la Datadog Lambda Extension. Si configuraste Datadog Serverless con el Datadog Forwarder antes que la funcionalidad de Lambda lista para usar, utiliza esta guía para mantener tu instancia.

Requisitos previos

Se necesita la función de Lambda del Datadog Forwarder para ingerir las trazas (traces), las métricas mejoradas, las métricas personalizadas y los logs de AWS Lambda.

Configuración

La Datadog CLI modifica la configuración de las funciones de Lambda existentes para permitir la instrumentación sin tener que volver a desplegar. Es la forma más rápida de empezar a trabajar con la monitorización serverless de Datadog.

También puedes añadir el comando a tus pipelines de CI/CD y así activar la instrumentación para todas tus aplicaciones serverless. Ejecuta el comando después del despliegue normal de tu aplicación serverless para evitar que los cambios del comando de la Datadog CLI se sobrescriban.

Instalar

Instala la Datadog CLI con NPM o Yarn:

# NPM
npm install -g @datadog/datadog-ci

# Yarn
yarn global add @datadog/datadog-ci

Instrumentar

Para instrumentar la función, ejecuta el siguiente comando con tus credenciales de AWS.

datadog-ci lambda instrument -f <functionname> -f <another_functionname> -r <aws_region> -v <layer_version> --forwarder <forwarder_arn>

Para rellenar los parámetros, haz lo siguiente:

  • Reemplaza <functionname> y <another_functionname> por los nombres de tu función de Lambda.
  • Reemplaza <aws_region> por el nombre de la región de AWS.
  • Reemplaza <layer_version> por la versión de la biblioteca Lambda de Datadog que quieres utilizar. La última versión es 121.
  • Reemplaza <forwarder_arn> por el nombre de recurso de Amazon (ARN) del Forwarder (consulta la documentación del Forwarder).

Por ejemplo:

datadog-ci lambda instrument -f my-function -f another-function -r us-east-1 -v 121 --forwarder "arn:aws:lambda:us-east-1:000000000000:function:datadog-forwarder"

Si configuraste tu función de Lambda para utilizar la firma de código, debes añadir el ARN del perfil de firma de Datadog (arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc) a la configuración de firma de código de tu función antes de poder instrumentarla con la Datadog CLI.

Obtén más información y parámetros adicionales en la documentación de la CLI.

El complemento Datadog Serverless Plugin añade la biblioteca Lambda de Datadog automáticamente a tus funciones mediante capas y configura las funciones para enviar métricas, trazas y logs a Datadog a través del Datadog Forwarder.

Si configuraste tu función de Lambda para utilizar la firma de código, debes añadir el ARN del perfil de firma de Datadog (arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc) a la configuración de firma de código de tu función antes de poder instalar el Datadog Serverless Plugin.

Para instalar y configurar el Datadog Serverless Plugin, sigue estos pasos:

  1. Instala el Datadog Serverless Plugin:
    yarn add --dev serverless-plugin-datadog
  2. Añade lo siguiente a tu archivo serverless.yml:
    plugins:
  - serverless-plugin-datadog
  3. Añade también la siguiente sección a tu archivo serverless.yml:
    custom:
  datadog:
    forwarderArn: # The Datadog Forwarder ARN goes here.
    Puedes obtener más información sobre el ARN o la instalación del Datadog Forwarder aquí. Consulta parámetros adicionales en la documentación del complemento.

Nota: Tendrás que seguir estos pasos de configuración adicionales si tu función de Lambda utiliza las bibliotecas de rastreo de Datadog y webpack de forma simultánea.

La macro de CloudFormation de Datadog transforma automáticamente tu plantilla de aplicación de SAM para añadir la biblioteca Lambda de Datadog a tus funciones mediante las capas. Además, configura las funciones para enviar métricas, trazas y logs a Datadog a través del Datadog Forwarder.

Instalar

Ejecuta el siguiente comando con tus credenciales de AWS para desplegar un stack tecnológico de CloudFormation que instale el recurso de AWS de la macro. Solo tienes que instalar la macro una vez en una región determinada de tu cuenta. Luego, debes reemplazar create-stack por update-stack para actualizar la macro a la versión más reciente.

aws cloudformation create-stack \
  --stack-name datadog-serverless-macro \
  --template-url https://datadog-cloudformation-template.s3.amazonaws.com/aws/serverless-macro/latest.yml \
  --capabilities CAPABILITY_AUTO_EXPAND CAPABILITY_IAM

Con estos pasos, la macro ya está desplegada y lista para usar.

Instrumentar

En tu archivo template.yml, añade lo siguiente en la sección Transform (Transformación), después de la transformación AWS::Serverless para SAM.

Transform:
  - AWS::Serverless-2016-10-31
  - Name: DatadogServerless
    Parameters:
      stackName: !Ref "AWS::StackName"
      nodeLayerVersion: "121"
      forwarderArn: "<FORWARDER_ARN>"
      service: "<SERVICE>" # Opcional
      env: "<ENV>" # Opcional

Para rellenar los parámetros, haz lo siguiente:

  • Reemplaza <FORWARDER_ARN> por el ARN del Forwarder (consulta la documentación del Forwarder).
  • Reemplaza <SERVICE> y <ENV> por los valores de tu servicio y entorno.

Si configuraste tu función de Lambda para utilizar la firma de código, debes añadir el ARN del perfil de firma de Datadog (arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc) a la configuración de firma de código de tu función antes de poder usar la macro.

Obtén más información y parámetros adicionales en la documentación de la macro.

Las Construcciones del Datadog CDK configuran automáticamente la ingesta de métricas, trazas y logs de tus aplicaciones serverless mediante las siguientes acciones:

  • La instalación y configuración de la biblioteca Lambda de Datadog para tus funciones de Lambda de Python y Node.js.
  • La habilitación de la recopilación de trazas y métricas personalizadas de tus funciones de Lambda.
  • La gestión de las suscripciones del Datadog Forwarder a los grupos de logs de tus funciones de Lambda.

Instalar

Ejecuta el siguiente comando de Yarn o NPM en tu proyecto del CDK para instalar la biblioteca de Construcciones del Datadog CDK:

#Yarn
yarn add --dev datadog-cdk-constructs

#NPM
npm install datadog-cdk-constructs --save-dev

Instrumentar

Para instrumentar la función, importa el módulo datadog-cdk-construct en tu aplicación de AWS CDK y añade las siguientes configuraciones (este ejemplo es de TypeScript, pero el uso en otros lenguajes es similar):

import * as cdk from "@aws-cdk/core";
import { Datadog } from "datadog-cdk-constructs";

class CdkStack extends cdk.Stack {
  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);
    const datadog = new Datadog(this, "Datadog", {
      nodeLayerVersion: 121,
      forwarderArn: "<FORWARDER_ARN>",
      service: "<SERVICE>",  // Opcional
      env: "<ENV>",  // Opcional
    });
    datadog.addLambdaFunctions([<LAMBDA_FUNCTIONS>])
  }
}

Para rellenar los parámetros, haz lo siguiente:

  • Reemplaza <FORWARDER_ARN> por el ARN del Forwarder (consulta la documentación del Forwarder).
  • Reemplaza <SERVICE> y <ENV> por los valores de tu servicio y entorno.

Si configuraste tu función de Lambda para utilizar la firma de código, debes añadir el ARN del perfil de firma de Datadog (arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc) a la configuración de firma de código de tu función antes de poder usar la macro.

Obtén más información y parámetros adicionales en la página de NPM del Datadog CDK.

Instalar

Si vas a desplegar tu función de Lambda como una imagen de contenedor, no puedes utilizar la biblioteca Lambda de Datadog como una capa. En su lugar, debes instalar la biblioteca Lambda de Datadog como una dependencia de tu función dentro de la imagen. Si quieres utilizar el rastreo de Datadog, también debes instalar dd-trace.

NPM:

npm install --save datadog-lambda-js dd-trace

Yarn:

yarn add datadog-lambda-js dd-trace

Nota: La versión secundaria del paquete datadog-lambda-js siempre coincide con la versión de la capa. Por ejemplo, datadog-lambda-js v0.5.0 coincide con el contenido de la versión 5 de la capa.

Configurar

Sigue estos pasos para configurar la función:

  1. Define el valor CMD de tu imagen como node_modules/datadog-lambda-js/dist/handler.handler. Puedes hacerlo en AWS o directamente en tu Dockerfile. Nota: El valor de AWS sobrescribirá el valor del Dockerfile si los defines por separado.
  2. Configura las siguientes variables de entorno en AWS:
  • Define DD_LAMBDA_HANDLER como tu controlador original, por ejemplo, myfunc.handler.
  • Define DD_TRACE_ENABLED como true.
  • Define DD_FLUSH_TO_LOG como true.
  1. Otra opción es añadir las etiquetas (tags) service y env con los valores adecuados a tu función.

Subscribir

Suscribe la función de Lambda del Datadog Forwarder a cada uno de los grupos de logs de tus funciones para enviar métricas, trazas y logs a Datadog.

  1. Instala el Datadog Forwarder si todavía no lo hiciste.
  2. Suscribe el Datadog Forwarder a los grupos de logs de tu función.

Instalar

La biblioteca Lambda de Datadog puede importarse como una capa o como un paquete de JavaScript.

La versión secundaria del paquete datadog-lambda-js siempre coincide con la versión de la capa. Por ejemplo, la versión 0.5.0 de datadog-lambda-js coincide con el contenido de la versión 5 de la capa.

Como una capa

Configura las capas de tu función de Lambda con el ARN en el siguiente formato.

# Para las regiones us, us3, us5, eu y ap1
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-<RUNTIME>:<VERSION>

# Para las regiones us-gov
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-<RUNTIME>:<VERSION>

Las opciones disponibles en RUNTIME son Node18-x, Node20-x, Node22-x. La última VERSION es 121. Por ejemplo:

arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Node22-x:121

Si configuraste tu función de Lambda para utilizar la firma de código, debes añadir el ARN del perfil de firma de Datadog (arn:aws:signer:us-east-1:464622532012:/signing-profiles/DatadogLambdaSigningProfile/9vMI9ZAGLc) a la configuración de firma de código de tu función antes de poder añadir la biblioteca Lambda de Datadog como una capa.

Como un paquete

NPM:

npm install --save datadog-lambda-js

Yarn:

yarn add datadog-lambda-js

Consulta la última versión.

Configurar

Sigue estos pasos para configurar la función:

  1. Configura el controlador de tu función como /opt/nodejs/node_modules/datadog-lambda-js/handler.handler si utilizas la capa, o node_modules/datadog-lambda-js/dist/handler.handler si utilizas el paquete.
  2. Define la variable de entorno DD_LAMBDA_HANDLER como tu controlador original, por ejemplo, myfunc.handler.
  3. Define la variable de entorno DD_TRACE_ENABLED como true.
  4. Define la variable de entorno DD_FLUSH_TO_LOG como true.
  5. Otra opción es añadir las etiquetas service y env con los valores adecuados para tu función.

Nota: Tendrás que seguir estos pasos de configuración adicionales si tu función de Lambda utiliza las bibliotecas de rastreo de Datadog y webpack de forma simultánea.

Subscribir

Suscribe la función de Lambda del Datadog Forwarder a cada uno de los grupos de logs de tu función para enviar métricas, trazas y logs a Datadog.

  1. Instala el Datadog Forwarder si todavía no lo hiciste.
  2. Suscribe el Datadog Forwarder a los grupos de logs de tu función.

Etiquetar

Aunque es opcional, Datadog recomienda etiquetar las aplicaciones serverless con las etiquetas env, service y version para el etiquetado de servicios unificado.

Explorar

Una vez que tienes tu función configurada según los pasos anteriores, puedes consultar tus métricas, logs y trazas en la página de inicio de Serverless.

Monitorizar la lógica de negocio personalizada

Si quieres enviar una métrica o un tramo (span) personalizados, consulta el siguiente código de ejemplo:

const { sendDistributionMetric, sendDistributionMetricWithDate } = require("datadog-lambda-js");
const tracer = require("dd-trace");

// envía un tramo personalizado con el nombre "sleep"
const sleep = tracer.wrap("sleep", (ms) => {
  return new Promise((resolve) => setTimeout(resolve, ms));
});

exports.handler = async (event) => {
  // añade etiquetas personalizadas al tramo de la función de Lambda,
  // NO funciona si el rastreo de X-Ray está habilitado
  const span = tracer.scope().active();
  span.setTag('customer_id', '123456');

  await sleep(100);

  // envía un tramo personalizado
  const sandwich = tracer.trace('hello.world', () => {
    console.log('Hello, World!');
  });

  // envía una métrica personalizada
  sendDistributionMetric(
    "coffee_house.order_value", // el nombre de la métrica
    12.45, // el valor de la métrica
    "product:latte", // una etiqueta
    "order:online", // otra etiqueta
  );

  // envía una métrica personalizada con una marca de tiempo
  sendDistributionMetricWithDate(
    "coffee_house.order_value", // el nombre de la métrica
    12.45, // el valor de la métrica
    new Date(Date.now()), // la fecha, debe estar dentro de los últimos 20 minutos
    "product:latte", // una etiqueta
    "order:online", // otra etiqueta
  );

  const response = {
    statusCode: 200,
    body: JSON.stringify("Hello from serverless!"),
  };
  return response;
};

Para obtener más información sobre el envío de métricas personalizadas, consulta Métricas personalizadas de aplicaciones serverless. Para obtener más información sobre la instrumentación personalizada, consulta la documentación de Datadog APM en la sección de instrumentación personalizada.

Referencias adicionales

Más enlaces, artículos y documentación útiles:

PREVIEWING: dgreen15/adding-custom-entities