# 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.
**As instâncias gerenciadas do Lambda não oferecem suporte à API de logs**
As instâncias gerenciadas do Lambda não oferecem suporte à API de logs. Se você estiver usando funções de instância gerenciada, use a [API de telemetria](telemetry-api.md) em vez disso. A API de telemetria fornece recursos aprimorados para coletar e processar dados de telemetria de suas funções do Lambda.
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 Lambda](runtimes-extensions-api.md)pode usar a API RLambda time Logs para assinar fluxos de log diretamente do Lambda[ambiente de execução](lambda-runtime-environment.md). O Lambda transmite os logs para a extensão e a extensão pode processar, filtrar e enviar os logs para qualquer destino preferido.
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/logs-api-concept-diagram.png)
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.
**Topics**
+ [Assinando para receber registros](#runtimes-logs-api-subscribing)
+ [Uso de memória](#runtimes-logs-api-memory)
+ [protocolos de destino](#runtimes-logs-api-dest)
+ [Configuração de buffer](#runtimes-logs-api-buffering)
+ [Exemplo de assinatura](#runtimes-logs-api-subs-example)
+ [Código de exemplo para Logs API](#runtimes-logs-api-samples)
+ [Referência da API Logs](#runtimes-logs-api-ref)
+ [Mensagens de log](#runtimes-logs-api-msg)
## 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](runtimes-extensions-api.md#extensions-registration-api-a) para receber o identificador de extensão. Em seguida, inscreva-se na API Logs durante a [inicialização](lambda-runtime-environment.md#runtimes-lifecycle-ib). 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](#runtimes-logs-api-buffering). O uso da memória buffer conta para o consumo geral de memória no ambiente de execução.
## protocolos de destino
É possível 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. É possível optar por receber logs através PUT ou POST.
1. **TCP**: o Lambda entrega logs a uma porta TCP no formato [JSON delimitado por nova linha (NDJSON)](https://github.com/ndjson/ndjson-spec).
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. É possível 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 obter mais informações, consulte [Lambda: nem todos os logs da função aparecem](troubleshooting-execution.md#troubleshooting-execution-missinglogs).
## 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 êxito 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](https://aws.amazon.com/blogs/compute/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](https://github.com/aws-samples/aws-lambda-extensions) 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](runtimes-extensions-api.md).
## 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](samples/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](#runtimes-logs-api-dest). Obrigatório: sim. Tipo: strings.
`buffering` – consulte [Configuração de buffer](#runtimes-logs-api-buffering). 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`](#runtimes-logs-api-ref-done) 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:
+ HTTP: [logs-api-http-response.zip](samples/logs-api-http-response.zip)
+ TCP: [logs-api-tcp-response.zip](samples/logs-api-tcp-response.zip)
****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 êxito 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.
**Topics**
+ [Logs de função](#runtimes-logs-api-msg-function)
+ [Logs de extensões](#runtimes-logs-api-msg-extension)
+ [Logs de plataformas](#runtimes-logs-api-msg-platform)
### Logs 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. \$1 "time": "2020-08-20T12:31:32.123Z", "type": "function", "record": "ERROR encountered. Rastreamento da pilha:\$1n\$1my-function (line 10)\$1n" \$1
### 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](lambda-runtime-environment.md#runtimes-lifecycle-ib). 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.
**Example registro do log de falhas da plataforma (estilo antigo)**
```
"record":"RequestId: ...\tError: Runtime exited with error: exit status 255\nRuntime.ExitError"
```
**Example 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ção`snap-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](samples/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: êxito, falha e tempo limite.
**Example Exemplo de mensagem de êxito**
```
{
"time": "2021-02-04T20:00:05.123Z",
"type": "platform.runtimeDone",
"record": {
"requestId":"6f7f0961f83442118a7af6fe80b88",
"status": "success"
}
}
```
**Example Exemplo de mensagem de falha**
```
{
"time": "2021-02-04T20:00:05.123Z",
"type": "platform.runtimeDone",
"record": {
"requestId":"6f7f0961f83442118a7af6fe80b88",
"status": "failure"
}
}
```
**Example Exemplo de mensagem de tempo limite**
```
{
"time": "2021-02-04T20:00:05.123Z",
"type": "platform.runtimeDone",
"record": {
"requestId":"6f7f0961f83442118a7af6fe80b88",
"status": "timeout"
}
}
```
**Example 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"
}
}
```