# Ampliar funções do Lambda usando extensões do Lambda
É possível usar extensões do Lambda para aumentar as funções do Lambda. Por exemplo, use extensões do Lambda para integrar funções com suas ferramentas preferidas de monitoramento, observação, segurança e governança. Você pode escolher entre várias ferramentas que os [parceiros do AWS Lambda](https://aws.amazon.com/lambda/partners/) fornecem, ou pode [criar suas próprias extensões do Lambda](runtimes-extensions-api.md).
O Lambda é compatível com extensões internas e externas. Uma extensão externa é executada como um processo independente no ambiente de execução e continua a ser executada após a invocação da função ser totalmente processada. Como as extensões são executadas como processos separados, elas podem ser escritas em uma linguagem diferente da função. Todos os [Runtimes do Lambda](lambda-runtimes.md) são compatíveis com extensões.
Uma extensão interna é executada como parte do processo de runtime. A função acessa extensões internas usando scripts wrapper ou mecanismos no processo, como `JAVA_TOOL_OPTIONS`. Para obter mais informações, consulte [Modificar o ambiente de runtime](runtimes-modify.md).
É possível adicionar extensões a uma função usando o console do Lambda, a AWS Command Line Interface (AWS CLI) ou serviços e ferramentas da infraestrutura como código (IaC), como o CloudFormation, o AWS Serverless Application Model (AWS SAM) e o Terraform.
Você é cobrado pelo tempo de execução consumido pela extensão (em incrementos de 1 ms). Não há custo para instalar suas próprias extensões. Para obter mais informações sobre a definição de preço para extensões, consulte [Definição de preço do AWS Lambda](https://aws.amazon.com/lambda/pricing/). Para obter informações de definição de preço sobre extensões de parceiros, consulte os sites desses parceiros. Consulte [Parceiros de extensões do AWS Lambda](extensions-api-partners.md) para obter uma lista de extensões oficiais de parceiros.
**Topics**
+ [Ambiente de execução](#using-extensions-env)
+ [Impacto na performance e nos recursos](#using-extensions-reg)
+ [Permissões](#using-extensions-permissions)
+ [Configuração de extensões do Lambda](extensions-configuration.md)
+ [Parceiros de extensões do AWS Lambda](extensions-api-partners.md)
+ [Usar a API de extensões do Lambda para criar extensões](runtimes-extensions-api.md)
+ [Acessar dados de telemetria em tempo real para extensões usando a API Telemetria](telemetry-api.md)
## Ambiente de execução
O Lambda invoca a função em um [ambiente de execução](lambda-runtime-environment.md), que fornece um ambiente do runtime seguro e isolado. O ambiente de execução gerencia os recursos necessários para executar sua função e fornece suporte ao ciclo de vida para o runtime e extensões da função.
O ciclo de vida do ambiente de execução inclui as seguintes fases:
+ `Init`: nessa fase, o Lambda cria ou descongela um ambiente de execução com os recursos configurados, faz download do código da função e de todas as camadas, inicializa todas as extensões e o runtime, em seguida executa o código de inicialização da função (o código fora do handler principal). O`Init`ocorre durante a primeira invocação, ou antes de invocações de função se você tiver habilitado[Simultaneidade provisionada](provisioned-concurrency.md).
O`Init`é dividida em três subfases:`Extension init`,`Runtime init`, e`Function init`. Essas subfases garantem que todas as extensões e o runtime concluam suas tarefas de configuração antes que o código da função seja executado.
Quando o [Lambda SnapStart](snapstart.md) está ativado, a fase `Init` ocorre ao você publicar uma versão da função. O Lambda salva um snapshot do estado da memória e do disco do ambiente de execução inicializado, mantém o snapshot criptografado e o armazena em cache para acesso de baixa latência. Se você tiver um [hook de runtime](snapstart-runtime-hooks.md) before-checkpoint, então, o código será executado ao final da fase `Init`.
+ `Restore` (somente para SnapStart): quando você invoca uma função do [SnapStart](snapstart.md) pela primeira vez e à medida que aumenta a escala verticalmente da função, o Lambda retoma novos ambientes de execução do snapshot retido, em vez de inicializar a função do zero. Se você tiver um [hook de runtime](snapstart-runtime-hooks.md) after-restore, o código será executado ao final da fase `Restore`. Serão realizadas cobranças pela duração dos hooks de runtime after-restore. O runtime deve ser carregado e os hooks de runtime after-restore devem ser concluídos dentro do limite de tempo limite (dez segundos). Caso contrário, você obterá uma SnapStartTimeoutException. Quando a fase `Restore` é concluída, o Lambda invoca o manipulador de função (a [Fase de invocação](lambda-runtime-environment.md#runtimes-lifecycle-invoke)).
+ `Invoke`: Nesta fase, o Lambda chama o manipulador de função. Depois que a função é executada até a conclusão, o Lambda se prepara para manipular outra invocação de função.
+ `Shutdown`: Esta fase é acionada se a função do Lambda não receber quaisquer invocações por um período de tempo. Na fase `Shutdown`, o Lambda encerra o runtime, alerta as extensões para permitir que elas parem de forma limpa e, em seguida, remove o ambiente. Lambda envia um`Shutdown`para cada extensão, que informa a extensão que o ambiente está prestes a ser encerrado.
Durante o`Init`, o Lambda extrai camadas contendo extensões para o`/opt`no ambiente de execução. O Lambda procura extensões no`/opt/extensions/`, interpreta cada arquivo como um bootstrap executável para iniciar a extensão e inicia todas as extensões em paralelo.
## Impacto na performance e nos recursos
O tamanho das extensões da função conta para o limite de tamanho do pacote de implantação. Para um arquivo .zip, o tamanho total descompactado da função e de todas as extensões não pode exceder o limite de tamanho do pacote de implantação descompactado de 250 MB.
As extensões podem afetar a performance da função porque compartilham recursos de função, como CPU, memória e armazenamento. Por exemplo, se uma extensão executa operações de computação intensiva, você pode ver o aumento da duração da execução da função.
Cada extensão deve concluir sua inicialização antes de o Lambda invocar a função. Portanto, uma extensão que consome tempo de inicialização significativo pode aumentar a latência da invocação da função.
Para medir o tempo adicional que a extensão leva após a execução da função, você pode usar a[métrica da função](monitoring-metrics.md) `PostRuntimeExtensionsDuration`. Para medir o aumento da memória usada, você pode usar a métrica `MaxMemoryUsed`. Para entender o impacto de uma extensão específica, você pode executar diferentes versões das funções lado a lado.
**nota**
A métrica `MaxMemoryUsed` é uma das [métricas coletadas pelo Lambda Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights-metrics.html), não uma métrica nativa do Lambda.
## Permissões
As extensões têm acesso aos mesmos recursos que as funções. Como as extensões são executadas no mesmo ambiente que a função, as permissões são compartilhadas entre a função e a extensão.
Para um arquivo .zip, é possível criar um modelo do CloudFormation para simplificar a tarefa de anexar a mesma configuração de extensão, incluindo permissões do AWS Identity and Access Management (IAM), a várias funções.
# Configuração de extensões do Lambda
## Configurar extensões (arquivamento de arquivo.zip)
Você pode adicionar uma extensão à sua função como uma [ camada do Lambda](chapter-layers.md). O uso de camadas permite compartilhar extensões em toda a organização ou com toda a comunidade de desenvolvedores do Lambda. É possível adicionar uma ou mais extensões a uma camada. É possível registrar até 10 extensões para uma função.
Adicione a extensão à função usando o mesmo método que faria para qualquer camada. Para ter mais informações, consulte [Gerenciar dependências do Lambda com camadas](chapter-layers.md).
**Adicionar uma extensão à função (console)**
1. Abra a [página Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda.
1. Escolha uma função.
1. Escolha a guia **Código** se ainda não estiver selecionada.
1. Em **Camadas**, escolha **Editar**.
1. Em **Choose a layer (Selecionar uma camada)**, selecione **Specify an ARN (Especificar um ARN)**.
1. Em **Specify an ARN (Especificar um ARN)**, insira o nome de recurso da Amazon (ARN) de uma camada de extensão.
1. Escolha **Adicionar**.
## Uso de extensões em imagens de contêiner
Você pode adicionar extensões à [imagem do contêiner](images-create.md). A configuração de imagem de contêiner ENTRYPOINT especifica o processo principal para a função. Configure a configuração ENTRYPOINT no Dockerfile ou como uma substituição na configuração da função.
Você pode executar vários processos dentro de um contêiner. Lambda gerencia o ciclo de vida do processo principal e quaisquer processos adicionais. O Lambda usa o[API Extensions do](runtimes-extensions-api.md)para gerenciar o ciclo de vida da extensão.
### Exemplo: Adicionando uma extensão externa
Uma extensão externa é executada em um processo separado da função Lambda. O Lambda inicia um processo para cada extensão no`/opt/extensions/`Diretório. O Lambda usa a API de extensões para gerenciar o ciclo de vida da extensão. Depois que a função for executada até a conclusão, o Lambda envia um evento `Shutdown` para cada extensão externa.
**Example de adicionar uma extensão externa a uma imagem base Python**
```
FROM public.ecr.aws/lambda/python:3.11
# Copy and install the app
COPY /app /app
WORKDIR /app
RUN pip install -r requirements.txt
# Add an extension from the local directory into /opt/extensions
ADD my-extension.zip /opt/extensions
CMD python ./my-function.py
```
## Próximas etapas
Para saber mais sobre extensões, recomendamos os seguintes recursos:
+ Para obter um exemplo básico de trabalho, consulte [Building Extensions for AWS Lambda](https://aws.amazon.com/blogs/compute/building-extensions-for-aws-lambda-in-preview/) no AWS Compute Blog.
+ Para obter informações sobre extensões fornecidas pelos parceiros da AWS Lambda, consulte [Introducing AWS Lambda Extensions](https://aws.amazon.com/blogs/compute/introducing-aws-lambda-extensions-in-preview/) no AWS Compute Blog.
+ Para exibir extensões de exemplo disponíveis e scripts de wrapper, consulte [AWS Lambda Extensões](https://github.com/aws-samples/aws-lambda-extensions) no repositório AWS Samples GitHub.
# Parceiros de extensões do AWS Lambda
O AWS Lambda fez uma parceria com várias entidades de terceiros para fornecer extensões que se integram às suas funções Lambda. A lista a seguir detalha extensões de terceiros que estão prontas para uso a qualquer momento.
+ [https://docs.appdynamics.com/display/PRO20X/Use+the+AppDynamics+AWS+Lambda+Extension+to+Instrument+Serverless+APM+at+Runtime](https://docs.appdynamics.com/display/PRO20X/Use+the+AppDynamics+AWS+Lambda+Extension+to+Instrument+Serverless+APM+at+Runtime): fornece instrumentação automática das funções do Lambda no Node.js ou Python, oferecendo visibilidade e alertando sobre a performance das funções.
+ [https://axiom.co/docs/apps/lambda](https://axiom.co/docs/apps/lambda): fornece painéis para monitorar a performance e as métricas agregadas no nível do sistema das funções do Lambda.
+ [https://docs.datadoghq.com/serverless/datadog_lambda_library/extension/](https://docs.datadoghq.com/serverless/datadog_lambda_library/extension/): fornece visibilidade abrangente em tempo real das aplicações com tecnologia sem servidor por meio do uso de métricas, rastreamentos e logs.
+ [https://www.dynatrace.com/support/help/technology-support/cloud-platforms/amazon-web-services/integrations/deploy-oneagent-as-lambda-extension/](https://www.dynatrace.com/support/help/technology-support/cloud-platforms/amazon-web-services/integrations/deploy-oneagent-as-lambda-extension/): fornece visibilidade de rastreamentos e métricas e utiliza IA para detecção automatizada de erros e análise de causa raiz em toda a pilha de aplicações.
+ [https://www.elastic.co/guide/en/apm/agent/nodejs/current/lambda.html](https://www.elastic.co/guide/en/apm/agent/nodejs/current/lambda.html): fornece monitoramento de desempenho de aplicativos (APM) para identificar e resolver problemas de causa raiz usando rastreamentos, métricas e logs.
+ [https://docs.epsagon.com/docs/environment-monitoring/lambda/intro](https://docs.epsagon.com/docs/environment-monitoring/lambda/intro): escuta eventos de invocação, armazena rastreamentos e envia-os em paralelo às execuções de funções do Lambda.
+ [https://docs.fastly.com/signalsciences/install-guides/paas/aws-lambda/](https://docs.fastly.com/signalsciences/install-guides/paas/aws-lambda/): protege as funções do Lambda contra atividades suspeitas, como ataques no estilo de injeção, invasão de contas por meio de inserção de credenciais, bots maliciosos e abuso de API.
+ [https://learn.hashicorp.com/tutorials/vault/aws-lambda](https://learn.hashicorp.com/tutorials/vault/aws-lambda): gerencia segredos e disponibiliza-os para os desenvolvedores usarem em código de funções, sem tornar as funções habilitadas para reconhecimento de cofre.
+ [https://docs.honeycomb.io/getting-data-in/integrations/aws/aws-lambda/](https://docs.honeycomb.io/getting-data-in/integrations/aws/aws-lambda/): ferramenta de observabilidade para depurar a pilha de aplicações.
+ [https://docs.lumigo.io/docs/lambda-extensions](https://docs.lumigo.io/docs/lambda-extensions): perfila invocações de funções do Lambda e coleta métricas para solucionar problemas em ambientes de tecnologia sem servidor e de microsserviços.
+ [https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/get-started/monitoring-aws-lambda-serverless-monitoring](https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/get-started/monitoring-aws-lambda-serverless-monitoring): é executado junto com as funções do Lambda, coletando, aperfeiçoando e transportando automaticamente telemetria para a plataforma de observabilidade unificada New Relic.
+ [https://docs.sedai.io/get-started/platform/optimization/aws/lambda](https://docs.sedai.io/get-started/platform/optimization/aws/lambda): uma plataforma autônoma de gerenciamento de nuvem, baseada em IA/ML, que oferece otimização contínua para equipes de operações de nuvem a fim de maximizar a economia de custos, o desempenho e a disponibilidade da nuvem em grande escala.
+ [https://docs.sentry.io/platforms/javascript/guides/aws-lambda/](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/): faça o diagnóstico, corrija e otimize a performance das funções do Lambda.
+ [https://www.site24x7.com/help/aws/lambda-execution-logs.html](https://www.site24x7.com/help/aws/lambda-execution-logs.html): obtenha observabilidade em tempo real dos ambientes do Lambda
+ [https://github.com/signalfx/splunk-otel-lambda](https://github.com/signalfx/splunk-otel-lambda): coleta métricas de alta resolução e baixa latência para monitoramento eficiente e eficaz das funções do Lambda.
+ [https://help.sumologic.com/03Send-Data/Collect-from-Other-Data-Sources/Collect_AWS_Lambda_Logs_using_an_Extension](https://help.sumologic.com/03Send-Data/Collect-from-Other-Data-Sources/Collect_AWS_Lambda_Logs_using_an_Extension): fornece visibilidade da integridade e performance das aplicações com tecnologia sem servidor.
+ [Salt Security](https://salt.security/press-releases/salt-security-becomes-the-first-and-only-api-security-vendor-to-join-aws-lambda-ready-program?): simplifica a governança de posturas da API e a segurança da API para funções do Lambda por meio de configuração e compatibilidade automatizadas para runtimes diversos.
## Extensões gerenciadas pela AWS
A AWS fornece suas próprias extensões gerenciadas, incluindo:
+ [AWS AppConfig](https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-lambda-extensions.html#appconfig-integration-lambda-extensions-enabling): use sinalizadores de recursos e dados dinâmicos para atualizar suas funções Lambda. Utilize também essa extensão para atualizar outras configurações dinâmicas, como controle de utilização e ajuste de operações.
+ [Amazon CodeGuru Profiler](https://docs.aws.amazon.com/codeguru/latest/profiler-ug/python-lambda-layers.html): melhora a performance da aplicação e reduz os custos identificando a linha de código mais cara da aplicação e fornecendo recomendações para melhorar o código.
+ [CloudWatch Lambda Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights.html): monitore, solucione problemas e otimize a performance de suas funções Lambda por painéis automatizados.
+ [AWS Distro para OpenTelemetry (ADOT)](https://aws.amazon.com/otel): possibilita que as funções enviem dados de rastreamento para os serviços de monitoramento da AWS, como o AWS X-Ray, e para os destinos que oferecem suporte ao OpenTelemetry, como o Honeycomb e o Lightstep.
+ [AWS Parameters and Secrets](with-secrets-manager.md): permite recuperar parâmetros da AWS Systems Manager Parameter Store e segredos do AWS Secrets Manager em funções do Lambda com segurança.
Para ver outros exemplos de extensões e projetos de demonstração, consulte as [extensões do AWS Lambda](https://github.com/aws-samples/aws-lambda-extensions).
# Usar a API de extensões do Lambda para criar extensões
Autores de funções do Lambda usam extensões para integrar o Lambda às suas ferramentas preferidas para monitoramento, observabilidade, segurança e governança. Os autores de funções podem usar extensões da AWS, de [parceiros da AWS](extensions-api-partners.md) e de projetos de código aberto. Para obter mais informações, consulte [Introducing AWS Lambda Extensions](https://aws.amazon.com/blogs/aws/getting-started-with-using-your-favorite-operational-tools-on-aws-lambda-extensions-are-now-generally-available/) no AWS Compute Blog. Esta seção descreve como usar a API de extensões do Lambda, o ciclo de vida do ambiente de execução do Lambda e a referência de API de extensões do Lambda.
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/telemetry-api-concept-diagram.png)
Como um autor de extensões, você pode usar as API de extensões do Lambda para integrar profundamente no [ambiente de execução](lambda-runtime-environment.md) do Lambda. Sua extensão pode inscrever-se para eventos de ciclo de vida do ambiente de execução e função. Em resposta a esses eventos, você pode iniciar novos processos, executar lógica e controlar e participar de todas as fases do ciclo de vida do Lambda: inicialização, invocação e desligamento. Além disso, você pode usar os [API Runtime Logs](runtimes-logs-api.md) para receber um stream de logs.
Uma extensão externa é executada como um processo independente no ambiente de execução e continua a ser executada após a invocação da função ser totalmente processada. Como as extensões são executadas como processos, elas podem ser escritas em uma linguagem diferente da função. Recomendamos que você implemente as extensões usando uma linguagem compilada. Nesse caso, a extensão é um binário autônomo compatível com os tempos de execução compatíveis. Todos os [Runtimes do Lambda](lambda-runtimes.md) são compatíveis com extensões. Se você usar uma linguagem não compilada, inclua um runtime compatível na extensão.
O Lambda também oferece suporte a *extensões internas*. Uma extensão interna é executada como um thread separado no processo de runtime. O runtime inicia e interrompe a extensão interna. Uma maneira alternativa de se integrar com o ambiente do Lambda é usar [variáveis de ambiente com linguagem específica e scripts wrapper](runtimes-modify.md). É possível usar isso para configurar o ambiente do runtime e modificar o comportamento de startup do processo do runtime.
É possível adicionar extensões a uma função de duas maneiras. Para uma função implantada como um [arquivo.zip](configuration-function-zip.md), você implanta a extensão como uma [camada](chapter-layers.md). Para uma função definida como uma imagem de contêiner, você adiciona [as extensões](extensions-configuration.md#invocation-extensions-images) à imagem do contêiner.
**nota**
Por exemplo, extensões e scripts de wrapper, consulte [AWS Lambda Extensões](https://github.com/aws-samples/aws-lambda-extensions) no repositório AWS Samples GitHub.
**Topics**
+ [Ciclo de vida do ambiente de execução do Lambda](#runtimes-extensions-api-lifecycle)
+ [Referência de API de extensões](#runtimes-extensions-registration-api)
## Ciclo de vida do ambiente de execução do Lambda
O ciclo de vida do ambiente de execução inclui as seguintes fases:
+ `Init`: nessa fase, o Lambda cria ou descongela um ambiente de execução com os recursos configurados, faz download do código da função e de todas as camadas, inicializa todas as extensões e o runtime, em seguida executa o código de inicialização da função (o código fora do handler principal). O`Init`ocorre durante a primeira invocação, ou antes de invocações de função se você tiver habilitado[Simultaneidade provisionada](provisioned-concurrency.md).
O`Init`é dividida em três subfases:`Extension init`,`Runtime init`, e`Function init`. Essas subfases garantem que todas as extensões e o runtime concluam suas tarefas de configuração antes que o código da função seja executado.
+ `Invoke`: Nesta fase, o Lambda chama o manipulador de função. Depois que a função é executada até a conclusão, o Lambda se prepara para manipular outra invocação de função.
+ `Shutdown`: Esta fase é acionada se a função do Lambda não receber quaisquer invocações por um período de tempo. Na fase `Shutdown`, o Lambda encerra o runtime, alerta as extensões para permitir que elas parem de forma limpa e, em seguida, remove o ambiente. O Lambda envia um`Shutdown`para cada extensão, que informa a extensão que o ambiente está prestes a ser encerrado.
Cada fase começa com um evento do serviço do Lambda para o runtime e para todas as extensões registradas. O runtime e cada conclusão do sinal de extensão enviando uma Solicitação de API `Next`. O Lambda congela o ambiente de execução quando cada processo é concluído e não há eventos pendentes.
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/Overview-Full-Sequence.png)
**Topics**
+ [Fase de inicialização](#runtimes-extensions-api-reg)
+ [Fase de invocação](#runtimes-lifecycle-extensions-invoke)
+ [Fase de desligamento](#runtimes-lifecycle-extensions-shutdown)
+ [Permissões e configuração](#runtimes-extensions-registration-api-e)
+ [Tratamento de falhas](#runtimes-extensions-api-failure)
+ [Solução de problemas de extensões](#runtimes-extensions-api-trbl)
### Fase de inicialização
Durante o`Extension init`, cada extensão precisa se registrar com o Lambda para receber eventos. O Lambda usa o nome completo do arquivo da extensão para validar que a extensão concluiu a sequência de bootstrap. Portanto, cada chamada de API `Register` deve incluir o cabeçalho `Lambda-Extension-Name` com o nome de arquivo completo da extensão.
É possível registrar até 10 extensões para uma função. Esse limite é imposto pela chamada de API `Register`.
Depois que cada extensão é registrada, o Lambda inicia a fase `Runtime init`. O processo de runtime chama `functionInit` para iniciar a fase `Function init`.
A fase `Init` é concluída após o runtime e cada extensão registrada indica a conclusão enviando uma solicitação de API `Next`.
**nota**
As extensões podem concluir sua inicialização em qualquer momento da fase `Init`.
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/Init-Phase.png)
### Fase de invocação
Quando uma função do Lambda é invocada em resposta a uma solicitação de API `Next`, o envia um evento `Invoke` para o runtime e para cada extensão registrada para o evento `Invoke`.
**nota**
**Instâncias gerenciadas do Lambda: ** as extensões para funções de instâncias gerenciadas pelo Lambda não podem se registrar para o evento `Invoke`. Como as instâncias gerenciadas do Lambda oferecem suporte a invocações simultâneas em um único ambiente de execução, não há suporte para o evento `Invoke`. As extensões só podem se registrar para o evento `Shutdown`. Se você precisar monitorar quando as invocações começam e terminam, use o evento de plataforma `platform.report` por meio da [API de telemetria](telemetry-api.md).
Durante a invocação, as extensões externas são executadas em paralelo com a função. Elas também continuam em execução após a conclusão da função. Isso permite que você capture informações para diagnóstico ou para enviar logs, métricas e rastreamentos para um local de sua escolha.
Depois de receber a resposta da função do runtime, o Lambda retorna a resposta ao cliente, mesmo que as extensões ainda estejam em execução.
A fase `Invoke` termina após o runtime e todas as extensões sinalizam que elas foram concluídas enviando uma solicitação de API `Next`.
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/Invoke-Phase.png)
**Carga útil do evento**: o evento enviado para o runtime (e a função do Lambda) leva toda a solicitação, os cabeçalhos (como `RequestId`) e carga útil. O evento enviado para cada extensão contém metadados que descrevem o conteúdo do evento. Este evento de ciclo de vida inclui o tipo do evento, o tempo em que a função timas-out (`deadlineMs`) `requestId`, o nome de recurso da Amazon (ARN) da função chamada e cabeçalhos de rastreamento.
As extensões que desejam acessar o corpo do evento de função podem usar um SDK no runtime que se comunica com a extensão. Os desenvolvedores de funções usam o SDK no runtime para enviar a carga útil para a extensão quando a função é invocada.
Veja um exemplo de carga útil:
```
{
"eventType": "INVOKE",
"deadlineMs": 676051,
"requestId": "3da1f2dc-3222-475e-9205-e2e6c6318895",
"invokedFunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:ExtensionTest",
"tracing": {
"type": "X-Amzn-Trace-Id",
"value": "Root=1-5f35ae12-0c0fec141ab77a00bc047aa2;Parent=2be948a625588e32;Sampled=1"
}
}
```
**Limite de duração**: a definição do tempo limite da função limita a duração de toda a fase `Invoke`. Por exemplo, se você definir o tempo limite da função como 360 segundos, a função e todas as extensões precisam ser concluídas em até 360 segundos. Observe que não há fase de pós-invocação independente. A duração é o tempo total até a conclusão do seu runtime e das invocações de todas as extensões. Esse valor não é calculado até que a função e todas as extensões tenham terminado a execução.
**Impacto na performance e sobrecarga de extensão**: as extensões podem afetar a performance da função. Como autor da extensão, você tem controle sobre o impacto de performance da extensão. Por exemplo, se a extensão executa operações com uso intenso de computação, a duração da função aumenta, pois a extensão e o código da função compartilham os mesmos recursos de CPU. Além disso, se a extensão executar operações extensas após a conclusão da invocação da função, a duração da função aumentará porque a fase `Invoke` continuará até que todas as extensões sinalizem que foram concluídas.
**nota**
O Lambda aloca a potência da CPU em proporção à configuração de memória da função. É possível ver maior duração de execução e inicialização em configurações de memória mais baixas porque os processos de função e extensão estão competindo pelos mesmos recursos da CPU. Para reduzir a duração da execução e inicialização, tente aumentar a configuração de memória.
Para ajudar a identificar o impacto na performance apresentado pelas extensões na fase `Invoke`, o Lambda gera a métrica `PostRuntimeExtensionsDuration`. Essa métrica mede o tempo cumulativo gasto entre a solicitação de API `Next` do runtime e a última solicitação de API `Next` da extensão. Para medir o aumento da memória usada, use a métrica `MaxMemoryUsed`. Para obter mais informações sobre métricas de funções, consulte [Uso de métricas do CloudWatch com o Lambda](monitoring-metrics.md).
Os desenvolvedores de funções podem executar diferentes versões de suas funções lado a lado para entender o impacto de uma extensão específica. Recomendamos que os autores de extensão publiquem o consumo esperado de recursos para facilitar aos desenvolvedores de funções a escolha de uma extensão adequada.
### Fase de desligamento
Quando o Lambda estiver prestes a encerrar o runtime, ele enviará um `Shutdown` a cada extensão externa registrada. As extensões podem usar esse tempo para tarefas de limpeza finais. O evento `Shutdown` é enviado em resposta a uma solicitação de API `Next`.
**Limite de duração**: a duração máxima da fase `Shutdown` depende da configuração das extensões registradas:
+ 0 ms: uma função sem extensões registradas
+ 500 ms: uma função com uma extensão interna registrada
+ 2.000 ms: uma função com uma ou mais extensões externas registradas
Se o runtime ou uma extensão não responder ao evento `Shutdown` dentro do limite, o Lambda encerrará o processo usando um sinal `SIGKILL`.
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/Shutdown-Phase.png)
**Carga útil do evento**: o evento `Shutdown` contém o motivo do desligamento e o tempo restante em milissegundos.
O `shutdownReason` inclui os seguintes valores:
+ SPINDOWN: desligamento normal
+ TIMEOUT: limite da duração do tempo expirado
+ FAILURE: condição de erro, como um evento `out-of-memory`
```
{
"eventType": "SHUTDOWN",
"shutdownReason": "reason for shutdown",
"deadlineMs": "the time and date that the function times out in Unix time milliseconds"
}
```
### Permissões e configuração
As extensões são executadas no mesmo ambiente de execução que a função do Lambda. As extensões também compartilham recursos com a função, como CPU, memória e armazenamento em disco `/tmp`. Além disso, as extensões usam a mesma função do AWS Identity and Access Management (IAM) e o mesmo contexto de segurança que a função.
**Permissões de acesso ao sistema de arquivos e à rede**: as extensões são executadas no mesmo sistema de arquivos e namespace de nome de rede que o runtime da função. Isso significa que as extensões precisam ser compatíveis com o sistema operacional associado. Se uma extensão exigir regras adicionais de saída do tráfego de rede, você deverá aplicar essas regras à configuração da função.
**nota**
Como o diretório de código de função é somente leitura, as extensões não podem modificar o código da função.
**Variáveis de ambiente**: as extensões podem acessar as [variáveis de ambiente](configuration-envvars.md) da função, exceto as seguintes variáveis específicas do processo de runtime:
+ `AWS_EXECUTION_ENV`
+ `AWS_LAMBDA_LOG_GROUP_NAME`
+ `AWS_LAMBDA_LOG_STREAM_NAME`
+ `AWS_XRAY_CONTEXT_MISSING`
+ `AWS_XRAY_DAEMON_ADDRESS`
+ `LAMBDA_RUNTIME_DIR`
+ `LAMBDA_TASK_ROOT`
+ `_AWS_XRAY_DAEMON_ADDRESS`
+ `_AWS_XRAY_DAEMON_PORT`
+ `_HANDLER`
**nota**
**Detecção de instâncias gerenciadas do Lambda:** as extensões podem verificar a variável de ambiente `AWS_LAMBDA_INITIALIZATION_TYPE` para determinar se estão sendo executadas em instâncias gerenciadas do Lambda versus nas funções do Lambda (padrão). Esse é o método recomendado para que as extensões adaptem seu comportamento conforme o tipo de ambiente de execução.
### Tratamento de falhas
**Falhas de inicialização**: se uma extensão falhar, o Lambda reiniciará o ambiente de execução para impor um comportamento consistente e incentivar falhas rapidamente para extensões. Além disso, para alguns clientes, as extensões devem atender às necessidades críticas, como registro em log, segurança, governança e coleta de telemetria.
**Invocar falhas** (como falta de memória, tempo limite da função): como as extensões compartilham recursos com o runtime, elas são afetadas pelo esgotamento da memória. Quando o runtime falha, todas as extensões e o próprio runtime participam da fase `Shutdown`. Além disso, o runtime é reiniciado automaticamente como parte do chamado atual ou por meio de um mecanismo de reinicialização adiado.
Se houver uma falha (como um erro de tempo limite ou de runtime de uma função) durante `Invoke`, o serviço Lambda executará uma redefinição. A redefinição se comporta como um evento `Shutdown`. Primeiro, o Lambda encerra o runtime, depois, envia um evento `Shutdown` para cada extensão externa registrada. O evento inclui o motivo do desligamento. Se esse ambiente for usado para uma nova invocação, a extensão e o runtime serão reinicializados como parte da próxima invocação.
![\[Exemplo de ambiente de execução: inicialização, invocação, invocação com erro, invocação, encerramento\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/Overview-Invoke-with-Error.png)
Para obter uma explicação mais detalhada do diagrama anterior, consulte [Falhas durante a fase de invocação](lambda-runtime-environment.md#runtimes-lifecycle-invoke-with-errors).
**Logs de extensões**: o Lambda envia a saída de log de extensões para o CloudWatch Logs. O Lambda também gera um evento de log adicional para cada extensão durante `Init`. O evento de logs registra o nome e a preferência de registro (evento, configuração) em caso de êxito ou o motivo da falha em caso de falha.
### Solução de problemas de extensões
+ Se uma solicitação `Register` falhar, o cabeçalho `Lambda-Extension-Name` na chamada de API `Register` deverá conter o nome completo do arquivo da extensão.
+ Se a solicitação `Register` falhar para uma extensão interna, a solicitação não deverá estar registrada para o evento `Shutdown`.
## Referência de API de extensões
A especificação OpenAPI para a versão da API de extensões **2020-01-01** está disponível aqui: [extensions-api.zip](samples/extensions-api.zip)
É possível recuperar o valor do endpoint da API da variável de ambiente `AWS_LAMBDA_RUNTIME_API`. Para enviar uma solicitação `Register`, use o prefixo `2020-01-01/` antes de cada caminho da API. Por exemplo:
```
http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register
```
**Topics**
+ [Inscreva-se](#extensions-registration-api-a)
+ [Próximo](#extensions-api-next)
+ [Erro de inicialização](#runtimes-extensions-init-error)
+ [Erro de saída](#runtimes-extensions-exit-error)
### Inscreva-se
Durante`Extension init`, todas as extensões precisam se registrar no Lambda para receber eventos. O Lambda usa o nome completo do arquivo da extensão para validar que a extensão concluiu a sequência de bootstrap. Portanto, cada chamada de API `Register` deve incluir o cabeçalho `Lambda-Extension-Name` com o nome de arquivo completo da extensão.
As extensões internas são iniciadas e interrompidas pelo processo de runtime, portanto, elas não têm permissão para se registrar para o evento `Shutdown`.
**Caminho** – `/extension/register`
**Método** – **POST**
**Cabeçalhos de solicitação**
+ `Lambda-Extension-Name`: o nome completo do arquivo da extensão. Obrigatório: sim. Tipo: string.
+ `Lambda-Extension-Accept-Feature`: use isso para especificar os recursos opcionais de extensões durante o registro. Obrigatório: não Tipo: strings separada por vírgula. Recursos disponíveis para serem especificados usando essa configuração:
+ `accountId`: se especificado, a resposta de registro da extensão conterá o ID da conta associada à função do Lambda para a qual você está registrando a extensão.
**Parâmetros do corpo da solicitação**
+ `events`: matriz dos eventos para registrar. Obrigatório: não Tipo: matriz de strings. Strings válidas: `INVOKE`, `SHUTDOWN`.
**nota**
**Instâncias gerenciadas do Lambda:** as extensões para funções de instâncias gerenciadas do Lambda podem somente se registrar para o evento `SHUTDOWN`. Tentar se registrar no evento `INVOKE` causará um erro. Como as instâncias gerenciadas do Lambda oferecem suporte a invocações simultâneas em um único ambiente de execução.
**Cabeçalhos de resposta**
+ `Lambda-Extension-Identifier`: identificador de agente exclusivo gerado (string UUID) que é obrigatório para todas as solicitações subsequentes.
**Códigos de resposta**
+ 200: o corpo de resposta contém o nome da função, a versão da função e o nome do manipulador.
+ 400: solicitação inválida
+ 403: proibido
+ 500: erro de contêiner. Estado não recuperável. A extensão deve sair imediatamente.
**Example Exemplo de corpo da solicitação**
```
{
'events': [ 'INVOKE', 'SHUTDOWN']
}
```
**Example Exemplo de corpo da resposta**
```
{
"functionName": "helloWorld",
"functionVersion": "$LATEST",
"handler": "lambda_function.lambda_handler"
}
```
**Example Exemplo de corpo de resposta com recurso opcional accountId**
```
{
"functionName": "helloWorld",
"functionVersion": "$LATEST",
"handler": "lambda_function.lambda_handler",
"accountId": "123456789012"
}
```
### Próximo
As extensões enviam uma solicitação de API `Next` para receber o próximo evento, que pode ser um evento `Invoke` ou um evento `Shutdown`. O corpo da resposta contém a carga útil, que é um documento JSON com dados do evento.
A extensão envia uma solicitação de API `Next` para sinalizar que está pronta para receber novos eventos. Essa é uma chamada de bloqueio.
Não defina um tempo limite na chamada GET, pois a extensão pode ser suspensa por um período até que haja um evento a ser retornado.
**Caminho** – `/extension/event/next`
**Método** – **GET**
**Cabeçalhos de solicitação**
+ `Lambda-Extension-Identifier`: identificador exclusivo para extensão (string UUID). Obrigatório: sim. Tipo: string UUID.
**Cabeçalhos de resposta**
+ `Lambda-Extension-Event-Identifier`: identificador exclusivo para o evento (string UUID).
**Códigos de resposta**
+ 200: a resposta contém informações sobre o próximo evento (`EventInvoke` ou `EventShutdown`).
+ 403: proibido
+ 500: erro de contêiner. Estado não recuperável. A extensão deve sair imediatamente.
### Erro de inicialização
A extensão usa esse método para relatar um erro de inicialização para o Lambda. Chame-a quando a extensão falhar ao inicializar após ter sido registrada. Depois que o Lambda recebe o erro, não há mais chamadas de API bem-sucedidas. A extensão deve sair depois de receber a resposta do Lambda.
**Caminho** – `/extension/init/error`
**Método** – **POST**
**Cabeçalhos de solicitação**
+ `Lambda-Extension-Identifier`: identificador exclusivo para extensão. Obrigatório: sim. Tipo: string UUID.
+ `Lambda-Extension-Function-Error-Type`: tipo de erro encontrado pela extensão. Obrigatório: sim. Este cabeçalho consiste em um valor de string. Lambda aceita qualquer string, mas recomendamos o formato . Por exemplo:
+ Extension.NoSuchHandler
+ Extension.APIKeyNotFound
+ Extension.ConfigInvalid
+ Extension.UnknownReason
**Parâmetros do corpo da solicitação**
+ `ErrorRequest`: informações adicionais sobre o erro. Obrigatório: não
Este campo é um objeto JSON com a seguinte estrutura:
```
{
errorMessage: string (text description of the error),
errorType: string,
stackTrace: array of strings
}
```
Observe que o Lambda aceita qualquer valor para `errorType`.
O exemplo a seguir mostra uma mensagem de erro de função do Lambda na qual a função não pôde analisar os dados do evento fornecidos na chamada.
**Example Erro de função**
```
{
"errorMessage" : "Error parsing event data.",
"errorType" : "InvalidEventDataException",
"stackTrace": [ ]
}
```
**Códigos de resposta**
+ 202: aceito
+ 400: solicitação inválida
+ 403: proibido
+ 500: erro de contêiner. Estado não recuperável. A extensão deve sair imediatamente.
### Erro de saída
A extensão usa esse método para relatar um erro ao Lambda antes de sair. Chame-a quando encontrar uma falha inesperada. Depois que o Lambda recebe o erro, não há mais chamadas de API bem-sucedidas. A extensão deve sair depois de receber a resposta do Lambda.
**Caminho** – `/extension/exit/error`
**Método** – **POST**
**Cabeçalhos de solicitação**
+ `Lambda-Extension-Identifier`: identificador exclusivo para extensão. Obrigatório: sim. Tipo: string UUID.
+ `Lambda-Extension-Function-Error-Type`: tipo de erro encontrado pela extensão. Obrigatório: sim. Este cabeçalho consiste em um valor de string. Lambda aceita qualquer string, mas recomendamos o formato . Por exemplo:
+ Extension.NoSuchHandler
+ Extension.APIKeyNotFound
+ Extension.ConfigInvalid
+ Extension.UnknownReason
**Parâmetros do corpo da solicitação**
+ `ErrorRequest`: informações adicionais sobre o erro. Obrigatório: não
Este campo é um objeto JSON com a seguinte estrutura:
```
{
errorMessage: string (text description of the error),
errorType: string,
stackTrace: array of strings
}
```
Observe que o Lambda aceita qualquer valor para `errorType`.
O exemplo a seguir mostra uma mensagem de erro de função do Lambda na qual a função não pôde analisar os dados do evento fornecidos na chamada.
**Example Erro de função**
```
{
"errorMessage" : "Error parsing event data.",
"errorType" : "InvalidEventDataException",
"stackTrace": [ ]
}
```
**Códigos de resposta**
+ 202: aceito
+ 400: solicitação inválida
+ 403: proibido
+ 500: erro de contêiner. Estado não recuperável. A extensão deve sair imediatamente.
# Acessar dados de telemetria em tempo real para extensões usando a API Telemetria
A API de Telemetria permite que as extensões recebam dados de telemetria diretamente do Lambda. Durante a inicialização e a invocação da função, o Lambda captura automaticamente a telemetria, incluindo logs, métricas de plataforma e rastreamentos de plataforma. A API de telemetria permite que as extensões acessem esses dados de telemetria diretamente no Lambda e quase em tempo real.
No ambiente de execução do Lambda, você pode inscrever as extensões do Lambda em fluxos de telemetria. Após a inscrição, o Lambda transmite automaticamente todos os dados de telemetria para as extensões. Você então tem a flexibilidade de processar, filtrar e despachar os dados para o destino de sua preferência, como um bucket do Amazon Simple Storage Service (Amazon S3) ou um provedor externo de ferramentas de observabilidade.
O diagrama a seguir mostra como a API de extensões e a API de telemetria conectam extensões ao Lambda no ambiente de execução. Além disso, a API de runtime conecta o seu runtime e a função ao Lambda.
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/telemetry-api-concept-diagram.png)
**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.
**Requisito de versão do esquema de instâncias gerenciadas do Lambda**
As instâncias gerenciadas do Lambda oferecem suporte somente à versão `2025-01-29` do esquema da API de telemetria. Ao assinar fluxos de telemetria para funções de instância gerenciada, você **deve** usar `"schemaVersion": "2025-01-29"` em sua solicitação de assinatura. O uso de versões anteriores do esquema resultará na rejeição de eventos pelo Lambda.
A versão `2025-01-29` do esquema é compatível com versões anteriores e pode ser usada com instâncias gerenciadas do Lambda e funções do Lambda (padrão). Recomendamos usar essa versão para todas as novas extensões para garantir a compatibilidade entre os dois modelos de implantação.
As extensões podem usar a API de telemetria para se inscrever em três fluxos de telemetria diferentes:
+ **Telemetria de plataforma**: logs, métricas e rastreamentos que descrevem eventos e erros relacionados ao ciclo de vida de runtime do ambiente de execução, ao ciclo de vida de extensão e às invocações de função.
+ **Logs de função**: logs personalizados gerados pelo código da função do Lambda.
+ **Logs de extensão**: logs personalizados gerados pelo código de extensão do Lambda.
**nota**
O Lambda enviará logs e métricas para o CloudWatch e rastreará para o X-Ray (se você ativou o rastreamento), mesmo que uma extensão assine fluxos de telemetria.
**Topics**
+ [Criação de extensões usando a API de telemetria](#telemetry-api-creating-extensions)
+ [Como registrar sua extensão](#telemetry-api-registration)
+ [Como criar um receptor de telemetria](#telemetry-api-listener)
+ [Como especificar um protocolo de destino](#telemetry-api-destination)
+ [Como configurar o uso de memória e o armazenamento em buffer](#telemetry-api-buffering)
+ [Como enviar uma solicitação de assinatura para a API de telemetria](#telemetry-api-subscription)
+ [Mensagens da API de telemetria de entrada](#telemetry-api-messages)
+ [Referência da API de Telemetria do Lambda](telemetry-api-reference.md)
+ [Referência de esquema para `Event` da API de Telemetria do Lambda](telemetry-schema-reference.md)
+ [Conversão de objetos `Event` da API de Telemetria do Lambda em spans do OpenTelemetry](telemetry-otel-spans.md)
+ [Usar a API de logs do Lambda](runtimes-logs-api.md)
## Criação de extensões usando a API de telemetria
As extensões do Lambda são executadas como processos independentes no ambiente de execução. As extensões podem continuar sendo executadas após a conclusão da invocação da função. Como as extensões são processos separados, é possível escrevê-las em uma linguagem diferente do código da função. Recomendamos a gravação de extensões usando uma linguagem compilada, como Golang ou Rust. Dessa forma, a extensão corresponde a um binário independente que pode ser compatível com qualquer runtime com suporte.
O diagrama a seguir ilustra um processo de quatro etapas para a criação de uma extensão que recebe e processa dados de telemetria usando a API de telemetria.
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/telemetry-api-creation-steps.png)
Veja a seguir cada etapa com mais detalhes:
1. Registre sua extensão usando a [Usar a API de extensões do Lambda para criar extensões](runtimes-extensions-api.md). Isso fornece um `Lambda-Extension-Identifier`, que você precisará para as etapas a seguir. Para obter mais informações sobre como registrar sua extensão, consulte [Como registrar sua extensão](#telemetry-api-registration).
1. Crie um receptor de telemetria. Pode ser um servidor HTTP ou TCP comum. O Lambda usa o URI do receptor de telemetria para enviar dados de telemetria para a extensão. Para obter mais informações, consulte [Como criar um receptor de telemetria](#telemetry-api-listener).
1. Use a API de inscrição na API de telemetria para inscrever a extensão nos fluxos de telemetria desejados. Você precisará do URI do receptor de telemetria para esta etapa. Para obter mais informações, consulte [Como enviar uma solicitação de assinatura para a API de telemetria](#telemetry-api-subscription).
1. Obtenha os dados de telemetria do Lambda por meio do receptor de telemetria. É possível fazer qualquer processamento personalizado desses dados, como enviar os dados para o Amazon S3 ou para um serviço de observabilidade externo.
**nota**
O ambiente de execução de uma função do Lambda pode ser iniciado e interrompido diversas vezes como parte de seu [ciclo de vida](runtimes-extensions-api.md#runtimes-extensions-api-lifecycle). Em geral, o código de extensão é executado durante as invocações de função e também por até dois segundos durante a fase de desligamento. Recomendamos processar a telemetria em lotes à medida que ela chegar ao receptor. Em seguida, use os eventos de ciclo de vida `Invoke` e `Shutdown` para enviar cada lote aos destinos desejados.
## Como registrar sua extensão
Antes de se inscrever em dados de telemetria, você deve registrar a extensão do Lambda. O registro ocorre durante a [fase de inicialização da extensão](runtimes-extensions-api.md#runtimes-extensions-api-reg). O exemplo a seguir mostra uma solicitação HTTP para registrar uma extensão.
```
POST http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register
Lambda-Extension-Name: lambda_extension_name
{
'events': [ 'INVOKE', 'SHUTDOWN']
}
```
Se o pedido for bem-sucedido, o assinante receberá uma resposta de êxito HTTP 200. O cabeçalho de resposta contém o `Lambda-Extension-Identifier`. O corpo de resposta contém outras propriedades da função.
```
HTTP/1.1 200 OK
Lambda-Extension-Identifier: a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
{
"functionName": "lambda_function",
"functionVersion": "$LATEST",
"handler": "lambda_handler",
"accountId": "123456789012"
}
```
Para obter mais informações, consulte a [Referência de API de extensões](runtimes-extensions-api.md#runtimes-extensions-registration-api).
## Como criar um receptor de telemetria
Sua extensão do Lambda deve ter um receptor que processe as solicitações recebidas da API de telemetria. O código a seguir mostra um exemplo de implementação de receptor de telemetria em Golang:
```
// Starts the server in a goroutine where the log events will be sent
func (s *TelemetryApiListener) Start() (string, error) {
address := listenOnAddress()
l.Info("[listener:Start] Starting on address", address)
s.httpServer = &http.Server{Addr: address}
http.HandleFunc("/", s.http_handler)
go func() {
err := s.httpServer.ListenAndServe()
if err != http.ErrServerClosed {
l.Error("[listener:goroutine] Unexpected stop on Http Server:", err)
s.Shutdown()
} else {
l.Info("[listener:goroutine] Http Server closed:", err)
}
}()
return fmt.Sprintf("http://%s/", address), nil
}
// http_handler handles the requests coming from the Telemetry API.
// Everytime Telemetry API sends log events, this function will read them from the response body
// and put into a synchronous queue to be dispatched later.
// Logging or printing besides the error cases below is not recommended if you have subscribed to
// receive extension logs. Otherwise, logging here will cause Telemetry API to send new logs for
// the printed lines which may create an infinite loop.
func (s *TelemetryApiListener) http_handler(w http.ResponseWriter, r *http.Request) {
body, err := ioutil.ReadAll(r.Body)
if err != nil {
l.Error("[listener:http_handler] Error reading body:", err)
return
}
// Parse and put the log messages into the queue
var slice []interface{}
_ = json.Unmarshal(body, &slice)
for _, el := range slice {
s.LogEventsQueue.Put(el)
}
l.Info("[listener:http_handler] logEvents received:", len(slice), " LogEventsQueue length:", s.LogEventsQueue.Len())
slice = nil
}
```
## Como especificar um protocolo de destino
Ao se inscrever para receber telemetria usando a API de telemetria, é possível especificar um protocolo de destino além do URI de destino:
```
{
"destination": {
"protocol": "HTTP",
"URI": "http://sandbox.localdomain:8080"
}
}
```
O Lambda aceita dois protocolos para o recebimento de telemetria:
+ **HTTP (recomendado)**: o Lambda fornece telemetria para um endpoint HTTP local (`http://sandbox.localdomain:${PORT}/${PATH}`) como uma matriz de registros no formato JSON. O parâmetro `$PATH` é opcional. O Lambda oferece suporte somente para HTTP, não para HTTPS. O Lambda fornece telemetria por meio de solicitações POST.
+ **TCP**: o Lambda fornece telemetria para uma porta TCP no [formato Newline delimited JSON (NDJSON)](https://github.com/ndjson/ndjson-spec).
**nota**
Recomendamos fortemente o uso de HTTP em vez de TCP. Com o TCP, a plataforma do Lambda não reconhece que a telemetria é entregue à camada da aplicação. Portanto, se sua extensão falhar, você poderá perder a telemetria. O HTTP não tem essa limitação.
Antes de se inscrever para receber telemetria, estabeleça o receptor HTTP ou a porta TCP local. Durante a configuração, observe o seguinte:
+ O Lambda envia telemetria somente para destinos que estão dentro do ambiente de execução.
+ O Lambda tenta novamente enviar telemetria (com recuo) na ausência de um receptor ou se a solicitação POST encontrar algum erro. Se o receptor de telemetria apresentar falhas, ele continuará a receber telemetria 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.
## Como configurar o uso de memória e o armazenamento em buffer
O uso de memória em um ambiente de execução cresce linearmente com o número de assinantes. As assinaturas consomem recursos de memória porque cada assinatura abre um novo buffer de memória para armazenar dados de telemetria. O uso da memória buffer contribui para o consumo geral de memória no ambiente de execução.
Ao se inscrever para receber telemetria usando a API de telemetria, você tem a opção de armazenar em buffer os dados de telemetria e entregá-los aos assinantes em lotes. Para otimizar o uso da memória, é possível especificar uma configuração de armazenamento em buffer:
```
{
"buffering": {
"maxBytes": 256*1024,
"maxItems": 1000,
"timeoutMs": 100
}
}
```
| Parameter | Descrição | Padrões e limites |
| --- | --- | --- |
| `maxBytes` | O volume máximo de telemetria (em bytes) para armazenar 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 para armazenar em buffer na memória. | Padrão: 10.000 Mínimo: 1.000 Máximo: 10.000. |
| `timeoutMs` | O tempo máximo (em milissegundos) para armazenar em buffer um lote. | Padrão: 1.000 Mínimo: 25 Máximo: 30.000 |
Ao configurar o buffer, lembre-se dos seguintes pontos:
+ Se algum dos fluxos de entrada estiver fechado, o Lambda liberará os logs. Por exemplo, isso pode acontecer se o runtime apresentar falhas.
+ Cada assinante pode personalizar a configuração de buffer durante a solicitação de assinatura.
+ Ao determinar o tamanho do buffer para ler os dados, preveja o recebimento de cargas úteis tão grandes quanto `2 * maxBytes + metadataBytes`, em que `maxBytes` é um componente da configuração de buffer. Para avaliar a quantidade de `metadataBytes` a ser considerada, analise os metadados a seguir. O Lambda anexa metadados semelhantes a este para cada registro:
```
{
"time": "2022-08-20T12:31:32.123Z",
"type": "function",
"record": "Hello World"
}
```
+ Se o assinante não puder processar a telemetria de entrada com rapidez suficiente ou se o código da sua função gerar um volume de log muito alto, o Lambda poderá descartar registros para manter a utilização da memória limitada. Quando isso ocorre, o Lambda envia um evento `platform.logsDropped`.
## Como enviar uma solicitação de assinatura para a API de telemetria
As extensões do Lambda podem se inscrever para receber dados de telemetria enviando uma solicitação de assinatura para a API de telemetria. A solicitação de assinatura deve conter informações sobre os tipos de eventos que você deseja que a extensão assine. Além disso, a solicitação pode conter [informações do destino de entrega](#telemetry-api-destination) e uma [configuração de armazenamento em buffer](#telemetry-api-buffering).
Antes de enviar uma solicitação de assinatura, você deve ter um ID de extensão (`Lambda-Extension-Identifier`). Ao [registrar sua extensão na API de extensões](#telemetry-api-registration), você obtém um ID de extensão a partir da resposta da API.
A assinatura ocorre durante a [fase de inicialização da extensão](runtimes-extensions-api.md#runtimes-extensions-api-reg). O exemplo a seguir mostra uma solicitação HTTP para assinar todos os três fluxos de telemetria: telemetria de plataforma, logs de função e logs de extensão.
```
PUT http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry HTTP/1.1
{
"schemaVersion": "2025-01-29",
"types": [
"platform",
"function",
"extension"
],
"buffering": {
"maxItems": 1000,
"maxBytes": 256*1024,
"timeoutMs": 100
},
"destination": {
"protocol": "HTTP",
"URI": "http://sandbox.localdomain:8080"
}
}
```
Se a solicitação tiver êxito, o assinante receberá uma resposta de êxito HTTP 200.
```
HTTP/1.1 200 OK
"OK"
```
## Mensagens da API de telemetria de entrada
Depois de se inscrever usando a API de telemetria, uma extensão começa automaticamente a receber telemetria do Lambda por meio de solicitações POST. Cada corpo de solicitação POST contém uma matriz de objetos `Event`. Cada `Event` tem o seguinte esquema:
```
{
time: String,
type: String,
record: Object
}
```
+ A propriedade `time` define quando a plataforma do Lambda gerou o evento. Isso é diferente de quando o evento realmente ocorreu. O valor da string `time` é um carimbo de data/hora no formato ISO 8601.
+ A propriedade `type` define o tipo de evento. A tabela a seguir descreve todos os valores possíveis.
+ A propriedade `record` define um objeto JSON que contém os dados de telemetria. O esquema desse objeto JSON depende do arquivo `type`.
**Ordenação de eventos com invocações simultâneas**
Em [Instâncias gerenciadas do Lambda](lambda-managed-instances.md), várias invocações de função podem ser executadas simultaneamente no mesmo ambiente de execução. Nesse caso, a ordem dos eventos `platform.start` e `platform.report` não é garantida entre diferentes invocações simultâneas. As extensões devem lidar com eventos de várias invocações executadas em paralelo e não devem assumir uma ordenação sequencial.
Para atribuir eventos adequadamente a invocações específicas, as extensões devem usar o campo `requestId` presente nesses eventos da plataforma. Cada invocação tem um ID de solicitação exclusivo que permanece consistente em todos os eventos dessa invocação, permitindo que as extensões correlacionem os eventos corretamente mesmo quando eles chegam fora de ordem.
A tabela a seguir resume todos os tipos de objetos `Event` e apresenta links para a [referência de esquema `Event` da API de telemetria](telemetry-schema-reference.md) para cada tipo de evento.
| Categoria | Tipo de evento | Descrição | Esquema de registro de evento |
| --- | --- | --- | --- |
| Evento de plataforma | `platform.initStart` | A inicialização da função foi iniciada. | Esquema [`platform.initStart`](telemetry-schema-reference.md#platform-initStart) |
| Evento de plataforma | `platform.initRuntimeDone` | A inicialização da função foi concluída. | Esquema [`platform.initRuntimeDone`](telemetry-schema-reference.md#platform-initRuntimeDone) |
| Evento de plataforma | `platform.initReport` | Um relatório sobre a inicialização da função. | Esquema [`platform.initReport`](telemetry-schema-reference.md#platform-initReport) |
| Evento de plataforma | `platform.start` | A invocação da função foi iniciada. | Esquema [`platform.start`](telemetry-schema-reference.md#platform-start) |
| Evento de plataforma | `platform.runtimeDone` | O runtime concluiu o processamento de um evento com êxito ou com falha. | Esquema [`platform.runtimeDone`](telemetry-schema-reference.md#platform-runtimeDone) |
| Evento de plataforma | `platform.report` | Um relatório sobre a invocação de função. | Esquema [`platform.report`](telemetry-schema-reference.md#platform-report) |
| Evento de plataforma | `platform.restoreStart` | A restauração do runtime foi iniciada. | Esquema [`platform.restoreStart`](telemetry-schema-reference.md#platform-restoreStart) |
| Evento de plataforma | `platform.restoreRuntimeDone` | A restauração do runtime foi concluída. | Esquema [`platform.restoreRuntimeDone`](telemetry-schema-reference.md#platform-restoreRuntimeDone) |
| Evento de plataforma | `platform.restoreReport` | Relatório de restauração do runtime. | Esquema [`platform.restoreReport`](telemetry-schema-reference.md#platform-restoreReport) |
| Evento de plataforma | `platform.telemetrySubscription` | A extensão foi inscrita na API de telemetria. | Esquema [`platform.telemetrySubscription`](telemetry-schema-reference.md#platform-telemetrySubscription) |
| Evento de plataforma | `platform.logsDropped` | O Lambda descartou entradas de log. | Esquema [`platform.logsDropped`](telemetry-schema-reference.md#platform-logsDropped) |
| Logs de função | `function` | Uma linha de log do código da função. | Esquema [`function`](telemetry-schema-reference.md#telemetry-api-function) |
| Logs de extensões | `extension` | Uma linha de log do código de extensão. | Esquema [`extension`](telemetry-schema-reference.md#telemetry-api-extension) |
# Referência da API de Telemetria do Lambda
Use o endpoint da API de Telemetria do Lambda para assinar extensões para fluxos de telemetria. É possível recuperar o endpoint da API de telemetria da variável de ambiente `AWS_LAMBDA_RUNTIME_API`. Para enviar uma solicitação de API, vincule a versão da API (`2022-07-01/`) e `telemetry/`. Por exemplo:
```
http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry/
```
Para obter a definição da Especificação OpenAPI (OAS) da versão das respostas de assinatura `2025-01-29`, consulte os itens a seguir:
+ **HTTP**: [telemetry-api-http-schema.zip](samples/events_http_schema_v2025_01_29.zip)
+ **TCP**: [telemetry-api-tcp-schema.zip](samples/events_tcp_schema_v2025_01_29.zip)
**Topics**
+ [Assinar](#telemetry-subscribe-api)
## Assinar
Para assinar um fluxo de telemetria, uma extensão do Lambda pode enviar uma solicitação para a API de assinatura.
+ **Caminho** – `/telemetry`
+ **Method** (Método): `PUT`
+ **Cabeçalhos**
+ `Content-Type`: `application/json`
+ **Parâmetros do corpo da solicitação**
+ **schemaVersion**
+ Obrigatório: Sim
+ Tipo: string
+ Valores válidos: `"2025-01-29"`, `"2022-12-13"` ou `"2022-07-01"`
+ **Observação:** as instâncias gerenciadas do Lambda exigem `"2025-01-29"`. Esta versão é compatível com versões anteriores das funções do Lambda (padrão).
+ **destination** (destino): as configurações que definem o destino do evento de telemetria e o protocolo para a entrega do evento.
+ Obrigatório: sim
+ Tipo: Objeto
```
{
"protocol": "HTTP",
"URI": "http://sandbox.localdomain:8080"
}
```
+ **protocol** (protocolo): o protocolo usado pelo Lambda para enviar dados de telemetria.
+ Obrigatório: Sim
+ Tipo: string
+ Valores válidos: `"HTTP"`\$1`"TCP"`
+ **URI**: o URI para o qual os dados de telemetria serão enviados.
+ Obrigatório: Sim
+ Tipo: string
+ Para obter mais informações, consulte [Como especificar um protocolo de destino](telemetry-api.md#telemetry-api-destination).
+ **types** (tipos): os tipos de telemetria que você deseja que a extensão assine.
+ Obrigatório: sim
+ Tipo: matriz de strings
+ Valores válidos: `"platform"`\$1`"function"`\$1`"extension"`
+ **buffering** (armazenamento em buffer): as configurações definidas para o armazenamento em buffer de eventos.
+ Obrigatório: não
+ Tipo: Objeto
```
{
"buffering": {
"maxItems": 1000,
"maxBytes": 256*1024,
"timeoutMs": 100
}
}
```
+ **maxItems**: o número máximo de eventos a serem colocados em buffer na memória.
+ Obrigatório: não
+ Tipo: inteiro
+ Padrão: 1.000
+ Mínimo: 1.000
+ Máximo: 10.000.
+ **maxBytes**: o volume máximo de telemetria (em bytes) para armazenar em buffer na memória.
+ Obrigatório: não
+ Tipo: inteiro
+ Padrão: 262.144
+ Mínimo: 262.144
+ Máximo: 1.048.576
+ **timeoutMs**: o tempo máximo (em milissegundos) para colocar um lote em buffer.
+ Obrigatório: não
+ Tipo: inteiro
+ Padrão: 1.000
+ Mínimo: 25
+ Máximo: 30.000
+ Para obter mais informações, consulte [Como configurar o uso de memória e o armazenamento em buffer](telemetry-api.md#telemetry-api-buffering).
### Exemplo de solicitação para a API de assinatura
```
PUT http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry HTTP/1.1
{
"schemaVersion": "2025-01-29",
"types": [
"platform",
"function",
"extension"
],
"buffering": {
"maxItems": 1000,
"maxBytes": 256*1024,
"timeoutMs": 100
},
"destination": {
"protocol": "HTTP",
"URI": "http://sandbox.localdomain:8080"
}
}
```
Se a solicitação de assinatura obtiver êxito, a extensão receberá uma resposta de êxito HTTP 200:
```
HTTP/1.1 200 OK
"OK"
```
Se a solicitação de assinatura falhar, a extensão receberá uma resposta de erro. Por exemplo:
```
HTTP/1.1 400 OK
{
"errorType": "ValidationError",
"errorMessage": "URI port is not provided; types should not be empty"
}
```
Veja a seguir alguns códigos de resposta adicionais que a extensão pode receber:
+ 200: solicitação concluída com êxito
+ 202: solicitação aceita. Resposta à solicitação de assinatura no ambiente de teste local.
+ 400: solicitação inválida.
+ 500: erro do serviço
# Referência de esquema para `Event` da API de Telemetria do Lambda
Use o endpoint da API de Telemetria do Lambda para assinar extensões para fluxos de telemetria. É possível recuperar o endpoint da API de telemetria da variável de ambiente `AWS_LAMBDA_RUNTIME_API`. Para enviar uma solicitação de API, vincule a versão da API (`2022-07-01/`) e `telemetry/`. Por exemplo:
```
http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry/
```
Para obter a definição da Especificação OpenAPI (OAS) da versão das respostas de assinatura `2025-01-29`, consulte os itens a seguir:
+ **HTTP**: [telemetry-api-http-schema.zip](samples/events_http_schema_v2025_01_29.zip)
+ **TCP**: [telemetry-api-tcp-schema.zip](samples/events_tcp_schema_v2025_01_29.zip)
A tabela a seguir é um resumo de todos os tipos de objetos `Event` aos quais a API de telemetria oferece suporte.
| Categoria | Tipo de evento | Descrição | Esquema de registro de evento |
| --- | --- | --- | --- |
| Evento de plataforma | `platform.initStart` | A inicialização da função foi iniciada. | Esquema [`platform.initStart`](#platform-initStart) |
| Evento de plataforma | `platform.initRuntimeDone` | A inicialização da função foi concluída. | Esquema [`platform.initRuntimeDone`](#platform-initRuntimeDone) |
| Evento de plataforma | `platform.initReport` | Um relatório sobre a inicialização da função. | Esquema [`platform.initReport`](#platform-initReport) |
| Evento de plataforma | `platform.start` | A invocação da função foi iniciada. | Esquema [`platform.start`](#platform-start) |
| Evento de plataforma | `platform.runtimeDone` | O runtime concluiu o processamento de um evento com êxito ou com falha. | Esquema [`platform.runtimeDone`](#platform-runtimeDone) |
| Evento de plataforma | `platform.report` | Um relatório sobre a invocação de função. | Esquema [`platform.report`](#platform-report) |
| Evento de plataforma | `platform.restoreStart` | A restauração do runtime foi iniciada. | Esquema [`platform.restoreStart`](#platform-restoreStart) |
| Evento de plataforma | `platform.restoreRuntimeDone` | A restauração do runtime foi concluída. | Esquema [`platform.restoreRuntimeDone`](#platform-restoreRuntimeDone) |
| Evento de plataforma | `platform.restoreReport` | Relatório de restauração do runtime. | Esquema [`platform.restoreReport`](#platform-restoreReport) |
| Evento de plataforma | `platform.telemetrySubscription` | A extensão foi inscrita na API de telemetria. | Esquema [`platform.telemetrySubscription`](#platform-telemetrySubscription) |
| Evento de plataforma | `platform.logsDropped` | O Lambda descartou entradas de log. | Esquema [`platform.logsDropped`](#platform-logsDropped) |
| Logs de função | `function` | Uma linha de log do código da função. | Esquema [`function`](#telemetry-api-function) |
| Logs de extensões | `extension` | Uma linha de log do código de extensão. | Esquema [`extension`](#telemetry-api-extension) |
**Contents**
+ [Tipos de objeto `Event` da API de telemetria](#telemetry-api-events)
+ [`platform.initStart`](#platform-initStart)
+ [`platform.initRuntimeDone`](#platform-initRuntimeDone)
+ [`platform.initReport`](#platform-initReport)
+ [`platform.start`](#platform-start)
+ [`platform.runtimeDone`](#platform-runtimeDone)
+ [`platform.report`](#platform-report)
+ [`platform.restoreStart`](#platform-restoreStart)
+ [`platform.restoreRuntimeDone`](#platform-restoreRuntimeDone)
+ [`platform.restoreReport`](#platform-restoreReport)
+ [`platform.extension`](#platform-extension)
+ [`platform.telemetrySubscription`](#platform-telemetrySubscription)
+ [`platform.logsDropped`](#platform-logsDropped)
+ [`function`](#telemetry-api-function)
+ [`extension`](#telemetry-api-extension)
+ [Tipos de objetos compartilhados](#telemetry-api-objects)
+ [`InitPhase`](#InitPhase)
+ [`InitReportMetrics`](#InitReportMetrics)
+ [`InitType`](#InitType)
+ [`ReportMetrics`](#ReportMetrics)
+ [`RestoreReportMetrics`](#RestoreReportMetrics)
+ [`RuntimeDoneMetrics`](#RuntimeDoneMetrics)
+ [`Span`](#Span)
+ [`Status`](#Status)
+ [`TraceContext`](#TraceContext)
+ [`TracingType`](#TracingType)
## Tipos de objeto `Event` da API de telemetria
Esta seção detalha os tipos de objetos `Event` aos quais a API de Telemetria do Lambda oferece suporte. Nas descrições dos eventos, um ponto de interrogação (`?`) indica que o atributo pode não estar presente no objeto.
### `platform.initStart`
Um evento `platform.initStart` indica que a fase de inicialização da função foi iniciada. Um objeto `Event` `platform.initStart` tem a forma a seguir:
```
Event: Object
- time: String
- type: String = platform.initStart
- record: PlatformInitStart
```
O objeto `PlatformInitStart` tem os seguintes atributos:
+ **functionName** – `String`
+ **functionVersion**: `String`
+ **initializationType**: objeto ``InitType``
+ **instanceId?**: `String`
+ **instanceMaxMemory?**: `Integer`
+ **phase** (fase): objeto ``InitPhase``
+ **runtimeVersion?** – `String`
+ **runtimeVersionArn?** – `String`
Veja a seguir um exemplo de `Event` do tipo `platform.initStart`:
```
{
"time": "2022-10-12T00:00:15.064Z",
"type": "platform.initStart",
"record": {
"initializationType": "on-demand",
"phase": "init",
"runtimeVersion": "nodejs-14.v3",
"runtimeVersionArn": "arn",
"functionName": "myFunction",
"functionVersion": "$LATEST",
"instanceId": "82561ce0-53dd-47d1-90e0-c8f5e063e62e",
"instanceMaxMemory": 256
}
}
```
### `platform.initRuntimeDone`
Um evento `platform.initRuntimeDone` indica que a fase de inicialização da função foi concluída. Um objeto `Event` `platform.initRuntimeDone` tem a forma a seguir:
```
Event: Object
- time: String
- type: String = platform.initRuntimeDone
- record: PlatformInitRuntimeDone
```
O objeto `PlatformInitRuntimeDone` tem os seguintes atributos:
+ **initializationType**: objeto ``InitType``
+ **phase** (fase): objeto ``InitPhase``
+ **status**: objeto ``Status``
+ **spans?** : lista de objetos ``Span``
Veja a seguir um exemplo de `Event` do tipo `platform.initRuntimeDone`:
```
{
"time": "2022-10-12T00:01:15.000Z",
"type": "platform.initRuntimeDone",
"record": {
"initializationType": "on-demand"
"status": "success",
"spans": [
{
"name": "someTimeSpan",
"start": "2022-06-02T12:02:33.913Z",
"durationMs": 70.5
}
]
}
}
```
### `platform.initReport`
Um evento `platform.initReport` contém um relatório geral da fase de inicialização da função. Um objeto `Event` `platform.initReport` tem a forma a seguir:
```
Event: Object
- time: String
- type: String = platform.initReport
- record: PlatformInitReport
```
O objeto `PlatformInitReport` tem os seguintes atributos:
+ **errorType?**: string
+ **initializationType**: objeto ``InitType``
+ **phase** (fase): objeto ``InitPhase``
+ **metrics** (métricas): objeto ``InitReportMetrics``
+ **spans?** : lista de objetos ``Span``
+ **status**: objeto ``Status``
Veja a seguir um exemplo de `Event` do tipo `platform.initReport`:
```
{
"time": "2022-10-12T00:01:15.000Z",
"type": "platform.initReport",
"record": {
"initializationType": "on-demand",
"status": "success",
"phase": "init",
"metrics": {
"durationMs": 125.33
},
"spans": [
{
"name": "someTimeSpan",
"start": "2022-06-02T12:02:33.913Z",
"durationMs": 90.1
}
]
}
}
```
### `platform.start`
Um evento `platform.start` indica que a fase de invocação da função foi iniciada. Um objeto `Event` `platform.start` tem a forma a seguir:
```
Event: Object
- time: String
- type: String = platform.start
- record: PlatformStart
```
O objeto `PlatformStart` tem os seguintes atributos:
+ **requestId** – `String`
+ **version?** – `String`
+ **tracing?** – ``TraceContext``
Veja a seguir um exemplo de `Event` do tipo `platform.start`:
```
{
"time": "2022-10-12T00:00:15.064Z",
"type": "platform.start",
"record": {
"requestId": "6d68ca91-49c9-448d-89b8-7ca3e6dc66aa",
"version": "$LATEST",
"tracing": {
"spanId": "54565fb41ac79632",
"type": "X-Amzn-Trace-Id",
"value": "Root=1-62e900b2-710d76f009d6e7785905449a;Parent=0efbd19962d95b05;Sampled=1"
}
}
}
```
### `platform.runtimeDone`
Um evento `platform.runtimeDone` indica que a fase de invocação da função foi concluída. Um objeto `Event` `platform.runtimeDone` tem a forma a seguir:
**Instâncias gerenciadas do Lambda**
Não há suporte para o evento `platform.runtimeDone` em instâncias gerenciadas do Lambda. As extensões executadas em instâncias gerenciadas não receberão esse evento porque as extensões não podem se inscrever no evento `INVOKE` em instâncias gerenciadas. Devido ao modelo de execução simultânea em que várias invocações podem ser processadas simultaneamente, as extensões não podem realizar o processamento pós-invocação para invocações individuais, como acontece tradicionalmente nas funções do Lambda (padrão).
Em instâncias gerenciadas, as extensões `responseLatency` e `responseDuration` que normalmente são incluídas em `platform.runtimeDone` estão disponíveis no evento `platform.report`. Para mais detalhes, consulte [`platform.report`](#platform-report).
```
Event: Object
- time: String
- type: String = platform.runtimeDone
- record: PlatformRuntimeDone
```
O objeto `PlatformRuntimeDone` tem os seguintes atributos:
+ **errorType?** – `String`
+ **metrics?**: objeto ``RuntimeDoneMetrics``
+ **requestId** – `String`
+ **status**: objeto ``Status``
+ **spans?** : lista de objetos ``Span``
+ **tracing?**: objeto ``TraceContext``
Veja a seguir um exemplo de `Event` do tipo `platform.runtimeDone`:
```
{
"time": "2022-10-12T00:01:15.000Z",
"type": "platform.runtimeDone",
"record": {
"requestId": "6d68ca91-49c9-448d-89b8-7ca3e6dc66aa",
"status": "success",
"tracing": {
"spanId": "54565fb41ac79632",
"type": "X-Amzn-Trace-Id",
"value": "Root=1-62e900b2-710d76f009d6e7785905449a;Parent=0efbd19962d95b05;Sampled=1"
},
"spans": [
{
"name": "someTimeSpan",
"start": "2022-08-02T12:01:23:521Z",
"durationMs": 80.0
}
],
"metrics": {
"durationMs": 140.0,
"producedBytes": 16
}
}
}
```
### `platform.report`
Um evento `platform.report` contém um relatório geral da fase de invocação da função. Um objeto `Event` `platform.report` tem a forma a seguir:
**Instâncias gerenciadas do Lambda**
O evento `platform.report` para instâncias gerenciadas do Lambda tem métricas e extensões diferentes em comparação com as funções do Lambda (padrão). Para instâncias gerenciadas
**Extensões**: contém `responseLatency` e `responseDuration` em vez de `extensionOverhead`. A extensão `extensionOverhead` não está disponível porque as extensões não podem assinar o evento em `INVOKE` em instâncias gerenciadas devido ao modelo de execução simultânea.
**Métricas**: inclui apenas `durationMs`. As métricas a seguir não estão incluídas: `billedDurationMs`, `initDurationMs`, `maxMemoryUsedMB` e `memorySizeMB`. Essas métricas por invocação não são aplicáveis no ambiente de execução simultânea. Para métricas de utilização de recursos, use [Monitoramento de instâncias gerenciadas do Lambda](lambda-managed-instances-monitoring.md) ou o [Lambda Insights](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-insights.html).
```
Event: Object
- time: String
- type: String = platform.report
- record: PlatformReport
```
O objeto `PlatformReport` tem os seguintes atributos:
+ **metrics** (métricas): objeto ``ReportMetrics``
+ **requestId** – `String`
+ **spans?** : lista de objetos ``Span``
+ **status**: objeto ``Status``
+ **tracing?**: objeto ``TraceContext``
Veja a seguir um exemplo de `Event` do tipo `platform.report`:
```
{
"time": "2022-10-12T00:01:15.000Z",
"type": "platform.report",
"record": {
"metrics": {
"billedDurationMs": 694,
"durationMs": 693.92,
"initDurationMs": 397.68,
"maxMemoryUsedMB": 84,
"memorySizeMB": 128
},
"requestId": "6d68ca91-49c9-448d-89b8-7ca3e6dc66aa",
}
}
```
### `platform.restoreStart`
Um evento `platform.restoreStart` indica que um evento de restauração do ambiente de função foi iniciado. Em um evento de restauração do ambiente, o Lambda cria o ambiente de um snapshot armazenado em cache, em vez de inicializá-lo do zero. Para obter mais informações, consulte [Lambda SnapStart](snapstart.md). Um objeto `Event` `platform.restoreStart` tem a forma a seguir:
```
Event: Object
- time: String
- type: String = platform.restoreStart
- record: PlatformRestoreStart
```
O objeto `PlatformRestoreStart` tem os seguintes atributos:
+ **functionName** – `String`
+ **functionVersion** – `String`
+ **instanceId?** – `String`
+ **instanceMaxMemory?** – `String`
+ **runtimeVersion?** – `String`
+ **runtimeVersionArn?** – `String`
Veja a seguir um exemplo de `Event` do tipo `platform.restoreStart`:
```
{
"time": "2022-10-12T00:00:15.064Z",
"type": "platform.restoreStart",
"record": {
"runtimeVersion": "nodejs-14.v3",
"runtimeVersionArn": "arn",
"functionName": "myFunction",
"functionVersion": "$LATEST",
"instanceId": "82561ce0-53dd-47d1-90e0-c8f5e063e62e",
"instanceMaxMemory": 256
}
}
```
### `platform.restoreRuntimeDone`
Um evento `platform.restoreRuntimeDone` indica que um evento de restauração do ambiente de função foi concluído. Em um evento de restauração do ambiente, o Lambda cria o ambiente de um snapshot armazenado em cache, em vez de inicializá-lo do zero. Para obter mais informações, consulte [Lambda SnapStart](snapstart.md). Um objeto `Event` `platform.restoreRuntimeDone` tem a forma a seguir:
```
Event: Object
- time: String
- type: String = platform.restoreRuntimeDone
- record: PlatformRestoreRuntimeDone
```
O objeto `PlatformRestoreRuntimeDone` tem os seguintes atributos:
+ **errorType?** – `String`
+ **spans?** : lista de objetos ``Span``
+ **status**: objeto ``Status``
Veja a seguir um exemplo de `Event` do tipo `platform.restoreRuntimeDone`:
```
{
"time": "2022-10-12T00:00:15.064Z",
"type": "platform.restoreRuntimeDone",
"record": {
"status": "success",
"spans": [
{
"name": "someTimeSpan",
"start": "2022-08-02T12:01:23:521Z",
"durationMs": 80.0
}
]
}
}
```
### `platform.restoreReport`
Um evento `platform.restoreReport` contém um relatório geral de um evento de restauração de função. Um objeto `Event` `platform.restoreReport` tem a forma a seguir:
```
Event: Object
- time: String
- type: String = platform.restoreReport
- record: PlatformRestoreReport
```
O objeto `PlatformRestoreReport` tem os seguintes atributos:
+ **errorType?**: string
+ **metrics?**: objeto ``RestoreReportMetrics``
+ **spans?** : lista de objetos ``Span``
+ **status**: objeto ``Status``
Veja a seguir um exemplo de `Event` do tipo `platform.restoreReport`:
```
{
"time": "2022-10-12T00:00:15.064Z",
"type": "platform.restoreReport",
"record": {
"status": "success",
"metrics": {
"durationMs": 15.19
},
"spans": [
{
"name": "someTimeSpan",
"start": "2022-08-02T12:01:23:521Z",
"durationMs": 30.0
}
]
}
}
```
### `platform.extension`
Um evento `extension` contém logs do código de extensão. Um objeto `Event` `extension` tem a forma a seguir:
```
Event: Object
- time: String
- type: String = extension
- record: {}
```
O objeto `PlatformExtension` tem os seguintes atributos:
+ **events** (eventos): lista de `String`
+ **name (nome** – `String`
+ **state (estado** – `String`
Veja a seguir um exemplo de `Event` do tipo `platform.extension`:
```
{
"time": "2022-10-12T00:02:15.000Z",
"type": "platform.extension",
"record": {
"events": [ "INVOKE", "SHUTDOWN" ],
"name": "my-telemetry-extension",
"state": "Ready"
}
}
```
### `platform.telemetrySubscription`
Um evento `platform.telemetrySubscription` contém informações sobre uma assinatura de extensão. Um objeto `Event` `platform.telemetrySubscription` tem a forma a seguir:
```
Event: Object
- time: String
- type: String = platform.telemetrySubscription
- record: PlatformTelemetrySubscription
```
O objeto `PlatformTelemetrySubscription` tem os seguintes atributos:
+ **name (nome** – `String`
+ **state (estado** – `String`
+ **types** (tipos): lista de `String`
Veja a seguir um exemplo de `Event` do tipo `platform.telemetrySubscription`:
```
{
"time": "2022-10-12T00:02:35.000Z",
"type": "platform.telemetrySubscription",
"record": {
"name": "my-telemetry-extension",
"state": "Subscribed",
"types": [ "platform", "function" ]
}
}
```
### `platform.logsDropped`
Um evento `platform.logsDropped` contém informações sobre eventos descartados. O Lambda emite o evento `platform.logsDropped` quando uma função gera logs em uma taxa muito alta para o Lambda processá-los. Quando o Lambda não consegue enviar logs para o CloudWatch ou para a extensão inscrita na API Telemetry na velocidade em que a função os produz, ele descarta logs para impedir que a execução da função fique mais lenta. Um objeto `Event` `platform.logsDropped` tem a forma a seguir:
```
Event: Object
- time: String
- type: String = platform.logsDropped
- record: PlatformLogsDropped
```
O objeto `PlatformLogsDropped` tem os seguintes atributos:
+ **droppedBytes** – `Integer`
+ **droppedRecords** – `Integer`
+ **reason (razão** – `String`
Veja a seguir um exemplo de `Event` do tipo `platform.logsDropped`:
```
{
"time": "2022-10-12T00:02:35.000Z",
"type": "platform.logsDropped",
"record": {
"droppedBytes": 12345,
"droppedRecords": 123,
"reason": "Some logs were dropped because the downstream consumer is slower than the logs production rate"
}
}
```
### `function`
Um evento `function` contém logs do código da função. Um objeto `Event` `function` tem a forma a seguir:
```
Event: Object
- time: String
- type: String = function
- record: {}
```
O formato do campo `record` vai variar dependendo se os logs da função estão em formato de texto simples ou JSON. Para saber mais sobre as opções de configuração de formato de logs, consulte [Configurar logs em formato de texto simples e JSON](monitoring-cloudwatchlogs-logformat.md).
Veja abaixo um exemplo de `Event` de tipo `function` em que o log está formatado em texto simples:
```
{
"time": "2022-10-12T00:03:50.000Z",
"type": "function",
"record": "[INFO] Hello world, I am a function!"
}
```
Veja abaixo um exemplo de `Event` de tipo `function` em que o log está formatado em JSON:
```
{
"time": "2022-10-12T00:03:50.000Z",
"type": "function",
"record": {
"timestamp": "2022-10-12T00:03:50.000Z",
"level": "INFO",
"requestId": "79b4f56e-95b1-4643-9700-2807f4e68189",
"message": "Hello world, I am a function!"
}
}
```
**nota**
Se a versão do esquema que você está usando for mais antiga que a versão `2022-12-13`, o campo `"record"` será sempre renderizado como uma string, mesmo se o formato do log da função estiver configurado como JSON. Para instâncias gerenciadas do Lambda, é necessário usar a versão `2025-01-29` do esquema.
### `extension`
Um evento `extension` contém logs do código de extensão. Um objeto `Event` `extension` tem a forma a seguir:
```
Event: Object
- time: String
- type: String = extension
- record: {}
```
O formato do campo `record` vai variar dependendo se os logs da função estão em formato de texto simples ou JSON. Para saber mais sobre as opções de configuração de formato de logs, consulte [Configurar logs em formato de texto simples e JSON](monitoring-cloudwatchlogs-logformat.md).
Veja abaixo um exemplo de `Event` de tipo `extension` em que o log está formatado em texto simples:
```
{
"time": "2022-10-12T00:03:50.000Z",
"type": "extension",
"record": "[INFO] Hello world, I am an extension!"
}
```
Veja abaixo um exemplo de `Event` de tipo `extension` em que o log está formatado em JSON:
```
{
"time": "2022-10-12T00:03:50.000Z",
"type": "extension",
"record": {
"timestamp": "2022-10-12T00:03:50.000Z",
"level": "INFO",
"requestId": "79b4f56e-95b1-4643-9700-2807f4e68189",
"message": "Hello world, I am an extension!"
}
}
```
**nota**
Se a versão do esquema que você está usando for mais antiga que a versão `2022-12-13`, o campo `"record"` será sempre renderizado como uma string, mesmo se o formato do log da função estiver configurado como JSON. Para instâncias gerenciadas do Lambda, é necessário usar a versão `2025-01-29` do esquema.
## Tipos de objetos compartilhados
Esta seção detalha os tipos de objetos compartilhados aos quais a API de Telemetria do Lambda oferece suporte.
### `InitPhase`
Uma enumeração da string que descreve a fase em que ocorre a etapa de inicialização. Na maioria dos casos, o Lambda executa o código de inicialização da função durante a fase `init`. No entanto, em alguns casos de erro, o Lambda pode executar novamente o código de inicialização da função durante a fase `invoke`. (Isso é chamado de *suppressed init* [inicialização suprimida]).
+ **Tipo** – `String`
+ **Valores válidos** – `init`\$1`invoke`\$1`snap-start`
### `InitReportMetrics`
Um objeto que contém as métricas sobre uma fase de inicialização.
+ **Tipo** – `Object`
Um objeto `InitReportMetrics` tem a forma a seguir:
```
InitReportMetrics: Object
- durationMs: Double
```
Veja a seguir um exemplo de um objeto `InitReportMetrics`:
```
{
"durationMs": 247.88
}
```
### `InitType`
Uma enumeração de string que descreve como o Lambda inicializou o ambiente.
+ **Tipo** – `String`
+ **Valores válidos** – `on-demand`\$1`provisioned-concurrency`
### `ReportMetrics`
Um objeto que contém métricas sobre uma fase concluída.
+ **Tipo** – `Object`
Um objeto `ReportMetrics` tem a forma a seguir:
```
ReportMetrics: Object
- billedDurationMs: Integer
- durationMs: Double
- initDurationMs?: Double
- maxMemoryUsedMB: Integer
- memorySizeMB: Integer
- restoreDurationMs?: Double
```
Veja a seguir um exemplo de um objeto `ReportMetrics`:
```
{
"billedDurationMs": 694,
"durationMs": 693.92,
"initDurationMs": 397.68,
"maxMemoryUsedMB": 84,
"memorySizeMB": 128
}
```
### `RestoreReportMetrics`
Um objeto que contém métricas sobre uma fase de restauração concluída.
+ **Tipo** – `Object`
Um objeto `RestoreReportMetrics` tem a forma a seguir:
```
RestoreReportMetrics: Object
- durationMs: Double
```
Veja a seguir um exemplo de um objeto `RestoreReportMetrics`:
```
{
"durationMs": 15.19
}
```
### `RuntimeDoneMetrics`
Um objeto que contém métricas sobre uma fase de invocação.
+ **Tipo** – `Object`
Um objeto `RuntimeDoneMetrics` tem a forma a seguir:
```
RuntimeDoneMetrics: Object
- durationMs: Double
- producedBytes?: Integer
```
Veja a seguir um exemplo de um objeto `RuntimeDoneMetrics`:
```
{
"durationMs": 200.0,
"producedBytes": 15
}
```
### `Span`
Um objeto que contém detalhes sobre um span. Um span representa uma unidade de trabalho ou de operação em um rastreamento. Para obter mais informações sobre os spans, consulte [Span](https://opentelemetry.io/docs/reference/specification/trace/api/#span) na página **Tracing API** (API de rastreamento) do site OpenTelemetry Docs.
O Lambda é compatível com os seguintes spans para o evento `platform.RuntimeDone`:
+ O span `responseLatency` descreve quanto tempo sua função do Lambda demorou para começar a enviar a resposta.
+ O span `responseDuration` descreve quanto tempo sua função do Lambda demorou para concluir o envio da resposta completa.
+ O span `runtimeOverhead` descreve quanto tempo levou para o runtime do Lambda sinalizar que está pronto para processar a próxima invocação da função. Esse é o tempo que o runtime levou para chamar a [próxima API de invocação](runtimes-api.md#runtimes-api-next) para obter o próximo evento após retornar a resposta da função.
Veja a seguir um exemplo de um objeto do span `responseLatency`:
```
{
"name": "responseLatency",
"start": "2022-08-02T12:01:23.521Z",
"durationMs": 23.02
}
```
### `Status`
Um objeto que descreve o status de uma fase de inicialização ou invocação. Se o status for `failure` ou`error`, o objeto `Status` também conterá um campo `errorType` com a descrição do erro.
+ **Tipo** – `Object`
+ **Valores de status válidos** – `success`\$1`failure`\$1`error`\$1`timeout`
### `TraceContext`
Um objeto que descreve as propriedades de um rastreamento.
+ **Tipo** – `Object`
Um objeto `TraceContext` tem a forma a seguir:
```
TraceContext: Object
- spanId?: String
- type: TracingType enum
- value: String
```
Veja a seguir um exemplo de um objeto `TraceContext`:
```
{
"spanId": "073a49012f3c312e",
"type": "X-Amzn-Trace-Id",
"value": "Root=1-62e900b2-710d76f009d6e7785905449a;Parent=0efbd19962d95b05;Sampled=1"
}
```
### `TracingType`
Uma enumeração de string que descreve o tipo de rastreamento em um objeto ``TraceContext``.
+ **Tipo** – `String`
+ **Valores válidos** – `X-Amzn-Trace-Id`
# Conversão de objetos `Event` da API de Telemetria do Lambda em spans do OpenTelemetry
O esquema da API de telemetria do AWS Lambda é semanticamente compatível com o OpenTelemetry (OTel). Isso significa que é possível converter os objetos `Event` da API de telemetria do AWS Lambda em spans do OpenTelemetry (OTel). Ao converter, você não deve mapear um único objeto `Event` para um único span do OTel. Em vez disso, você deve apresentar todos os três eventos relacionados a uma fase do ciclo de vida em um único span do OTel. Por exemplo, os eventos `start`, `runtimeDone` e `runtimeReport` representam uma única invocação de função. Apresente todos esses três eventos como um único span do OTel.
É possível converter seus eventos usando “Span Events” (Eventos de span) ou “Child Spans” (aninhado) (Spans secundários). As tabelas nesta página descrevem os mapeamentos entre as propriedades do esquema da API de telemetria e as propriedades do span do OTel para ambas as abordagens. Para obter mais informações sobre os spans do OTel, consulte [Span](https://opentelemetry.io/docs/reference/specification/trace/api/#span) na página **Tracing API** (API de rastreamento) do site OpenTelemetry Docs.
**Topics**
+ [Mapeamento para spans do OTel com “Span Events” (Eventos de span)](#telemetry-otel-span-events)
+ [Mapeamento para spans do OTel com “Child Spans” (Spans secundários)](#telemetry-otel-child-spans)
## Mapeamento para spans do OTel com “Span Events” (Eventos de span)
Nas tabelas a seguir, `e` representa o evento proveniente da fonte de telemetria.
**Mapeando os eventos \$1Start**
| OpenTelemetry | Esquema da API de Telemetria do Lambda |
| --- | --- |
| `Span.Name` | Sua extensão gera esse valor com base no campo `type`. |
| `Span.StartTime` | Use `e.time`. |
| `Span.EndTime` | N/A, porque o evento ainda não foi concluído. |
| `Span.Kind` | Definir como `Server`. |
| `Span.Status` | Definir como `Unset`. |
| `Span.TraceId` | Analise o cabeçalho do AWS X-Ray encontrado em `e.tracing.value` e, em seguida, use o valor `TraceId`. |
| `Span.ParentId` | Analise o cabeçalho do X-Ray encontrado em `e.tracing.value` e, em seguida, use o valor `Parent`. |
| `Span.SpanId` | Use `e.tracing.spanId`, se disponível. Caso contrário, gere um novo `SpanId`. |
| `Span.SpanContext.TraceState` | N/A para um contexto de rastreamento do X-Ray. |
| `Span.SpanContext.TraceFlags` | Analise o cabeçalho do X-Ray encontrado em `e.tracing.value` e, em seguida, use o valor `Sampled`. |
| `Span.Attributes` | Sua extensão pode adicionar quaisquer valores personalizados aqui. |
**Mapeando os eventos \$1RuntimeDone**
| OpenTelemetry | Esquema da API de Telemetria do Lambda |
| --- | --- |
| `Span.Name` | Sua extensão gera o valor com base no campo `type`. |
| `Span.StartTime` | Use `e.time` a partir do evento `*Start` correspondente. Como alternativa, use `e.time - e.metrics.durationMs`. |
| `Span.EndTime` | N/A, porque o evento ainda não foi concluído. |
| `Span.Kind` | Definir como `Server`. |
| `Span.Status` | Se `e.status` não for igual a `success`, defina como `Error`. Caso contrário, defina como `Ok`. |
| `Span.Events[]` | Use `e.spans[]`. |
| `Span.Events[i].Name` | Use `e.spans[i].name`. |
| `Span.Events[i].Time` | Use `e.spans[i].start`. |
| `Span.TraceId` | Analise o cabeçalho do AWS X-Ray encontrado em `e.tracing.value` e, em seguida, use o valor `TraceId`. |
| `Span.ParentId` | Analise o cabeçalho do X-Ray encontrado em `e.tracing.value` e, em seguida, use o valor `Parent`. |
| `Span.SpanId` | Use o mesmo `SpanId` do evento `*Start`. Se não estiver disponível, use `e.tracing.spanId` ou gere um novo `SpanId`. |
| `Span.SpanContext.TraceState` | N/A para um contexto de rastreamento do X-Ray. |
| `Span.SpanContext.TraceFlags` | Analise o cabeçalho do X-Ray encontrado em `e.tracing.value` e, em seguida, use o valor `Sampled`. |
| `Span.Attributes` | Sua extensão pode adicionar quaisquer valores personalizados aqui. |
**Mapeando os eventos \$1Report events**
| OpenTelemetry | Esquema da API de Telemetria do Lambda |
| --- | --- |
| `Span.Name` | Sua extensão gera o valor com base no campo `type`. |
| `Span.StartTime` | Use `e.time` a partir do evento `*Start` correspondente. Como alternativa, use `e.time - e.metrics.durationMs`. |
| `Span.EndTime` | Use `e.time`. |
| `Span.Kind` | Definir como `Server`. |
| `Span.Status` | Use o mesmo valor do evento `*RuntimeDone`. |
| `Span.TraceId` | Analise o cabeçalho do AWS X-Ray encontrado em `e.tracing.value` e, em seguida, use o valor `TraceId`. |
| `Span.ParentId` | Analise o cabeçalho do X-Ray encontrado em `e.tracing.value` e, em seguida, use o valor `Parent`. |
| `Span.SpanId` | Use o mesmo `SpanId` do evento `*Start`. Se não estiver disponível, use `e.tracing.spanId` ou gere um novo `SpanId`. |
| `Span.SpanContext.TraceState` | N/A para um contexto de rastreamento do X-Ray. |
| `Span.SpanContext.TraceFlags` | Analise o cabeçalho do X-Ray encontrado em `e.tracing.value` e, em seguida, use o valor `Sampled`. |
| `Span.Attributes` | Sua extensão pode adicionar quaisquer valores personalizados aqui. |
## Mapeamento para spans do OTel com “Child Spans” (Spans secundários)
A tabela a seguir descreve como converter eventos da API de Telemetria do Lambda em spans do OTel com “Child Spans” (aninhado) (Spans secundários) para spans `*RuntimeDone`. Para mapeamentos `*Start` e `*Report`, consulte as tabelas em [Mapeamento para spans do OTel com “Span Events” (Eventos de span)](#telemetry-otel-span-events), pois elas são semelhantes para “Child Spans” (Spans secundários). Nesta tabela, `e` representa o evento proveniente da fonte de telemetria.
**Mapeando os eventos \$1RuntimeDone**
| OpenTelemetry | Esquema da API de Telemetria do Lambda |
| --- | --- |
| `Span.Name` | Sua extensão gera o valor com base no campo `type`. |
| `Span.StartTime` | Use `e.time` a partir do evento `*Start` correspondente. Como alternativa, use `e.time - e.metrics.durationMs`. |
| `Span.EndTime` | N/A, porque o evento ainda não foi concluído. |
| `Span.Kind` | Definir como `Server`. |
| `Span.Status` | Se `e.status` não for igual a `success`, defina como `Error`. Caso contrário, defina como `Ok`. |
| `Span.TraceId` | Analise o cabeçalho do AWS X-Ray encontrado em `e.tracing.value` e, em seguida, use o valor `TraceId`. |
| `Span.ParentId` | Analise o cabeçalho do X-Ray encontrado em `e.tracing.value` e, em seguida, use o valor `Parent`. |
| `Span.SpanId` | Use o mesmo `SpanId` do evento `*Start`. Se não estiver disponível, use `e.tracing.spanId` ou gere um novo `SpanId`. |
| `Span.SpanContext.TraceState` | N/A para um contexto de rastreamento do X-Ray. |
| `Span.SpanContext.TraceFlags` | Analise o cabeçalho do X-Ray encontrado em `e.tracing.value` e, em seguida, use o valor `Sampled`. |
| `Span.Attributes` | Sua extensão pode adicionar quaisquer valores personalizados aqui. |
| `ChildSpan[i].Name` | Use `e.spans[i].name`. |
| `ChildSpan[i].StartTime` | Use `e.spans[i].start`. |
| `ChildSpan[i].EndTime` | Use `e.spans[i].start + e.spans[i].durations`. |
| `ChildSpan[i].Kind` | Semelhante ao principal `Span.Kind`. |
| `ChildSpan[i].Status` | Semelhante ao principal `Span.Status`. |
| `ChildSpan[i].TraceId` | Semelhante ao principal `Span.TraceId`. |
| `ChildSpan[i].ParentId` | Use o principal `Span.SpanId`. |
| `ChildSpan[i].SpanId` | Gere um novo `SpanId`. |
| `ChildSpan[i].SpanContext.TraceState` | N/A para um contexto de rastreamento do X-Ray. |
| `ChildSpan[i].SpanContext.TraceFlags` | Semelhante ao principal `Span.SpanContext.TraceFlags`. |
# 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"
}
}
```