Registrar em log e monitorar funções do Lambda em C#

O AWS Lambda monitora automaticamente as funções do Lambda e envia entradas de logs para o Amazon CloudWatch. Sua função do Lambda vem com um grupo de logs do CloudWatch Logs e uma transmissão de logs para cada instância de sua função. O ambiente de runtime do Lambda envia detalhes sobre cada invocação e outras saídas do código da função para o fluxo de logs. Para obter mais informações sobre o CloudWatch Logs, consulte Uso do CloudWatch Logs com o Lambda.

Criar uma função que retorna logs

Para gerar os logs do código de função, você pode usar o ILambdaLogger no objeto de contexto, os métodos na classe Console ou qualquer biblioteca de logs que grave no stdout ou no stderr.

O runtime do .NET registra em log as linhas START, END e REPORT para cada invocação. A linha do relatório fornece os detalhes a seguir.

Uso de controles avançados de registro em log do Lambda com .NET

Para dar mais controle sobre como os logs das funções são capturados, processados e consumidos, você pode configurar as seguintes opções de log para runtimes compatíveis do .NET:

Para obter mais informações sobre essas opções de registro em log e instruções sobre como configurar a função para usá-las, consulte Configurar controles avançados de registro em log para funções do Lambda.

Para usar as opções de formato de log e nível de log com as funções do Lambda para .NET, consulte as orientações nas seções a seguir.

Uso de logs em formato JSON estruturado com .NET

Se você selecionar JSON para o formato de log da função, o Lambda enviará a saída de logs usando ILambdaLogger como JSON estruturado. Cada objeto de log JSON contém pelo menos cinco pares de valores-chave com as seguintes chaves:

A instância ILambdaLogger pode adicionar mais pares de valores-chave, por exemplo, ao gerar logs de exceções. Você também pode fornecer seus próprios parâmetros adicionais, conforme descrito na seção Parâmetros de log fornecidos pelo cliente.

O exemplo de comando de geração de log a seguir mostra como escrever uma mensagem de log com o nível INFO.

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

Você também pode usar um método de log genérico que usa o nível de log como argumento, conforme mostrado no exemplo a seguir.

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

A saída de log desse exemplo de trechos de código seria capturada no CloudWatch Logs da seguinte forma:

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

Se você não atribuir um nível à saída de log, o Lambda atribuirá automaticamente o nível INFO a ele.

Exceções de log em JSON

Ao usar a geração estruturada de logs JSON com ILambdaLogger, você pode registrar exceções em seu código, conforme mostrado no exemplo a seguir.

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

A saída do formato de log por esse código é mostrada no JSON de exemplo a seguir. Observe que a propriedade message no JSON é preenchida usando o argumento de mensagem fornecido na chamada LogWarning, enquanto a propriedade errorMessage vem da propriedade Message da própria exceção.

{
    "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>"]
}

Se o formato de log da sua função estiver definido como JSON, o Lambda também mostrará mensagens de log formatadas em JSON quando seu código gerar uma exceção não detectada. O exemplo de trecho de código e mensagem de log a seguir mostra como as exceções não detectadas são registradas em log.

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 log fornecidos pelo cliente

Com mensagens de log formatadas em JSON, você pode fornecer parâmetros adicionais de log e incluí-los no log message. O exemplo de trecho de código a seguir mostra um comando para adicionar dois parâmetros fornecidos pelo usuário com os rótulos retryAttempt e uri. No exemplo, o valor desses parâmetros vem dos argumentos retryAttempt e uriDestination passados para o comando de geração e log.

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

A saída da mensagem de log desse comando é mostrada no JSON de exemplo a seguir.

{
    "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);

Observe que, quando você fornece parâmetros adicionais de log, o Lambda os captura como propriedades de nível superior no registro de log JSON. Essa abordagem difere de algumas bibliotecas populares de logs .NET, como Serilog, que captura parâmetros adicionais em um objeto filho separado.

Se o argumento que você fornece para um parâmetro adicional for um objeto complexo, por padrão, o Lambda usa o método ToString() para fornecer o valor. Para indicar que um argumento deve ser um objeto serializado JSON, use o prefixo @ conforme mostrado no trecho de código a seguir. Neste exemplo, User é um objeto com as propriedades FirstName e LastName.

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

A saída da mensagem de log desse comando é mostrada no JSON de exemplo a seguir.

{
    "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"
    }
}

Se o argumento para um parâmetro adicional for uma matriz ou implementar IList ou IDictionary, o Lambda acrescentará o argumento à mensagem de log JSON como uma matriz, conforme mostrado no exemplo de registro de log JSON a seguir. Neste exemplo, {users} usa um argumento IList que contém instâncias da propriedade User com o mesmo formato do exemplo anterior. O Lambda converte IList em uma matriz, com cada valor sendo criado usando o 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"       
    ] 
}

Você também pode serializar a lista com JSON usando o prefixo @ em seu comando de geração de log. No exemplo de registro de log JSON a seguir, a propriedade users é serializada em 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 de filtragem em nível de log com .NET

Ao configurar a filtragem em nível de log, você pode optar por enviar somente logs de um determinado nível de detalhe, ou inferior, para o CloudWatch Logs. Para saber como configurar a filtragem em nível de log para a função, consulte Filtragem em nível de log.

Para o AWS Lambda filtrar suas mensagens de log por nível de log, você pode usar logs formatados em JSON ou usar os métodos .NET Console para gerar mensagens de log. Para criar logs no formato JSON, configure o tipo de log da sua função como JSON e use a instância ILambdaLogger.

Com logs formatados em JSON, o Lambda filtrará as saídas de log usando o par de valores-chave “nível” no objeto JSON descrito em Uso de logs em formato JSON estruturado com .NET.

Se você usa os métodos .NET Console para gravar mensagens no CloudWatch Logs, o Lambda aplica níveis de log às suas mensagens da seguinte forma:

Ao configurar sua função para usar a filtragem em nível de log, você precisa selecionar entre as seguintes opções para o nível de logs enviados pelo Lambda para o CloudWatch Logs. Observe o mapeamento dos níveis de log usados pelo Lambda com os níveis padrão da Microsoft usados pelo ILambdaLogger .NET.

O Lambda envia logs do nível de detalhe selecionado, e dos níveis inferiores, para o CloudWatch. Por exemplo, se você configurar um nível de log de WARN, o Lambda enviará logs correspondentes aos níveis WARN, ERROR e FATAL.

Outras ferramentas de geração de log e bibliotecas

O Powertools para AWS Lambda (.NET) é um kit de ferramentas para desenvolvedores para implementar práticas recomendadas de tecnologia sem servidor e aumentar a velocidade do desenvolvedor. O utilitário de logs fornece um registrador de logs otimizado para Lambda que inclui informações adicionais sobre o contexto da função em todas as suas funções, com saída estruturada como JSON. Use esse utilitário para fazer o seguinte:

Uso do Powertools para AWS Lambda (.NET) e do AWS SAM para registro em log estruturado

Siga as etapas abaixo para baixar, criar e implantar um exemplo de aplicação C# Hello World com os módulos integrados do Powertools para AWS Lambda (.NET) usando o AWS SAM. Esta aplicação implementa um backend de API básico e usa o Powertools para emitir logs, métricas e rastreamentos. Consiste em um endpoint do Amazon API Gateway e uma função do Lambda. Quando você envia uma solicitação GET ao endpoint do API Gateway, a função do Lambda invoca, envia logs e métricas usando o formato de métricas incorporadas ao CloudWatch e envia rastreamentos ao AWS X-Ray. A função retorna uma mensagem hello world.

Gerenciar a retenção de logs

Os grupos de logs não são excluídos automaticamente excluídos quando você exclui uma função. Para evitar armazenar logs por tempo indeterminado, exclua o grupo de logs ou configure um período de retenção após o qual o CloudWatch excluirá os logs automaticamente. Para configurar a retenção de logs, adicione o seguinte ao seu modelo do 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

Visualizar logs no console do Lambda

Você pode usar o console do Lambda para exibir a saída do log depois de invocar uma função do Lambda.

Se seu código puder ser testado no editor de Código incorporado, você encontrará logs nos resultados de execução. Ao usar o recurso de teste do console para invocar uma função, você encontrará Saída de log na seção Detalhes.

Visualização de logs no console do CloudWatch

Você pode usar o console do Amazon CloudWatch para exibir registros de todas as invocações da função do Lambda.

Cada fluxo de log corresponde a uma instância da sua função. Uma transmissão de logs é exibida quando você atualiza sua função do Lambda e quando mais instâncias são criadas para lidar com várias invocações simultâneas. Para localizar logs de uma invocação específica, recomendamos intrumentar sua função com AWS X-Ray. O X-Ray registra detalhes sobre a solicitação e o stream de logs no rastreamento.

Visualizar logs usando a AWS Command Line Interface (AWS CLI)

O AWS CLI é uma ferramenta de código aberto que permite interagir com os serviços do AWS usando comandos no shell da linha de comando. Para concluir as etapas desta seção, você deve ter a versão 2 da AWS CLI.

Você pode usar a AWS CLI para recuperar logs de uma invocação usando a opção de comando --log-type. A resposta contém um campo LogResult com até 4 KB de logs codificados em base64 obtidos da invocação.

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"
}

Excluir logs

Os grupos de logs não são excluídos automaticamente excluídos quando você exclui uma função. Para evitar armazenar logs indefinidamente, exclua o grupo de logs ouConfigurar um período de retençãoapós o qual os logs são excluídos automaticamente.