Registro y supervisión de las funciones de Lambda de C#

AWS Lambda supervisa de forma automática funciones de Lambda y envía entradas de registros a Amazon CloudWatch. Su función de Lambda viene con un grupo de registros de Registros de CloudWatch y con un flujo de registro para cada instancia de su función. El entorno de tiempo de ejecución de Lambda envía detalles sobre cada invocación y otros resultados del código de su función al flujo de registro. Para obtener más información acerca de Registros de CloudWatch, consulte Uso de los Registros de CloudWatch con Lambda.

Crear una función que devuelve registros

Para generar registros desde el código de su función, puede utilizar el ILambdaLogger en el objeto de contexto, los métodos de la Clase de consola, o cualquier biblioteca de registro que escriba en stdout o stderr.

El tiempo de ejecución de .NET registra las líneas START, END y REPORT de cada invocación. La línea del informe proporciona los siguientes detalles.

Uso de los controles de registro avanzados de Lambda con .NET

Para tener más control sobre cómo se registran, procesan y consumen los registros de las funciones, puede configurar las siguientes opciones de registro para los tiempos de ejecución de .NET admitidos:

Para obtener más información sobre estas opciones de registro e instrucciones sobre cómo configurar la función para utilizarlas, consulte Configuración de controles de registro avanzados para las funciones de Lambda.

Para usar las opciones de formato y nivel de registro con las funciones de Lambda de .NET, consulte las instrucciones de las siguientes secciones.

Uso del formato de registro JSON estructurado con .NET

Si selecciona JSON para el formato de registro de la función, Lambda enviará los registros de salida mediante ILambdaLogger como JSON estructurado. Cada objeto de registro JSON contiene, por lo menos, cinco pares clave-valor con las siguientes claves:

La instancia ILambdaLogger puede agregar pares clave-valor adicionales, por ejemplo, al registrar excepciones. También puede proporcionar sus propios parámetros adicionales, tal y como se describe en la sección Parámetros de registro proporcionados por el cliente.

En el siguiente ejemplo de comando de registro, se muestra cómo escribir un mensaje de registro con el nivel INFO.

context.Logger.LogInformation("Fetching cart from database");

También puede utilizar un método de registro genérico que tome el nivel de registro como argumento, como se muestra en el siguiente ejemplo.

context.Logger.Log(LogLevel.Information, "Fetching cart from database");

La salida del registro generada por estos fragmentos de código de ejemplo se capturaría en Registros de CloudWatch de la siguiente manera:

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Information",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "Fetching cart from database"
}

Si no asigna un nivel a la salida del registro, Lambda asignará el nivel INFO automáticamente.

Registro de excepciones en JSON

Si utiliza el registro JSON estructurado con ILambdaLogger, puede registrar las excepciones en su código, como se muestra en el siguiente ejemplo.

try
{
    connection.ExecuteQuery(query);
}
catch(Exception e)
{
    context.Logger.LogWarning(e, "Error executing query");
}

El resultado en formato de registro de este código se muestra en el ejemplo siguiente de JSON. Tenga en cuenta que la propiedad message de JSON se rellena con el argumento message proporcionado en la llamada LogWarning, mientras que la propiedad errorMessage proviene de la propiedad Message de la propia excepción.

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Warning",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "Error executing query",
    "errorType": "System.Data.SqlClient.SqlException",
    "errorMessage": "Connection closed",
    "stackTrace": ["<call exception.StackTrace>"]
}

Si el formato de registro de la función está establecido en JSON, Lambda también genera mensajes de registro con formato JSON cuando el código arroja una excepción no detectada. En el siguiente ejemplo, el fragmento de código y el mensaje de registro muestran cómo se registran las excepciones no detectadas.

throw new ApplicationException("Invalid data");

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Error",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "Invalid data",
    "errorType": "System.ApplicationException",
    "errorMessage": "Invalid data",
    "stackTrace": ["<call exception.StackTrace>"]
}

Parámetros de registro proporcionados por el cliente

Con los mensajes de registro con formato JSON, puede proporcionar parámetros de registro adicionales e incluirlos en el registro message. En el siguiente ejemplo de fragmento de código, se muestra un comando para agregar dos parámetros proporcionados por el usuario denominados retryAttempt y uri. En el ejemplo, el valor de estos parámetros proviene de los argumentos retryAttempt y uriDestination transferidos al comando logging.

context.Logger.LogInformation("Starting retry {retryAttempt} to make GET request to {uri}", retryAttempt, uriDestination);

El resultado del mensaje de registro de este comando se muestra en el ejemplo siguiente de JSON.

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Information",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "Starting retry 1 to make GET request to http://example.com/",
    "retryAttempt": 1,
    "uri": "http://example.com/"
}

context.Logger.LogInformation("Starting retry {0} to make GET request to {1}", retryAttempt, uriDestination);

Tenga en cuenta que cuando suministra parámetros adicionales de registro, Lambda los captura como propiedades de nivel superior en el registro de registros en JSON. Este enfoque difiere de algunas bibliotecas populares de registro en .NET, como Serilog, que captura parámetros adicionales en un objeto secundario separado.

Si el argumento que proporciona para un parámetro adicional es un objeto complejo, Lambda utilizará el método ToString() de forma predeterminada para proporcionar el valor. Para indicar que un argumento debe estar serializado en JSON, utilice el prefijo @ como se muestra en el siguiente fragmento de código. En este ejemplo, User es un objeto con propiedades FirstName y LastName.

context.Logger.LogInformation("User {@user} logged in", User);

El resultado del mensaje de registro de este comando se muestra en el ejemplo siguiente de JSON.

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Information",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "User {@user} logged in",
    "user": 
    {
        "FirstName": "John",
        "LastName": "Doe"
    }
}

Si el argumento de un parámetro adicional es una matriz o implementa IList o IDictionary, Lambda agrega el argumento al mensaje de registro JSON como una matriz, como se muestra en el siguiente ejemplo de registro JSON. En este ejemplo, {users} toma un argumento IList que contiene instancias de la propiedad User con el mismo formato que en el ejemplo anterior. Lambda convierte a IList en una matriz y cada valor se crea mediante el método ToString.

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Information",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "{users} have joined the group",
    "users": 
    [
        "Rosalez, Alejandro",
        "Stiles, John"       
    ] 
}

También puede serializar la lista en JSON mediante el prefijo @ del comando de registro. En el siguiente ejemplo de registro JSON, la propiedad users está serializada en JSON.

{
    "timestamp": "2023-09-07T01:30:06.977Z",
    "level": "Information",
    "requestId": "8f711428-7e55-46f9-ae88-2a65d4f85fc5",
    "traceId": "1-6408af34-50f56f5b5677a7d763973804",
    "message": "{@users} have joined the group",
    "users": 
    [
        {
            "FirstName": "Alejandro",
            "LastName": "Rosalez"
        },
        {
            "FirstName": "John",
            "LastName": "Stiles"
        }        
    ] 
}

Uso del filtrado de registros con .NET

Al configurar el filtrado de registros, puede elegir enviar solo los registros de un nivel de detalle específico o inferior a los Registros de CloudWatch. Para obtener información sobre cómo configurar el filtrado a nivel de registro para su función, consulte Filtrado a nivel de registro.

Para que AWS Lambda filtre los mensajes de registro por nivel de registro, puede usar registros con formato JSON o usar los métodos. NET Console para generar mensajes de registro. Para crear registros con formato JSON, configure el tipo de registro de su función en JSON y use la instancia ILambdaLogger.

Con los registros en formato JSON, Lambda filtra sus salidas de registro mediante el par clave-valor “level” en el objeto JSON descrito en Uso del formato de registro JSON estructurado con .NET.

Si utiliza los métodos .NET Console para escribir mensajes en los Registros de CloudWatch, Lambda aplicará los siguientes niveles de registro a los mensajes:

Cuando configura la función para que utilice el filtrado a nivel de registro, debe seleccionar una de las siguientes opciones para el nivel de registros que desea que Lambda envíe a los Registros de CloudWatch. Observe la asignación de los niveles de registro utilizados por Lambda con los niveles estándar de Microsoft utilizados por .NET ILambdaLogger.

Lambda envía los registros del nivel de detalle seleccionado e inferior a CloudWatch. Por ejemplo, si configura un nivel de registro de WARN, Lambda enviará los registros correspondientes a los niveles WARN, ERROR y FATAL.

Herramientas y bibliotecas de registro adicionales

Powertools para AWS Lambda (.NET) es un kit de herramientas para desarrolladores destinado a implementar prácticas recomendadas sin servidor y aumentar la velocidad de los desarrolladores. La utilidad de registro proporciona un logger optimizado para Lambda que incluye información adicional sobre el contexto de la función en todas las funciones con un resultado estructurado como JSON. Utilice esta utilidad para hacer lo siguiente:

Uso de Powertools para AWS Lambda (.NET) y AWS SAM para el registro estructurado

Siga los pasos que figuran a continuación para descargar, crear e implementar una aplicación de muestra “Hola, mundo” de C# con módulos de Powertools para AWS Lambda (.NET) integrados mediante AWS SAM. Esta aplicación implementa un backend de API básico y utiliza Powertools para emitir registros, métricas y seguimiento. Consta de un punto de conexión de Amazon API Gateway y una función de Lambda. Cuando se envía una solicitud GET al punto de conexión de API Gateway, la función de Lambda se invoca, envía registros y métricas a CloudWatch mediante Embedded Metric Format y envía seguimiento a AWS X-Ray. La función devuelve el mensaje hello world.

Administración de retención de registros

Los grupos de registro no se eliminan automáticamente cuando se elimina una función. Para evitar almacenar registros de forma indefinida, elimine el grupo de registros o configure un periodo de retención después del cual CloudWatch los eliminará de forma automática. Para configurar la retención de registros, agregue lo siguiente a la plantilla de AWS SAM:

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      # Omitting other properties

  LogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: !Sub "/aws/lambda/${HelloWorldFunction}"
      RetentionInDays: 7

Visualización de los registros en la consola de Lambda

Puede utilizar la consola de Lambda para ver la salida del registro después de invocar una función de Lambda.

Si su código se puede probar desde el editor de código integrado, encontrará los registros en los resultados de ejecución. Cuando utilice la característica de prueba de la consola para invocar una función, encontrará la Salida de registro en la sección de Detalles.

Visualización de los registros de en la consola de CloudWatch

Puede utilizar la consola Amazon CloudWatch para ver los registros de todas las invocaciones de funciones de Lambda.

Cada flujo de registro se corresponde con una instancia de su función. Aparece un flujo de registro cuando actualiza la función de Lambda y cuando se crean instancias adicionales para manejar varias invocaciones simultáneas. Para encontrar registros para una invocación específica, le recomendamos que interfiera su función con AWS X-Ray. X-Ray registra los detalles sobre la solicitud y el flujo de registro en el seguimiento.

Visualización de los registros mediante la AWS Command Line Interface (AWS CLI)

La AWS CLI es una herramienta de código abierto que lo habilita para interactuar con los servicios de AWS mediante el uso de comandos en el intérprete de comandos de la línea de comandos. Para completar los pasos de esta sección, debe disponer de la versión 2 de la AWS CLI.

Puede utilizar la CLI de AWS CLI para recuperar registros de una invocación mediante la opción de comando --log-type. La respuesta contiene un campo LogResult que contiene hasta 4 KB de registros con codificación base64 a partir de la invocación.

aws lambda invoke --function-name my-function out --log-type Tail

{
    "StatusCode": 200,
    "LogResult": "U1RBUlQgUmVxdWVzdElkOiA4N2QwNDRiOC1mMTU0LTExZTgtOGNkYS0yOTc0YzVlNGZiMjEgVmVyc2lvb...",
    "ExecutedVersion": "$LATEST"
}

aws lambda invoke --function-name my-function out --log-type Tail \
--query 'LogResult' --output text --cli-binary-format raw-in-base64-out | base64 --decode

START RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8 Version: $LATEST
"AWS_SESSION_TOKEN": "AgoJb3JpZ2luX2VjELj...", "_X_AMZN_TRACE_ID": "Root=1-5d02e5ca-f5792818b6fe8368e5b51d50;Parent=191db58857df8395;Sampled=0"",ask/lib:/opt/lib",
END RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8
REPORT RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8  Duration: 79.67 ms      Billed Duration: 80 ms         Memory Size: 128 MB     Max Memory Used: 73 MB

#!/bin/bash
aws lambda invoke --function-name my-function --cli-binary-format raw-in-base64-out --payload '{"key": "value"}' out
sed -i'' -e 's/"//g' out
sleep 15
aws logs get-log-events --log-group-name /aws/lambda/my-function --log-stream-name stream1 --limit 5

chmod -R 755 get-logs.sh

./get-logs.sh

{
    "StatusCode": 200,
    "ExecutedVersion": "$LATEST"
}
{
    "events": [
        {
            "timestamp": 1559763003171,
            "message": "START RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf Version: $LATEST\n",
            "ingestionTime": 1559763003309
        },
        {
            "timestamp": 1559763003173,
            "message": "2019-06-05T19:30:03.173Z\t4ce9340a-b765-490f-ad8a-02ab3415e2bf\tINFO\tENVIRONMENT VARIABLES\r{\r  \"AWS_LAMBDA_FUNCTION_VERSION\": \"$LATEST\",\r ...",
            "ingestionTime": 1559763018353
        },
        {
            "timestamp": 1559763003173,
            "message": "2019-06-05T19:30:03.173Z\t4ce9340a-b765-490f-ad8a-02ab3415e2bf\tINFO\tEVENT\r{\r  \"key\": \"value\"\r}\n",
            "ingestionTime": 1559763018353
        },
        {
            "timestamp": 1559763003218,
            "message": "END RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf\n",
            "ingestionTime": 1559763018353
        },
        {
            "timestamp": 1559763003218,
            "message": "REPORT RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf\tDuration: 26.73 ms\tBilled Duration: 27 ms \tMemory Size: 128 MB\tMax Memory Used: 75 MB\t\n",
            "ingestionTime": 1559763018353
        }
    ],
    "nextForwardToken": "f/34783877304859518393868359594929986069206639495374241795",
    "nextBackwardToken": "b/34783877303811383369537420289090800615709599058929582080"
}

Eliminación de registros

Los grupos de registro no se eliminan automáticamente cuando se elimina una función. Para evitar almacenar registros indefinidamente, elimine el grupo de registros o configure un periodo de retención después de lo cual los registros se eliminan automáticamente.