Usar a API de logs do Lambda
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 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
oustderr
.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.
Tópicos
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:
-
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. -
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
, ondemaxBytes
é 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
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
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
oustderr
.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" }
nota
A AWS atualmente está implementando alterações no serviço Lambda. Devido a essas alterações, você pode ver pequenas diferenças entre a estrutura e o conteúdo das mensagens de log do sistema e os segmentos de rastreamento emitidos por diferentes funções do Lambda na sua Conta da AWS.
Uma das saídas de log afetadas por essa alteração é o campo "record"
do log de falhas da plataforma. Os exemplos a seguir mostram campos "record"
ilustrativos no formato antigo e no formato novo. O novo estilo de log de falhas contém uma mensagem mais concisa
Essas alterações serão implementadas durante as próximas semanas, e todas as funções em todas as Regiões da AWS, exceto nas regiões China e GovCloud, passarão a usar o novo formato de mensagens de log e segmentos de rastreamento.
exemplo registro do log de falhas da plataforma (estilo antigo)
"record":"RequestId: ...\tError: Runtime exited with error: exit status 255\nRuntime.ExitError"
exemplo registro do log de falhas da plataforma (estilo novo)
"record":"RequestId: ... Status: error\tErrorType: Runtime.ExitError"
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" } }