API Lambda Logs - AWS Lambda
Assinando para receber registrosUso de memóriaprotocolos de destinoConfiguração de bufferExemplo de assinaturaCódigo de exemplo para Logs APIReferência da API LogsMensagens de log

API Lambda Logs

Importante

A API de telemetria do Lambda substitui a API de logs do Lambda. Embora a API de logs permaneça totalmente funcional, recomendamos usar apenas a API de telemetria daqui para frente. É possível inscrever sua extensão em um fluxo de telemetria usando a API de telemetria ou a API de logs. Após se inscrever usando uma dessas APIs, qualquer tentativa de se inscrever usando a outra API retornará um erro.

O Lambda captura automaticamente os logs de tempo de execução e os transmite para o Amazon CloudWatch. Essa transmissão de log contém os logs que seu código de função e extensões geram, e também os gerados pelo Lambda como parte da chamada de função.

Extensões do Lambdapode usar a API RLambda time Logs para assinar fluxos de log diretamente do Lambdaambiente de execução. O Lambda transmite os logs para a extensão e a extensão pode processar, filtrar e enviar os logs para qualquer destino preferido.

A API Extensions e a API Logs conectam o Lambda e as extensões externas.

A API Logs permite que as extensões se inscrevam em três fluxos de logs diferentes:

  • Logs de função que a função do Lambda gera e grava em stdout ou stderr.

  • Registros de extensão que o código de extensão gera.

  • Logs da plataforma do Lambda que registram eventos e erros relacionados a invocações e extensões.

nota

O Lambda envia todos os logs para o CloudWatch, mesmo quando uma extensão se inscreve em uma ou mais transmissões de log.

Assinando para receber registros

Uma extensão do Lambda pode se inscrever para receber registros enviando uma solicitação de assinatura para a API Logs.

Para se inscrever para receber registros, você precisa do identificador de extensão (Lambda-Extension-Identifier). Primeiro registre a extensão para receber o identificador de extensão. Em seguida, inscreva-se na API Logs durante a inicialização. Após a conclusão da fase de inicialização, o Lambda não processa solicitações de assinatura.

nota

A assinatura da API de registros é idempotente. As solicitações de assinatura duplicadas não resultam em assinaturas duplicadas.

Uso de memória

O uso da memória aumenta linearmente à medida que o número de assinantes aumenta. As assinaturas consomem recursos de memória porque cada assinatura abre um novo buffer de memória para armazenar os logs. Para ajudar a otimizar o uso da memória, você pode ajustar a configuração de buffer. O uso da memória buffer conta para o consumo geral de memória no ambiente de execução.

protocolos de destino

Você pode escolher um dos seguintes protocolos para receber os logs:

  1. HTTP (recomendado): o Lambda entrega os logs a um endpoint HTTP local (http://sandbox.localdomain:${PORT}/${PATH}) como uma matriz de registros no formato JSON. O parâmetro $PATH é opcional. Observe que somente HTTP é suportado, não HTTPS. Você pode optar por receber registros através PUT ou POST.

  2. TCP: o Lambda entrega logs a uma porta TCP no formato JSON delimitado por nova linha (NDJSON).

Recomendamos usar HTTP em vez de TCP. Com o TCP, a plataforma do Lambda não reconhece que os logs são entregues à camada da aplicação. Portanto, você poderá perder os logs se a extensão falhar. O HTTP não compartilha essa limitação.

Também recomendamos configurar o ouvinte HTTP local ou a porta TCP antes de se inscrever para receber logs. Durante a configuração, observe o seguinte:

  • O Lambda envia logs somente para destinos que estão dentro do ambiente de execução.

  • O Lambda tenta novamente enviar os logs (com recuo) se não houver listener ou se a solicitação POST ou PUT resultar em erro. Se o assinante do log falhar, ele continuará a receber logs depois que o Lambda reiniciar o ambiente de execução.

  • Lambda reserva porto 9001. Não há outras restrições ou recomendações de número de porta.

Configuração de buffer

O Lambda pode armazenar logs de buffer e entregá-los ao assinante. Você pode configurar esse comportamento na solicitação de assinatura especificando os campos opcionais a seguir. Observe que o Lambda usa o valor padrão para qualquer campo que você não especificar.

  • timeoutMs: o tempo máximo (em milissegundos) para colocar um lote em buffer. Padrão: 1.000. Mínimo: 25. Máximo: 30.000.

  • maxBytes: o tamanho máximo (em bytes) dos logs para colocar em buffer na memória. Padrão: 262.144. Mínimo: 262.144. Máximo: 1.048.576.

  • maxItems: o número máximo de eventos a serem colocados em buffer na memória. Padrão: 10.000. Mínimo: 1.000. Máximo: 10.000.

Durante a configuração de buffer, observe os seguintes pontos:

  • O Lambda libera os logs se alguma das transmissões de entrada estiver fechada, por exemplo, se o tempo de execução falhar.

  • Cada assinante pode especificar uma configuração de buffer diferente durante a solicitação de assinatura.

  • Considere o tamanho do buffer que você precisa para ler os dados. Espere receber cargas úteis tão grandes quanto 2*maxBytes+metadata, onde maxBytes é configurado na solicitação de assinatura. Por exemplo, o Lambda adiciona os seguintes bytes de metadados a cada registro:

    {
"time": "2020-08-20T12:31:32.123Z",
"type": "function",
"record": "Hello World"
}

  • Se o assinante não puder processar logs de entrada com rapidez suficiente, o Lambda pode descartar logs para manter a utilização da memória limitada. Para indicar o número de registros descartados, o Lambda envia um log platform.logsDropped. Para ter mais informações, consulte Lambda: nem todos os logs da função aparecem.

Exemplo de assinatura

O exemplo a seguir mostra uma solicitação para se inscrever na plataforma e logs de funções.

PUT http://${AWS_LAMBDA_RUNTIME_API}/2020-08-15/logs HTTP/1.1
{ "schemaVersion": "2020-08-15",
  "types": [
      "platform",
      "function"
    ],
  "buffering": {
      "maxItems": 1000,
      "maxBytes": 262144,
      "timeoutMs": 100
    },
  "destination": {
    "protocol": "HTTP",
    "URI": "http://sandbox.localdomain:8080/lambda_logs"
  }
}

Se o pedido for bem-sucedido, o assinante receberá uma resposta de sucesso HTTP 200.

HTTP/1.1 200 OK
"OK"

Código de exemplo para Logs API

Para obter exemplos de código mostrando como enviar logs para um destino personalizado, consulte Using AWS Lambda extensions to send logs to custom destinations no AWS Compute Blog.

Para exemplos de código Python e Go que mostram como desenvolver uma extensão básica do Lambda e assinar a API Logs, consulte Extensões do AWS Lambda no repositório de exemplos da AWS no GitHub. Para obter mais informações sobre a criação de uma extensão do Lambda, consulte Usar a API de extensões do Lambda para criar extensões.

Referência da API Logs

É possível recuperar o endpoint da API Logs da variável de ambiente AWS_LAMBDA_RUNTIME_API. Para enviar uma solicitação de API, use o prefixo 2020-08-15/ antes do caminho da API. Por exemplo:

http://${AWS_LAMBDA_RUNTIME_API}/2020-08-15/logs

A especificação OpenAPI para a versão da API de logs, 2020-08-15, está disponível aqui: logs-api-request.zip

Assinar

Para se inscrever em um ou mais transmissões de log disponíveis no ambiente de execução do Lambda, as extensões enviam uma solicitação de assinatura da API.

Caminho: /logs

Método – PUT

Body parameters (Parâmetros do corpo)

destination: consulte protocolos de destino. Obrigatório: sim. Tipo: strings.

buffering: consulte Configuração de buffer. Obrigatório: não Tipo: strings.

types: uma matriz dos tipos de logs a serem recebidos. Obrigatório: sim. Tipo: matriz de strings. Valores válidos: “plataforma”, “função”, “extensão”.

schemaVersion: obrigatório: não Valor padrão: “2020-08-15”. Defina como “2021-03-18” para que a extensão receba platform.runtimeDone mensagens.

Parâmetros de resposta

As especificações OpenAPI para as respostas de assinatura, versão 2020-08-15, estão disponíveis para HTTP e TCP:

Códigos de resposta

  • 200: solicitação concluída com êxito

  • 202: solicitação aceita. Resposta a uma solicitação de assinatura durante testes locais.

  • 4XX: solicitação inválida

  • 500: erro do serviço

Se o pedido for bem-sucedido, o assinante receberá uma resposta de sucesso HTTP 200.

HTTP/1.1 200 OK
"OK"

Se a solicitação falhar, o assinante receberá uma resposta de erro. Por exemplo:

HTTP/1.1 400 OK
{
    "errorType": "Logs.ValidationError",
    "errorMessage": URI port is not provided; types should not be empty"
}

Mensagens de log

A API Logs permite que as extensões se inscrevam em três fluxos de logs diferentes:

  • Função: logs que a função do Lambda gera e grava em stdout ou stderr.

  • Extensão: logs gerados pelo código da extensão.

  • Plataforma: logs gerados pela plataforma de tempo de execução, que registram eventos e erros relacionados a invocações e extensões.

Registros de função

A função e as extensões internas do Lambda geram logs de funções e os gravam em stdout ou stderr.

O exemplo a seguir mostra o formato de uma mensagem de log de função. { "time": "2020-08-20T12:31:32.123Z", "type": "function", "record": "ERROR encountered. Rastreamento da pilha:\n\my-function (line 10)\n" }

Logs de extensões

As extensões podem gerar logs de extensões. O formato do log é o mesmo que para um log de funções.

Logs de plataformas

O Lambda gera mensagens de log para eventos de plataforma como platform.end, platform.start e platform.fault.

Opcionalmente, você pode se inscrever na versão 2021-03-18 do esquema da API de logs, que inclui a mensagem de log platform.runtimeDone.

Exemplo de mensagens de log da plataforma

O exemplo a seguir mostra o início da plataforma e os logs finais da plataforma. Esses logs indicam a hora de início da invocação e o horário de término para a invocação que o requestID especifica. 

{     
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.start",
    "record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56"}   
}
{
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.end",
    "record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56"}   
}

A mensagem de log platform.initRuntimeDone mostra o status da subfase Runtime init, que faz parte da fase de inicialização do ciclo de vida. Quando o Runtime init ocorre com êxito, o tempo de execução envia uma solicitação de API de tempo de execução /next (para os tipos provisioned-concurrency e de inicialização on-demand) ou restore/next (para o tipo de inicialização snap-start). O exemplo a seguir mostra uma mensagem de log platform.initRuntimeDone com êxito para o tipo de inicialização snap-start.

{
  "time":"2022-07-17T18:41:57.083Z",
  "type":"platform.initRuntimeDone",
  "record":{
      "initializationType":"snap-start",
      "status":"success"
  }
}

A mensagem de log Platform.initReport mostra quanto tempo durou a fase Init e por quantos milissegundos você foi cobrado durante essa fase. Quando o tipo de inicialização é provisioned-concurrency, o Lambda envia essa mensagem durante a invocação. Quando o tipo de inicialização é snap-start, o Lambda envia essa mensagem após restaurar o snapshot. O exemplo a seguir mostra uma mensagem de log platform.initReport para o tipo de inicialização snap-start.

{
  "time":"2022-07-17T18:41:57.083Z",
  "type":"platform.initReport",
  "record":{
      "initializationType":"snap-start",
      "metrics":{
          "durationMs":731.79,
          "billedDurationMs":732
          }
  }
}

O log de relatório da plataforma inclui métricas sobre a invocação que o requestID especifica. O campo initDurationMs é incluído no log somente se a invocação incluir uma partida a frio. Se o rastreamento do AWS X-Ray estiver ativo, o log incluirá metadados do X-Ray. O exemplo a seguir mostra um log de relatório de plataforma para uma invocação que incluiu uma partida a frio.

{     
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.report",
    "record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56",
        "metrics": {"durationMs": 101.51,
            "billedDurationMs": 300,
            "memorySizeMB": 512,
            "maxMemoryUsedMB": 33,
            "initDurationMs": 116.67
        }
    }
}

O log da plataforma captura erros de ambiente de execução ou tempo de execução. O exemplo a seguir mostra uma mensagem de log de falha da plataforma. 

{     
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.fault",
    "record": "RequestId: d783b35e-a91d-4251-af17-035953428a2c Process exited before completing request"
}

O Lambda gera um log de extensão de plataforma quando uma extensão se registra com a API Extensions. O exemplo a seguir mostra uma mensagem de extensão da plataforma. 

{     
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.extension",
    "record": {"name": "Foo.bar",
        "state": "Ready",
        "events": ["INVOKE", "SHUTDOWN"]
     }
}

O Lambda gera um log de assinatura de logs de plataforma quando uma extensão se inscreve na API Logs. O exemplo a seguir mostra uma mensagem de assinatura de logs. 

{     
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.logsSubscription",
    "record": {"name": "Foo.bar",
        "state": "Subscribed",
        "types": ["function", "platform"],
    }
}

O Lambda gera um log descartado de logs de plataforma quando uma extensão não é capaz de processar o número de logs que está recebendo. O exemplo a seguir mostra uma mensagem de log platform.logsDropped. 

{     
    "time": "2020-08-20T12:31:32.123Z",
    "type": "platform.logsDropped",
    "record": {"reason": "Consumer seems to have fallen behind as it has not acknowledged receipt of logs.",
        "droppedRecords": 123,
        "droppedBytes" 12345
    }
}

A mensagem de log platform.restoRestoRestart mostra o horário em que a fase Restore começou (somente para o tipo de inicialização snap-start). Exemplo:

{ 
  "time":"2022-07-17T18:43:44.782Z", 
  "type":"platform.restoreStart", 
  "record":{} 
}

A mensagem de log platform.restoreReport mostra quanto tempo durou a fase Restore e por quantos milissegundos você foi cobrado durante essa fase (somente para o tipo de inicializaçãosnap-start ). Exemplo:

{
  "time":"2022-07-17T18:43:45.936Z",
  "type":"platform.restoreReport",
  "record":{
      "metrics":{
          "durationMs":70.87,
          "billedDurationMs":13
      }
  }
}

Mensagens runtimeDone da plataforma

Se você definir a versão do esquema como “2021-03-18” na solicitação de assinatura, o Lambda enviará uma mensagem platform.runtimeDone após a conclusão da invocação da função com êxito ou com um erro. A extensão pode usar esta mensagem para interromper toda a coleção de telemetria para esta invocação de função.

A especificação OpenAPI para o tipo de evento do log no esquema versão 2021-03-18 está disponível aqui: schema-2021-03-18.zip

O Lambda gera a mensagem de log Next quando o tempo de execução envia uma solicitação de API do tempo de execução platform.runtimeDone ou Error. O platform.runtimeDone log informa os consumidores da API Logs que a invocação de função foi concluída. As extensões podem usar essas informações para decidir quando enviar toda a telemetria coletada durante essa invocação.

Exemplos

O Lambda envia a mensagem platform.runtimeDone depois que o tempo de execução envia a solicitação NEXT, quando a invocação da função for concluída. Os exemplos a seguir mostram mensagens para cada um dos valores de status: sucesso, falha e tempo limite.

exemplo Exemplo de mensagem de sucesso
{
    "time": "2021-02-04T20:00:05.123Z",
    "type": "platform.runtimeDone",
    "record": {
       "requestId":"6f7f0961f83442118a7af6fe80b88",
       "status": "success"
    }
}
exemplo Exemplo de mensagem de falha
{
   "time": "2021-02-04T20:00:05.123Z",
   "type": "platform.runtimeDone",
   "record": {
      "requestId":"6f7f0961f83442118a7af6fe80b88",
      "status": "failure"
   }
}
exemplo Exemplo de mensagem de tempo limite 
{
   "time": "2021-02-04T20:00:05.123Z",
   "type": "platform.runtimeDone",
   "record": {
      "requestId":"6f7f0961f83442118a7af6fe80b88",
      "status": "timeout"
  }
}
exemplo Exemplo de mensagem “platform.RestoreRuntimeDone” (somente para o tipo de inicialização snap-start)

A mensagem de log platform.RestoreRuntimeDone mostra se a fase Restore ocorreu, ou não, com êxito. O Lambda envia essa mensagem quando o tempo de execução envia uma solicitação de API de tempo de execução restore/next. Existem três status possíveis: com êxito, com falha e tempo limite. O exemplo a seguir mostra uma mensagem de log platform.restoreRuntimeDone com êxito.

{
  "time":"2022-07-17T18:43:45.936Z",
  "type":"platform.restoreRuntimeDone",
  "record":{
      "status":"success"
  }
}