Instrumentación del código Java en AWS Lambda

Lambda se integra con AWS X-Ray para permitirle seguir, depurar y optimizar aplicaciones de Lambda. Puede utilizar X-Ray para seguir una solicitud mientras atraviesa los recursos de la aplicación, que pueden incluir funciones de Lambda y otros servicios de AWS.

Para enviar datos de seguimiento a X-Ray, puede utilizar una de estas dos bibliotecas de SDK:

• AWS Distro for OpenTelemetry (ADOT): distribución segura, lista para producción y con soporte de AWS del OpenTelemetry (OTel) SDK.

• AWS X-Ray SDK para Java: un SDK para generar y enviar datos de seguimiento a X-Ray.

Tanto ADOT como el X-Ray SDK ofrecen formas de enviar los datos de telemetría al servicio X-Ray. Tras ello, se puede utilizar X-Ray para consultar, filtrar y obtener información sobre las métricas de rendimiento de la aplicación con el fin de identificar problemas y oportunidades de optimización.

importante

Los SDK de X-Ray son parte de una solución de instrumentación estrechamente integrada que ofrece AWS. Las capas Lambda de ADOT forman parte de un estándar que abarca todo el sector para la instrumentación de seguimiento que recopila más datos en general, pero es posible que no sean adecuadas para todos los casos de uso. Puede implementar el seguimiento integral en X-Ray con cualquiera de las soluciones. Para obtener más información sobre cuál elegir, consulte Elegir entre SDK de AWS Distro para OpenTelemetry y X-Ray.

Uso de ADOT para instrumentar las funciones de Java

ADOT proporciona capas de Lambda completamente administradas que empaquetan todo lo necesario para recopilar datos de telemetría mediante el OTel SDK. Utilizando esta capa, se pueden instrumentar las funciones de Lambda sin tener que modificar el código de ninguna función. También se puede configurar la capa para que realice una inicialización personalizada de OTel. Para obtener más información, consulte Configuración personalizada del recopilador de ADOT en Lambda en la documentación de ADOT.

Para los tiempos de ejecución de Java, puede elegir entre dos capas:

• Capa de Lambda administrada de AWS para ADOT Java (agente de instrumentación automática): esta capa transforma automáticamente el código de la función durante el inicio para recopilar datos de seguimiento. Para obtener instrucciones detalladas sobre cómo utilizar esta capa junto con el agente de ADOT Java, consulte Soporte de Lambda de AWS Distro for OpenTelemetry para Java (agente de instrumentación automática) en la documentación de ADOT.

• Capa de Lambda administrada de AWS para ADOT Java: esta capa también proporciona instrumentación integrada para las funciones de Lambda, pero requiere algunos cambios de código manuales para inicializar el OTel SDK. Para obtener instrucciones detalladas sobre cómo utilizar esta capa, consulte Soporte de Lambda de AWS Distro for OpenTelemetry para Java en la documentación de ADOT.

Uso del X-Ray SDK para instrumentar las funciones de Java

Para registrar datos sobre las llamadas que realiza la función a otros recursos y servicios de la aplicación, se puede agregar el X-Ray SDK para Java a la configuración de compilación. En el siguiente ejemplo, se muestra una configuración de compilación de Gradle que incluye las bibliotecas que activan la instrumentación automática de los clientes de AWS SDK for Java 2.x.

ejemplo build.gradle: dependencias de seguimiento.

dependencies {
    implementation platform('software.amazon.awssdk:bom:2.15.0')
    implementation platform('com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0')
    ...
    implementation 'com.amazonaws:aws-xray-recorder-sdk-core'
    implementation 'com.amazonaws:aws-xray-recorder-sdk-aws-sdk'
    implementation 'com.amazonaws:aws-xray-recorder-sdk-aws-sdk-instrumentor'
    ...
}

Una vez agregadas las dependencias correctas y realizados los cambios de código necesarios, active el seguimiento en la configuración de la función mediante la consola de Lambda o la API.

Activación del seguimiento con la consola de Lambda

Para activar el seguimiento activo de la función Lambda mediante la consola, siga estos pasos:

Para activar el seguimiento activo

1. Abra la página de Functions (Funciones) en la consola de Lambda.

2. Elija una función.

3. Elija Configuration (Configuración), y luego Monitoring and operations tools (Herramientas de supervisión y operaciones).

4. Elija Edit (Editar).

5. En X-Ray, active Active tracing (Rastreo activo).

6. Seleccione Save.

Activación del seguimiento con la API de Lambda

Configure el rastreo en la función Lambda con AWS CLI o SDK de AWS, utilice las siguientes operaciones de API:

• UpdateFunctionConfiguration

• GetFunctionConfiguration

• CreateFunction

El siguiente comando de ejemplo de la AWS CLI habilita el seguimiento activo en una función llamada my-function.

aws lambda update-function-configuration --function-name my-function \
--tracing-config Mode=Active

El modo de seguimiento forma parte de la configuración específica de la versión, cuando se publica una versión de la función. No se puede cambiar el modo de seguimiento de una versión publicada.

Activación del seguimiento con AWS CloudFormation

Para activar el seguimiento en un recurso de AWS::Lambda::Function de una plantilla de AWS CloudFormation, utilice la propiedad TracingConfig.

ejemplo función-inline.yml: configuración de rastreo

Resources:
  function:
    Type: AWS::Lambda::Function
    Properties:
      TracingConfig:
        Mode: Active
      ...

Para un recurso AWS::Serverless::Function de AWS Serverless Application Model (AWS SAM) , utilice la propiedad Tracing.

ejemplo template.yml: configuración de rastreo

Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Tracing: Active
      ...

Interpretación de un seguimiento de X-Ray

Su función necesita permiso para cargar datos de rastreo en X-Ray. Cuando activa el rastreo activo en la consola de Lambda, Lambda agrega los permisos necesarios al rol de ejecución de la función. De lo contrario, agregue la política AWSXRayDaemonWriteAccess al rol de ejecución.

Después de configurar el seguimiento activo, se pueden observar solicitudes específicas a través de la aplicación. El gráfico de servicios de X-Ray muestra información sobre la aplicación y todos sus componentes. En el siguiente ejemplo de la aplicación de ejemplo de procesamiento de errores se muestra una aplicación con dos funciones. La función principal procesa eventos y, a veces, devuelve errores. La segunda función de la cadena procesa los errores que aparecen en el primer grupo de registros y utiliza el SDK de AWS para llamar a X-Ray, Amazon Simple Storage Service (Amazon S3) y registros de Amazon CloudWatch.

X-Ray no sigue todas las solicitudes realizadas a la aplicación. X-Ray aplica un algoritmo de muestreo para garantizar que el seguimiento sea eficiente, a la vez que sigue proporcionando una muestra representativa de todas las solicitudes. La tasa de muestreo es 1 solicitud por segundo y un 5 por ciento de las solicitudes adicionales.

nota

La frecuencia de muestreo de X-Ray no se puede configurar para las funciones.

Cuando se usa seguimiento activo, Lambda registra dos segmentos por seguimiento, lo que crea dos nodos en el gráfico de servicios. En la siguiente imagen, se resaltan los dos nodos para la función principal de la aplicación de ejemplo del procesador de errores.

El primer nodo, situado a la izquierda, representa el servicio de Lambda, que recibe la solicitud de invocación. El segundo nodo representa la función Lambda específica. En el siguiente ejemplo, se muestra un seguimiento con estos dos segmentos. Ambos se denominan my-function, pero uno tiene un origen de AWS::Lambda y el otro tiene origen de AWS::Lambda::Function.

En este ejemplo, el segmento de la función aparece ampliado para mostrar sus subsegmentos:

• Inicialización: representa el tiempo dedicado a cargar la función y ejecutar el código de inicialización. Este subsegmento aparece únicamente para el primer evento que procesa cada instancia de la función.

• Invocación: representa el tiempo dedicado a ejecutar el código del controlador.

• Sobrecarga: representa el tiempo que el tiempo de ejecución de Lambda dedica a prepararse para gestionar el siguiente evento.

También puede instrumentar clientes HTTP, registrar consultas SQL y crear subsegmentos personalizados con anotaciones y metadatos. Para obtener más información, consulte AWS X-Ray SDK para Java en la Guía para desarrolladores de AWS X-Ray.

Precios

Puede utilizar el seguimiento de X-Ray de manera gratuita cada mes hasta un límite determinado como parte del nivel Gratuito de AWS. A partir de ese umbral, X-Ray realiza cargos por almacenamiento y recuperación del seguimiento. Para obtener más información, consulte Precios de AWS X-Ray.

Almacenamiento de dependencias de tiempo de ejecución en una capa (X-Ray SDK)

Si utiliza el X-Ray SDK para instrumentar el código de las funciones de los clientes del SDK de AWS, el paquete de implementación puede llegar a ser bastante grande. Para evitar que se carguen dependencias en tiempo de ejecución cada vez que se actualice el código de las funciones, empaquete el X-Ray SDK en una capa de Lambda.

En el siguiente ejemplo, se muestra un recurso de AWS::Serverless::LayerVersion que almacena el AWS SDK for Java y el X-Ray SDK.

ejemplo template.yml: capa de dependencias.

Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: build/distributions/blank-java.zip
      Tracing: Active
      Layers:
        - !Ref libs
      ...
  libs:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: blank-java-lib
      Description: Dependencies for the blank-java sample app.
      ContentUri: build/blank-java-lib.zip
      CompatibleRuntimes:
        - java8

Con esta configuración, solo se actualiza la capa de la biblioteca si se modifican las dependencias del tiempo de ejecución. Dado que el paquete de implementación de la función contiene únicamente el código, esto puede ayudar a reducir los tiempos de carga.

Para crear una capa de dependencias, es necesario realizar cambios en la configuración de compilación para generar el archivo de capas antes de la implementación. Para ver un ejemplo práctico, consulte la aplicación de ejemplo java-basic en GitHub.

Seguimiento de X-Ray en aplicaciones de ejemplo (X-Ray SDK)

En el repositorio de GitHub correspondiente a esta guía hay aplicaciones de ejemplo que muestran cómo utilizar el seguimiento de X-Ray. Cada una de las aplicaciones de ejemplo contiene scripts para facilitar la implementación y la limpieza, una plantilla de AWS SAM y recursos de soporte.

Aplicaciones de Lambda de ejemplo en Java

• java-basic: una colección de funciones Java mínimas con pruebas unitarias y configuración de registro variable.

• java-events: una colección de funciones Java que contiene un código básico sobre cómo gestionar los eventos de varios servicios, como Amazon API Gateway, Amazon SQS y Amazon Kinesis. Estas funciones utilizan la última versión de la biblioteca aws-lambda-java-events (3.0.0 y más recientes). Estos ejemplos no requieren utilizar AWS SDK como una dependencia.

• s3-java: una función de Java que procesa los eventos de notificación de Amazon S3 y utiliza Java Class Library (JCL) para crear miniaturas de los archivos de imagen cargados.

• Uso de API Gateway para invocar una función de Lambda: una función Java que escanea una tabla de Amazon DynamoDB que contiene información sobre los empleados. Luego, utiliza Amazon Simple Notification Service para enviar un mensaje de texto a los empleados que celebran sus aniversarios laborales. En este ejemplo, se utiliza API Gateway para invocar la función.

Todas las aplicaciones de ejemplo tienen activado el seguimiento activo de las funciones de Lambda. Por ejemplo, en la aplicación s3-java, se muestra la instrumentación automática de los clientes de AWS SDK for Java 2.x, la administración de segmentos para pruebas, subsegmentos personalizados y el uso de capas de Lambda para almacenar dependencias en tiempo de ejecución.