Instrumentación de aplicaciones serverless de Python mediante el Datadog Forwarder

Documentos > Serverless > Guías de Serverless Monitoring > Instrumentación de aplicaciones serverless de Python 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 de que Lambda ofreciera la funcionalidad 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 102.
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 102 --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 una capa 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][4] de tu función antes de poder instalar el Datadog Serverless Plugin.

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

Instala el Datadog Serverless Plugin:

yarn add --dev serverless-plugin-datadog

Añade lo siguiente a tu archivo serverless.yml:
```
plugins:
  - serverless-plugin-datadog
```
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.

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

Para instrumentar tu función, añade lo siguiente al archivo template.yml 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:
      pythonLayerVersion: "102"
      stackName: !Ref "AWS::StackName"
      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.

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

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

Instalar

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

Para instrumentar la función, añade la transformación DatadogServerless y la asignación CfnMapping al objeto Stack en tu aplicación del AWS CDK. Consulta el siguiente código de ejemplo en Python (el uso en otro lenguaje debería ser similar).

from aws_cdk import core

class CdkStack(core.Stack):
  def __init__(self, scope: core.Construct, id: str, **kwargs) -> None:
    super().__init__(scope, id, **kwargs)
    self.add_transform("DatadogServerless")

    mapping = core.CfnMapping(self, "Datadog",
      mapping={
        "Parameters": {
          "pythonLayerVersion": "102",
          "forwarderArn": "<FORWARDER_ARN>",
          "stackName": self.stackName,
          "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.

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

Actualizar parámetros

Añade los siguientes parámetros a tu archivo zappa_settings.json:

{
    "dev": {
        "layers": ["arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-<RUNTIME>:<VERSION>"],
        "lambda_handler": "datadog_lambda.handler.handler",
        "aws_environment_variables": {
            "DD_LAMBDA_HANDLER": "handler.lambda_handler",
            "DD_TRACE_ENABLED": "true",
            "DD_FLUSH_TO_LOG": "true",
        },
    }
}

Reemplaza los parámetros <AWS_REGION>, <RUNTIME> y <VERSION> en el ARN de la capa por los valores adecuados. Las opciones disponibles de RUNTIME son Python38, Python39, Python310, Python311, Python312. La última VERSION es 102. Por ejemplo:
```
# For regular regions
arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Python312:102

# For us-gov regions
arn:aws-us-gov:lambda:us-gov-east-1:002406178527:layer:Datadog-Python312:102
```
Si configuraste tu función de Lambda para utilizar la firma de código, añade 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.

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.

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

Actualizar el proyecto

Define las variables de entorno DD_TRACE_ENABLED y DD_FLUSH_TO_LOG como "true" en tu archivo config.json:

{
  "version": "2.0",
  "app_name": "hello-chalice",
  "stages": {
    "dev": {
      "api_gateway_stage": "api",
      "environment_variables": {
        "DD_TRACE_ENABLED": "true",
        "DD_FLUSH_TO_LOG": "true"
      }
    }
  }
}

Añade datadog_lambda a tu archivo requirements.txt.

Registra datadog_lambda_wrapper como middleware en tu archivo app.py:

from chalice import Chalice, ConvertToMiddleware
from datadog_lambda.wrapper import datadog_lambda_wrapper

app = Chalice(app_name='hello-chalice')

app.register_middleware(ConvertToMiddleware(datadog_lambda_wrapper))

@app.route('/')
def index():
    return {'hello': 'world'}

Si configuraste tu función de Lambda para utilizar la firma de código, añade 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.

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.

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

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.

pip install datadog-lambda

Ten en cuenta que la versión secundaria del paquete datadog-lambda siempre coincide con la versión de la capa. Por ejemplo, datadog-lambda v0.5.0 coincide con el contenido de la versión 5 de la capa.

Configurar

Sigue estos pasos para configurar la función:

Define el valor CMD de tu imagen como datadog_lambda.handler.handler. Puedes hacerlo en AWS o directamente en tu Dockerfile. Ten en cuenta que el valor de AWS sobrescribirá el valor del Dockerfile si los defines por separado.
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.

Otra opción es añadir las etiquetas (tags) service y env con los valores adecuados para 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.

Instalar

Puedes instalar la biblioteca Lambda de Datadog como una capa (recomendado) o como un paquete de Python.

La versión secundaria del paquete datadog-lambda siempre coincide con la versión de la capa. Por ejemplo, la versión 0.5.0 de datadog-lambda 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, ap1 y eu
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 Python38, Python39, Python310, Python311, Python312. La última VERSION es 102. Por ejemplo:

arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Python312:102

Como un paquete

Instala datadog-lambda y sus dependencias localmente en la carpeta del proyecto de tu función. Nota: datadog-lambda depende de ddtrace, que utiliza extensiones nativas; por lo tanto, deben instalarse y compilarse en un entorno de Linux. Por ejemplo, puedes utilizar dockerizePip para el Serverless Framework y –use-container para AWS SAM. Para obtener más información, consulta cómo añadir dependencias al paquete de despliegue de tu función.

pip install datadog-lambda -t ./

Consulta la última versión.

Configurar

Sigue estos pasos para configurar la función:

Configura el controlador de tu función como datadog_lambda.handler.handler.
Define la variable de entorno DD_LAMBDA_HANDLER como tu controlador original, por ejemplo, myfunc.handler.
Define la variable de entorno DD_TRACE_ENABLED como true.
Define la variable de entorno DD_FLUSH_TO_LOG como true.
Otra opción es añadir las etiquetas service y env con los valores adecuados para tu función.

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.

Instala el Datadog Forwarder si todavía no lo hiciste.
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:

import time
from ddtrace import tracer
from datadog_lambda.metric import lambda_metric

def lambda_handler(event, context):
    # añade etiquetas personalizadas al tramo de la función de Lambda,
    # NO funciona si el rastreo de X-Ray está habilitado
    current_span = tracer.current_span()
    if current_span:
        current_span.set_tag('customer.id', '123456')

    # envía un tramo personalizado
    with tracer.trace("hello.world"):
        print('Hello, World!')

    # envía una métrica personalizada
    lambda_metric(
        metric_name='coffee_house.order_value',
        value=12.45,
        timestamp=int(time.time()), # opcional, debe estar dentro de los últimos 20 minutos
        tags=['product:latte', 'order:online']
    )

    return {
        'statusCode': 200,
        'body': get_message()
    }

# rastrea una función
@tracer.wrap()
def get_message():
    return 'Hello from serverless!'

Para obtener más información sobre el envío de métricas personalizadas, consulta los detalles aquí. 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: