Instrumentación de aplicaciones serverless de Java
Para completar la instrumentación de tu aplicación serverless con el rastreo distribuido, debes tener tus funciones de Lambda de Java con los tiempos de ejecución Java 8 Corretto (java8.al2
), Java 11 (java11
), Java 17 (java17
) o Java 21 (java21
) con al menos 1024 MB de memoria.
Si despliegas tus funciones de Lambda en una VPC sin acceso a la Internet pública, puedes enviar datos con AWS PrivateLink para el sitio de Datadog datadoghq.com
, o bien mediante un proxy, en caso de que uses cualquier otro sitio.
Si ya configuraste tus funciones de Lambda con el Datadog Forwarder, consulta la sección de instrumentación mediante el Datadog Forwarder. De lo contrario, sigue las instrucciones de esta guía para instrumentar mediante la Datadog Lambda Extension.
Si utilizas las capas de Lambda de Datadog dd-trace-java:4
(o anteriores) y Datadog-Extension:24
(o anteriores), sigue las instrucciones de actualización especiales.
Instalación
Datadog ofrece muchas formas diferentes de habilitar la instrumentación para tus aplicaciones serverless. Elige a continuación el método que mejor se adapte a tus necesidades. Por lo general, Datadog recomienda utilizar la Datadog CLI (interfaz de línea de comandos). Debes seguir las instrucciones para “Imagen de contenedor” si despliegas tu aplicación como una imagen de contenedor.
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.
Instalar el cliente de la Datadog CLI
npm install -g @datadog/datadog-ci
Si es la primera vez que usas la monitorización serverless de Datadog, inicia la Datadog CLI en el modo interactivo para recibir instrucciones sobre cómo realizar la primera instalación. Esto te permitirá entrar en materia rápidamente y saltarte los demás pasos de esta página. Si deseas instalar Datadog de forma permanente en tus aplicaciones de producción, omite ese paso y dirígete directamente a los siguientes para ejecutar el comando de la Datadog CLI en tus pipelines de CI/CD después de haber desplegado como lo haces normalmente.
datadog-ci lambda instrument -i
Configurar las credenciales de AWS
La Datadog CLI necesita acceder al servicio AWS Lambda y depende del SDK de AWS para JavaScript a la hora de configurar las credenciales. Asegúrate de que tus credenciales de AWS estén configuradas con el mismo método que utilizarás para invocar la AWS CLI.
Configurar el sitio de Datadog
export DATADOG_SITE="<DATADOG_SITE>"
Reemplaza <DATADOG_SITE>
por
(asegúrate de seleccionar el sitio [SITE] correcto del lado derecho).
Configurar la clave de la API de Datadog
Datadog recomienda guardar la clave de la API de Datadog en AWS Secrets Manager para una mayor seguridad y una rotación más sencilla. La clave debe almacenarse en una cadena de texto sin formato (no en un blob JSON). Además, asegúrate de que tus funciones de Lambda tengan el permiso de IAM obligatorio secretsmanager:GetSecretValue
.
export DATADOG_API_KEY_SECRET_ARN="<DATADOG_API_KEY_SECRET_ARN>"
Si quieres hacer un testeo rápido, también puedes configurar la clave de la API de Datadog en texto sin formato:
export DATADOG_API_KEY="<DATADOG_API_KEY>"
Instrumentar las funciones de Lambda
Nota: Antes que nada, instrumenta tus funciones de Lambda en un entorno de desarrollo o de prueba. Si el resultado de la instrumentación no es satisfactorio, puedes ejecutar uninstrument
con los mismos argumentos para revertir los cambios.
Para instrumentar tus funciones de Lambda, ejecuta el siguiente comando.
datadog-ci lambda instrument -f <functionname> -f <another_functionname> -r <aws_region> -v 15 -e 66
Para rellenar los parámetros:
- Reemplaza
<functionname>
y <another_functionname>
por los nombres de tus funciones de Lambda. Otra posibilidad es usar --functions-regex
para instrumentar automáticamente varias funciones cuyos nombres coincidan con una expresión regular determinada. - Reemplaza
<aws_region>
por el nombre de la región de AWS.
Si necesitas parámetros adicionales, consulta la documentación acerca de la CLI.
El complemento Datadog Serverless Plugin configura automáticamente tus funciones para enviar métricas, trazas (traces) y logs a Datadog mediante la Datadog Lambda Extension.
Para instalar y configurar el Datadog Serverless Plugin, sigue estos pasos:
Instala el Datadog Serverless Plugin:
serverless plugin install --name serverless-plugin-datadog
Actualiza tu archivo serverless.yml
:
custom:
datadog:
site: <DATADOG_SITE>
apiKeySecretArn: <DATADOG_API_KEY_SECRET_ARN>
Para rellenar los parámetros:
- Reemplaza
<DATADOG_SITE>
por
(asegúrate de seleccionar el sitio [SITE] correcto del lado derecho). - Reemplaza
<DATADOG_API_KEY_SECRET_ARN>
por el ARN del secreto de AWS en el que almacenaste la clave de la API de Datadog de forma segura. La clave debe estar almacenada en una cadena de texto sin formato (no en un blob JSON). Además, el permiso secretsmanager:GetSecretValue
es obligatorio. Si quieres hacer un testeo rápido, puedes usar apiKey
en lugar del ARN y configurar la clave de la API de Datadog en texto sin formato.
Para obtener más información y parámetros adicionales, consulta la documentación acerca del complemento.
La macro de CloudFormation de Datadog transforma automáticamente tu plantilla de aplicación de SAM para instalar Datadog en tus funciones con las capas de Lambda. Además, configura las funciones para enviar métricas, trazas y logs a Datadog a través de la Datadog Lambda Extension.
Instalar la macro de CloudFormation de Datadog
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. Reemplaza 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 las funciones de Lambda
Añade la transformación DatadogServerless
después de la transformación AWS::Serverless
en la sección Transform
de tu archivo template.yml
para SAM.
Transform:
- AWS::Serverless-2016-10-31
- Name: DatadogServerless
Parameters:
stackName: !Ref "AWS::StackName"
javaLayerVersion: 15
extensionLayerVersion: 66
site: "<DATADOG_SITE>"
apiKeySecretArn: "<DATADOG_API_KEY_SECRET_ARN>"
Para rellenar los parámetros:
- Reemplaza
<DATADOG_SITE>
por
(asegúrate de seleccionar el sitio [SITE] correcto del lado derecho). - Reemplaza
<DATADOG_API_KEY_SECRET_ARN>
por el ARN del secreto de AWS en el que almacenaste la clave de la API de Datadog de forma segura. La clave debe estar almacenada en una cadena de texto sin formato (no en un blob JSON). Además, el permiso secretsmanager:GetSecretValue
es obligatorio. Si quieres hacer un testeo rápido, puedes usar apiKey
en lugar del ARN y configurar la clave de la API de Datadog en texto sin formato.
Obtén más información y parámetros adicionales en la documentación de la macro.
La instrumentación de funciones de Java a través del constructo del CDK de Datadog solo está disponible para aplicaciones del CDK de AWS escritas en Node.js y Python.
El constructo del CDK de Datadog instala automáticamente Datadog en tus funciones con las capas de Lambda. Además, configura tus funciones para enviar métricas, trazas y logs a Datadog a través de la Datadog Lambda Extension.
Instalar la biblioteca de constructos del CDK de Datadog
Node.js:
# For AWS CDK v1
npm install datadog-cdk-constructs --save-dev
# For AWS CDK v2
npm install datadog-cdk-constructs-v2 --save-dev
Python:
# For AWS CDK v1
pip install datadog-cdk-constructs
# For AWS CDK v2
pip install datadog-cdk-constructs-v2
Instrumentar las funciones de Lambda
Node.js:
// For AWS CDK v1
import { Datadog } from "datadog-cdk-constructs";
// For AWS CDK v2
import { Datadog } from "datadog-cdk-constructs-v2";
const datadog = new Datadog(this, "Datadog", {
javaLayerVersion: 15,
extensionLayerVersion: 66,
site: "<DATADOG_SITE>",
apiKeySecretArn: "<DATADOG_API_KEY_SECRET_ARN>"
});
datadog.addLambdaFunctions([<LAMBDA_FUNCTIONS>])
Python:
# For AWS CDK v1
from datadog_cdk_constructs import Datadog
# For AWS CDK v2
from datadog_cdk_constructs_v2 import Datadog
datadog = Datadog(self, "Datadog",
java_layer_version=15,
extension_layer_version=66,
site="<DATADOG_SITE>",
api_key_secret_arn="<DATADOG_API_KEY_SECRET_ARN>",
)
datadog.add_lambda_functions([<LAMBDA_FUNCTIONS>])
Para rellenar los parámetros:
- Reemplaza
<DATADOG_SITE>
por
(asegúrate de seleccionar el sitio [SITE] correcto del lado derecho). - Reemplaza
<DATADOG_API_KEY_SECRET_ARN>
por el ARN del secreto de AWS en el que almacenaste la clave de la API de Datadog de forma segura. La clave debe estar almacenada en una cadena de texto sin formato (no en un blob JSON). Asegúrate de que el rol de ejecución de Lambda tenga el permiso de IAM secretsmanager:GetSecretValue
para que pueda leer el valor del secreto. Si quieres hacer un testeo rápido, puedes usar apiKey
en lugar del ARN y configurar la clave de la API de Datadog en texto sin formato.
Obtén más información y parámetros adicionales en la documentación del CDK de Datadog.
Instalar la Datadog Lambda Extension
COPY --from=public.ecr.aws/datadog/lambda-extension:<TAG> /opt/. /opt/
Reemplaza <TAG>
por un número de versión específico (por ejemplo, 66
) o por latest
. Alpine también es compatible con números de versión específicos (como 66-alpine
) o con latest-alpine
. Puedes ver una lista completa de posibles etiquetas (tags) en el repositorio de Amazon ECR.
Instalar el cliente de Datadog APM para .NET
RUN yum -y install tar wget gzip
RUN wget -O /opt/java/lib/dd-java-agent.jar 'https://dtdg.co/latest-java-tracer'
Configurar las variables de entorno obligatorias
- Configura
AWS_LAMBDA_EXEC_WRAPPER
como /opt/datadog_wrapper
. - Configura
DD_SITE
como
(asegúrate de seleccionar el sitio [SITE] correcto del lado derecho). - Configura
DD_API_KEY_SECRET_ARN
con el ARN del secreto de AWS en el que almacenaste la clave de la API de Datadog de forma segura. La clave debe estar almacenada en una cadena de texto sin formato (no en un blob JSON). Además, el permiso secretsmanager:GetSecretValue
es obligatorio. Si quieres hacer un testeo rápido, puedes usar DD_API_KEY
en lugar del ARN y configurar la clave de la API de Datadog en texto sin formato.
El módulo de Terraform lambda-datadog
envuelve el recurso aws_lambda_function
y configura automáticamente tu función de Lambda para Datadog Serverless Monitoring mediante las siguientes acciones:
- adición de las capas de Lambda de Datadog,
- redireccionamiento del controlador de Lambda,
- habilitación de la recopilación y el envío de métricas, trazas y logs a Datadog.
module "lambda-datadog" {
source = "DataDog/lambda-datadog/aws"
version = "2.0.0"
environment_variables = {
"DD_API_KEY_SECRET_ARN" : "<DATADOG_API_KEY_SECRET_ARN>"
"DD_ENV" : "<ENVIRONMENT>"
"DD_SERVICE" : "<SERVICE_NAME>"
"DD_SITE": "<DATADOG_SITE>"
"DD_VERSION" : "<VERSION>"
}
datadog_extension_layer_version = 67
datadog_java_layer_version = 15
# los argumentos de aws_lambda_function
}
Reemplaza el recurso aws_lambda_function
por el módulo de Terraform lambda-datadog
. Luego, especifica el origen source
y la versión version
del módulo.
Configura los argumentos de aws_lambda_function
:
Todos los argumentos disponibles en el recurso aws_lambda_function
están disponibles en este módulo de Terraform. Los argumentos definidos como bloques en el recurso aws_lambda_function
se redefinen como variables con sus argumentos anidados.
Por ejemplo, en aws_lambda_function
, environment
se define como un bloque con un argumento variables
. En el módulo de Terraform lambda-datadog
, el valor de environment_variables
se pasa al argumento environment.variables
en aws_lambda_function
. Consulta las entradas para ver una lista completa de las variables en este módulo.
Rellena los parámetros de las variables de entorno:
- Reemplaza
<DATADOG_API_KEY_SECRET_ARN>
por el ARN del secreto de AWS en el que almacenaste la clave de la API de Datadog de forma segura. La clave debe estar almacenada en una cadena de texto sin formato (no en un blob JSON). Además, el permiso secretsmanager:GetSecretValue
es obligatorio. Si quieres hacer un testeo rápido, puedes usar la variable de entorno DD_API_KEY
en lugar del ARN y configurar la clave de la API de Datadog en texto sin formato. - Reemplaza
<ENVIRONMENT>
por el entorno de la función de Lambda, como prod
o staging
. - Reemplaza
<SERVICE_NAME>
por el nombre del servicio de la función de Lambda. - Reemplaza
<DATADOG_SITE>
por
. (Asegúrate de seleccionar el sitio de Datadog correcto en esta página). - Reemplaza
<VERSION>
por el número de versión de la función de Lambda.
Selecciona las versiones de la capa de Lambda de la Datadog Extension y de la capa de Lambda de Datadog para Java que quieres usar. Si las dejas en blanco, se utilizarán las últimas versiones de las capas.
datadog_extension_layer_version = 67
datadog_java_layer_version = 15
Instalar el rastreador de Datadog
Configura las capas de tu función de Lambda con el ARN en el siguiente formato:
# Use this format for Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:dd-trace-java:15
# Use this format for Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:dd-trace-java:15
Reemplaza <AWS_REGION>
por una región de AWS válida, como us-east-1
.
Instalar la Datadog Lambda Extension
Configura las capas de tu función de Lambda con el ARN en el siguiente formato:
# Use this format for x86-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-Extension:66
# Use this format for arm64-based Lambda deployed in AWS commercial regions
arn:aws:lambda:<AWS_REGION>:464622532012:layer:Datadog-Extension-ARM:66
# Use this format for x86-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-Extension:66
# Use this format for arm64-based Lambda deployed in AWS GovCloud regions
arn:aws-us-gov:lambda:<AWS_REGION>:002406178527:layer:Datadog-Extension-ARM:66
Reemplaza <AWS_REGION>
por una región de AWS válida, como us-east-1
.
Configurar las variables de entorno obligatorias
- Configura
AWS_LAMBDA_EXEC_WRAPPER
como /opt/datadog_wrapper
. - Configura
DD_SITE
como
(asegúrate de seleccionar el sitio [SITE] correcto del lado derecho). - Configura
DD_API_KEY_SECRET_ARN
con el ARN del secreto de AWS en el que almacenaste la clave de la API de Datadog de forma segura. La clave debe estar almacenada en una cadena de texto sin formato (no en un blob JSON). Además, el permiso secretsmanager:GetSecretValue
es obligatorio. Si quieres hacer un testeo rápido, puedes usar DD_API_KEY
en lugar del ARN y configurar la clave de la API de Datadog en texto sin formato.
¿Qué toca hacer ahora?
- Ya puedes consultar métricas, logs y trazas en la página de inicio Serverless.
- Activa la monitorización de amenazas para recibir alertas sobre los atacantes que tienen tu servicio como objetivo.
- Envía una métrica personalizada o un tramo (span) de APM para monitorizar tu lógica de negocio.
- Consulta la guía de solución de problemas si tienes dificultades para recopilar la telemetría.
- Consulta las configuraciones avanzadas para saber cómo hacer lo siguiente:
- conectar tu telemetría mediante el uso de tags,
- recopilar telemetría para Amazon API Gateway, SQS, etc.;
- capturar las cargas útiles de solicitud y respuesta de Lambda;
- vincular los errores de tus funciones de Lambda con tu código fuente;
- filtrar o borrar información confidencial de logs o trazas.
Referencias adicionales
Más enlaces, artículos y documentación útiles: