Configuración de controles de registro avanzados para las funciones de Lambda

Para tener más control sobre cómo se registran, procesan y consumen los registros de sus funciones, Lambda ofrece las siguientes opciones de configuración del registro:

Para obtener más información sobre la configuración de los controles de registro avanzados, consulte las siguientes secciones:

Configuración de los formatos de registro JSON y de texto sin formato

Al capturar las salidas del registro como pares clave-valor JSON, resulta más fácil buscar y filtrar resultados cuando se depuran las funciones. Con los registros con formato JSON, también puede agregar etiquetas e información contextual a sus registros. Esto puede ayudarlo a realizar un análisis automatizado de grandes volúmenes de datos de registro. A menos que su flujo de trabajo de desarrollo se base en herramientas existentes que consumen registros de Lambda con texto sin formato, le recomendamos que seleccione JSON como formato de registro.

Para todos los tiempos de ejecución administrados por Lambda, puede elegir si los registros del sistema de su función se deben enviar a Registros de Amazon CloudWatch en texto sin formato o formato JSON no estructurado. Los registros del sistema son los registros que Lambda genera y, a veces, se conocen como registros de eventos de plataforma.

En el caso de los tiempos de ejecución compatibles, cuando se utiliza uno de los métodos de registro integrados compatibles, Lambda también puede generar los registros de aplicación de la función (los registros que genera el código de la función) en formato JSON estructurado. Al configurar el formato de registro de la función para estos tiempos de ejecución, la configuración que elija se aplicará tanto a los registros del sistema como de la aplicación.

Para los tiempos de ejecución compatibles, si su función utiliza una biblioteca o un método de registro compatibles, no necesita realizar ningún cambio en el código existente para que Lambda capture los registros en formato JSON estructurado.

Tiempos de ejecución y métodos de registro compatibles

Actualmente, Lambda admite la opción de generar registros de aplicaciones en formato JSON estructurado para los siguientes tiempos de ejecución.

Para que Lambda envíe los registros de aplicación de la función a CloudWatch en formato JSON estructurado, la función debe utilizar las siguientes herramientas de registro integradas para generar los registros:

Para obtener más información sobre el uso de controles de registro avanzados con tiempos de ejecución compatibles, consulte Registro y supervisión de las funciones de Lambda de Java, Registro y supervisión de las funciones de Lambda de Node.js y Registro y supervisión de las funciones de Lambda de Python.

Para otros tiempos de ejecución de Lambda administrados, Lambda actualmente solo admite de forma nativa la captura de registros del sistema en formato JSON estructurado. Sin embargo, puede seguir capturando los registros de aplicaciones en formato JSON estructurado en cualquier tiempo de ejecución con herramientas de registro, como Powertools para AWS Lambda, que generan salidas de registro con formato JSON.

Formatos de registro predeterminados

Actualmente, el formato de registro predeterminado para todos los tiempos de ejecución de Lambda es texto sin formato.

Si ya utiliza bibliotecas de registro, como Powertools para AWS Lambda, para generar los registros de funciones en formato JSON estructurado, no necesita cambiar el código si selecciona el formato de registro JSON. Lambda no codifica dos veces ningún registro que ya esté codificado en JSON, por lo que los registros de la aplicación de su función seguirán capturándose como antes.

Formato JSON para registros del sistema

Al configurar el formato de registro de la función como JSON, se captura cada elemento de registro del sistema (evento de plataforma) como un objeto JSON que contiene pares clave-valor con las siguientes claves:

El formato del valor "record" varía según el tipo de evento que se registre. Para obtener más información, consulte Tipos de objetos Event de la API de telemetría. Para obtener más información sobre los niveles de registro asignados a los eventos de registro del sistema, consulte Asignación de eventos a nivel de registro del sistema.

A modo de comparación, los dos ejemplos siguientes muestran la misma salida de registro en formato JSON estructurado y de texto sin formato. Tenga en cuenta que, en la mayoría de los casos, los eventos de registro del sistema contienen más información cuando se generan con formato JSON que cuando se generan con texto sin formato.

2023-03-13 18:56:24.046000 fbe8c1   INIT_START  Runtime Version: python:3.9.v18  Runtime Version ARN: arn:aws:lambda:eu-west-1::runtime:edb5a058bfa782cb9cedc6d534ac8b8c193bc28e9a9879d9f5ebaaf619cd0fc0

{
  "time": "2023-03-13T18:56:24.046Z",
  "type": "platform.initStart",
  "record": {
    "initializationType": "on-demand",
    "phase": "init",
    "runtimeVersion": "python:3.9.v18",
    "runtimeVersionArn": "arn:aws:lambda:eu-west-1::runtime:edb5a058bfa782cb9cedc6d534ac8b8c193bc28e9a9879d9f5ebaaf619cd0fc0"
  }
}

Formato JSON para registros de aplicaciones

Al configurar el formato de registro de la función como JSON, las salidas del registro de aplicación escritas con las bibliotecas y los métodos de registro compatibles se capturan como un objeto JSON que contiene pares de clave-valor con las siguientes claves:

Según el tiempo de ejecución y el método de registro que utilice la función, este objeto JSON también puede contener pares de claves adicionales. Por ejemplo, en Node.js, si la función utiliza métodos console para registrar objetos de error con varios argumentos, el objeto JSON contendrá pares de clave-valor adicionales junto con las claves errorMessage, errorType, ystackTrace. Para obtener más información sobre los registros con formato JSON en diferentes tiempos de ejecución de Lambda, consulte Registro y supervisión de las funciones de Lambda de Python, Registro y supervisión de las funciones de Lambda de Node.js, y Registro y supervisión de las funciones de Lambda de Java.

A modo de comparación, los dos ejemplos siguientes muestran la misma salida de registro en formato JSON estructurado y de texto sin formato.

2023-10-27T19:17:45.586Z 79b4f56e-95b1-4643-9700-2807f4e68189 INFO some log message

{
    "timestamp":"2023-10-27T19:17:45.586Z",
    "level":"INFO",
    "message":"some log message",
    "requestId":"79b4f56e-95b1-4643-9700-2807f4e68189"
}

Configuración del formato de registro de su función

Para configurar el formato de registro de la función, puede utilizar la consola de Lambda o la AWS Command Line Interface (AWS CLI). También puede configurar el formato de registro de una función mediante los comandos de la API de Lambda CreateFunction y UpdateFunctionConfiguration, el recurso de AWS Serverless Application Model (AWS SAM) AWS::Serverless::Function y el recurso de AWS CloudFormation AWS::Lambda::Function.

Cambiar el formato de registro de la función no afecta a los registros existentes almacenados en Registros de Amazon CloudWatch. Solo los registros nuevos utilizarán el formato actualizado.

Si cambia el formato de registro de la función a JSON y no establece el nivel de registro, Lambda establece automáticamente el nivel de registro de la aplicación y el nivel de registro del sistema de la función en INFO. Esto significa que Lambda envía a Registros de CloudWatch solo las salidas de registro de nivel INFO e inferiores. Para obtener más información sobre el filtrado a nivel de registro de aplicaciones y sistemas, consulte Filtrado a nivel de registro.

En el caso de las funciones de Node.js que emiten registros en formato de métricas integradas (EMF), cambiar el formato de registro de la función a JSON podría provocar que CloudWatch no reconozca las métricas.

Filtrado a nivel de registro

Lambda puede filtrar los registros de su función para que solo se envíen a Registros de Amazon CloudWatch los registros con un nivel de detalle determinado o inferior. Puede configurar el filtrado a nivel de registro por separado para los registros del sistema de la función (los registros que Lambda genera) y los registros de la aplicación (los registros que genera el código de la función).

Para Tiempos de ejecución y métodos de registro compatibles, no necesita realizar ningún cambio en el código de la función para que Lambda filtre los registros de aplicación de su función.

Para todos los demás tiempos de ejecución y métodos de registro, el código de la función debe generar los eventos de registro en stdout o stderr como objetos con formato JSON que contengan un par clave-valor con la clave "level". Por ejemplo, Lambda interpreta la siguiente salida de stdout como un registro de nivel DEBUG.

print('{"level": "debug", "msg": "my debug log", "timestamp": "2023-11-02T16:51:31.587199Z"}')

Si el campo de valor "level" no es válido o falta, Lambda asignará a la salida del registro el nivel INFO. Para que Lambda utilice el campo de marca de tiempo, debe especificar el tiempo con un formato de marca de tiempo RFC 3339 válido. Si no proporciona una marca de tiempo válida, Lambda asignará al registro el nivel INFO y agregará una marca de tiempo por usted.

Cuando asigne un nombre a la clave de marca de tiempo, siga las convenciones del tiempo de ejecución que esté utilizando. Lambda admite la mayoría de las convenciones de nomenclatura habituales que utilizan los tiempos de ejecución administrados. Por ejemplo, en las funciones que utilizan el tiempo de ejecución .NET, Lambda reconoce la clave "Timestamp".

Para los registros de aplicaciones (los registros generados por el código de la función), puede elegir entre los siguientes niveles de registro.

Al seleccionar un nivel de registro, Lambda envía los registros de ese nivel y de niveles inferiores a Registros de Amazon CloudWatch. Por ejemplo, si establece el nivel de registro de la aplicación de una función en WARN, Lambda no envía las salidas de registro en los niveles INFO y DEBUG. El nivel de registro de aplicaciones predeterminado para el filtrado de registros es INFO.

Cuando Lambda filtra los registros de aplicaciones de la función, a los mensajes de registro sin nivel se les asignará el nivel de registro INFO.

Para los registros del sistema (los registros generados por el servicio Lambda), puede elegir entre los siguientes niveles de registro.

Al seleccionar un nivel de registro, Lambda envía los registros a ese nivel y a niveles inferiores. Por ejemplo, si establece el nivel de registro del sistema de una función en INFO, Lambda no envía las salidas de registro en el nivel DEBUG.

De forma predeterminada, Lambda establece el nivel de registro del sistema en INFO. Con esta configuración, Lambda envía los mensajes de registro "start" y "report" a CloudWatch automáticamente. Para recibir registros del sistema más o menos detallados, cambie el nivel de registro a DEBUG o WARN. Para ver una lista de los niveles de registro a los que Lambda asigna diferentes eventos de registro del sistema, consulte Asignación de eventos a nivel de registro del sistema.

Configuración del filtrado a nivel de registro

Para configurar el filtrado a nivel de registro de aplicaciones y sistemas para su función, puede utilizar la consola de Lambda o la AWS Command Line Interface (AWS CLI). También puede configurar el nivel de registro de una función con los comandos de la API de Lambda CreateFunction y UpdateFunctionConfiguration, el recurso de AWS Serverless Application Model (AWS SAM) AWS::Serverless::Function y el recurso de AWS CloudFormation AWS::Lambda::Function.

Tenga en cuenta que si establece el nivel de registro de la función en el código, esta configuración tiene prioridad sobre cualquier otra configuración a nivel de registro que configure. Por ejemplo, si usa el método setLevel() de logging de Python para establecer el nivel de registro de la función en INFO, esta configuración tiene prioridad sobre la configuración WARN que configure mediante la consola de Lambda.

Asignación de eventos a nivel de registro del sistema

Para los eventos de registro a nivel de sistema generados por Lambda, la siguiente tabla define el nivel de registro asignado a cada evento. Para obtener más información sobre los eventos que figuran en la tabla, consulte Referencia del esquema Event de la API de telemetría de Lambda.

Filtrado a nivel de registro de aplicaciones con tiempos de ejecución personalizados

Al configurar el filtrado a nivel de registro de aplicaciones para su función, en segundo plano, Lambda establece el nivel de registro de la aplicación en el tiempo de ejecución mediante la variable de entorno AWS_LAMBDA_LOG_LEVEL. Lambda también establece el formato de registro de la función mediante la variable de entorno AWS_LAMBDA_LOG_FORMAT. Puede utilizar estas variables para integrar los controles de registro avanzados de Lambda en un tiempo de ejecución personalizado.

Para poder configurar los ajustes de registro de una función mediante un tiempo de ejecución personalizado con la consola de Lambda, AWS CLI y las API de Lambda, configure el tiempo de ejecución personalizado para comprobar el valor de estas variables de entorno. A continuación, puede configurar los registradores de su tiempo de ejecución de acuerdo con el formato y los niveles de registro que seleccione.

Configuración de grupos de registros de CloudWatch

De forma predeterminada, CloudWatch crea automáticamente un grupo de registro denominado /aws/lambda/<function name> para la función cuando se invoca por primera vez. Para configurar su función de manera que envíe registros a un grupo de registro existente o para crear un nuevo grupo de registro para su función, puede usar la consola de Lambda o la AWS CLI. También puede configurar grupos de registros personalizados con los comandos de la API de Lambda CreateFunction y UpdateFunctionConfiguration, y el recurso de AWS Serverless Application Model (AWS SAM) AWS::Serverless::Function.

Puede configurar varias funciones de Lambda para enviar registros al mismo grupo de registro de CloudWatch. Por ejemplo, puede usar un único grupo de registro para almacenar los registros de todas las funciones de Lambda que componen una aplicación concreta. Cuando se utiliza un grupo de registro personalizado para una función de Lambda, los flujos de registro que Lambda crea incluyen el nombre y la versión de la función. Esto garantiza que se conserve la asignación entre los mensajes de registro y las funciones, incluso si utiliza el mismo grupo de registro para varias funciones.

El formato de denominación del flujo de registro para grupos de registro personalizados sigue esta convención:

YYYY/MM/DD/<function_name>[<function_version>][<execution_environment_GUID>]

Tenga en cuenta que, al configurar un grupo de registro personalizado, el nombre que seleccione para el grupo de registro debe seguir las reglas de nomenclatura de Registros de Amazon CloudWatch. Además, los nombres personalizados de los grupos de registros no deben empezar por la cadena aws/. Si crea un grupo de registros personalizado empezando por aws/, Lambda no podrá crear el grupo de registros. Como resultado, los registros de la función no se enviarán a CloudWatch.

Permisos de rol de ejecución

Para que su función envíe registros a Registros de Amazon CloudWatch, debe tener el permiso logs:PutLogEvents. Al configurar el grupo de registro de la función con la consola de Lambda, si la función no tiene este permiso, Lambda lo agrega al rol de ejecución de la función de forma predeterminada. Cuando Lambda agrega este permiso, otorga a la función permiso para enviar registros a cualquier grupo de registro de Registros de Amazon CloudWatch.

Para evitar que Lambda actualice automáticamente el rol de ejecución de la función y, en su lugar, lo edite manualmente, expanda Permisos y deje la opción Agregar permisos necesarios sin marcar.

Al configurar el grupo de registro de la función con la AWS CLI, Lambda no agregará el permiso logs:PutLogEvents automáticamente. Agregue el permiso al rol de ejecución de su función si aún no lo tiene. Este permiso se incluye en la política administrada AWSLambdaBasicExecutionRole.