# Visualizar as invocações da função do Lambda usando o AWS X-Ray
Você pode usar o AWS X-Ray para visualizar os componentes do aplicativo, identificar gargalos de performance e solucionar problemas de solicitações que resultaram em um erro. Suas funções do Lambda enviam dados de rastreamento para o X-Ray, e o X-Ray processa os dados para gerar um mapa de serviço e resumos de rastreamento pesquisáveis.
O Lambda aceita dois modos de rastreamento para o X-Ray: `Active` e `PassThrough`. Com o rastreamento `Active`, o Lambda cria automaticamente segmentos de rastreamento para invocações de funções e os envia para o X-Ray. O modo `PassThrough`, por outro lado, simplesmente propaga o contexto de rastreamento para os serviços subsequentes. Se você tiver habilitado o rastreamento `Active` para a função, o Lambda enviará automaticamente rastreamentos para o X-Ray para solicitações amostradas. Normalmente, um serviço antecedente, como o Amazon API Gateway, ou uma aplicação hospedada no Amazon EC2 que é instrumentada com o SDK do X-Ray, decide se as solicitações recebidas devem ser rastreadas, depois adiciona essa decisão de amostragem como um cabeçalho de rastreamento. O Lambda usa esse cabeçalho para decidir enviar ou não rastreamentos. Os rastreamentos de produtores de mensagens upstream, como o Amazon SQS, são vinculados automaticamente aos rastreamentos de funções do Lambda downstream, o que cria uma visão completa de toda a aplicação. Para obter mais informações, consulte [Tracing event-driven applications](https://docs.aws.amazon.com//xray/latest/devguide/xray-tracelinking.html) (Rastreamento de aplicações orientadas a eventos) no *Guia do desenvolvedor do AWS X-Ray*.
**nota**
Atualmente, o rastreamento do X-Ray não oferece suporte a funções do Lambda com o Amazon Managed Streaming for Apache Kafka (Amazon MSK), Apache Kafka autogerenciado, Amazon MQ com ActiveMQ e RabbitMQ ou mapeamentos da origem do evento do Amazon DocumentDB.
Para alternar o rastreamento ativo na sua função do Lambda usando o console, siga as etapas abaixo:
**Para ativar o rastreamento ativo**
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 **Configuration** (Configuração) e depois **Monitoring and operations tools** (Ferramentas de monitoramento e operações).
1. Em **Ferramentas de monitoramento adicionais**, selecione **Editar**.
1. Em **CloudWatch Application Signals e AWS X-Ray**, escolha **Habilitar** para **Rastreamentos do serviço Lambda**.
1. Escolha **Salvar**.
Sua função precisa de permissão para carregar dados de rastreamento no X-Ray. Quando você ativa o rastreamento ativo no console do Lambda, o Lambda adiciona as permissões necessárias à [função de execução](lambda-intro-execution-role.md) da função. Caso contrário, adicione a política [AWSXRayDaemonWriteAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess) à função de execução.
O X-Ray não rastreia todas as solicitações para sua aplicação. O X-Ray aplica um algoritmo de amostragem para garantir que o rastreamento seja eficiente, enquanto ainda fornece uma amostra representativa das solicitações. A taxa de amostragem é uma solicitação por segundo e 5% de solicitações adicionais. Você não pode configurar a taxa de amostragem do X-Ray para suas funções.
## Noções básicas sobre rastreamentos do X-Ray
No X-Ray, um *rastreamento* registra informações sobre uma solicitação que é processada por um ou mais *serviços*. O Lambda registra dois segmentos por rastreamento, o que cria dois nós no gráfico de serviços. A imagem a seguir destaca esses dois nós:
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/xray-servicemap-function.png)
O primeiro nó à esquerda representa o serviço do Lambda, que recebe a solicitação de invocação. O segundo nó representa a sua função do Lambda específica.
O segmento registrado para o serviço Lambda, `AWS::Lambda`, abrange todas as etapas necessárias para preparar o ambiente de execução do Lambda. Isso inclui agendar o microVM, criar ou descongelar um ambiente de execução com os recursos que você configurou e baixar o código e todas as camadas da função .
O segmento `AWS::Lambda::Function` é para o trabalho realizado pela função.
**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.
Essa alteração afeta os subsegmentos do segmento da função. Os parágrafos a seguir descrevem o formato antigo e formato novo desses subsegmentos.
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.
**Estrutura de segmentos do Lambda AWS X-Ray no estilo antigo**
A estrutura do X-Ray no estilo antigo para o segmento `AWS::Lambda` é assim:
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/V2_sandbox_images/v1_XRay_structure.png)
Nesse formato, o segmento da função tem subsegmentos para `Initialization`, `Invocation` e `Overhead`. Somente para [Lambda SnapStart](snapstart.md), existe também um subsegmento `Restore` (não mostrado nesse diagrama).
O subsegmento `Initialization` representa a fase inicial do ciclo de vida do ambiente de execução do Lambda. Durante essa fase, Lambda inicializa as extensões, inicializa o runtime e executa o código de inicialização da função.
O subsegmento `Invocation` representa a fase de chamada em que o Lambda chama o manipulador de função. Isso começa com o registro do runtime e da extensão e termina quando o runtime está pronto para enviar a resposta.
(Lambda SnapStart apenas) O subsegmento `Restore` mostra o tempo necessário para o Lambda restaurar um snapshot, carregar o runtime e executar todos os [hooks de runtime](snapstart-runtime-hooks.md) after-restore. O processo de restauração de snapshots pode incluir o tempo gasto em atividades fora da MicroVM. Esse tempo é relatado no subsegmento `Restore`. Você não é cobrado pelo tempo gasto fora da microVM para restaurar um snapshot.
O subsegmento `Overhead` representa a fase que ocorre entre o momento em que o runtime envia a resposta e o sinal para a próxima chamada. Durante esse período, o runtime termina todas as tarefas relacionadas a uma chamada e se prepara para congelar o sandbox.
**Importante**
Você pode usar o SDK do X-Ray para estender o subsegmento `Invocation` com subsegmentos adicionais para anotações, metadados e chamadas downstream. Não é possível acessar o segmento de função diretamente nem registrar trabalhos feitos fora do escopo de chamada do manipulador.
Para obter mais informações sobre as fases do ambiente de execução do Lambda, consulte [Noções básicas sobre o ciclo de vida do ambiente de execução do Lambda](lambda-runtime-environment.md).
Um exemplo de rastreamento usando a estrutura de X-Ray no estilo antigo é mostrado no diagrama a seguir.
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/V2_sandbox_images/my-function-2-v1.png)
Observe os dois segmentos do exemplo. Ambos têm o nome **my-function**, mas um tem a origem `AWS::Lambda` e o outro, a origem `AWS::Lambda::Function`. Se o segmento `AWS::Lambda` mostrar um erro, o serviço Lambda teve um problema. Se o segmento `AWS::Lambda::Function` mostrar um erro, sua função teve um problema.
**nota**
Ocasionalmente, é possível notar um grande intervalo entre as fases de inicialização e de invocação da função em seus rastreamentos do X-Ray. Para as funções que usam a [simultaneidade provisionada](provisioned-concurrency.md), isso ocorre pelo Lambda inicializar as instâncias de função com bastante antecedência à invocação. Para as funções que usam a [simultaneidade não reservada (sob demanda)](lambda-concurrency.md), o Lambda pode inicializar proativamente uma instância de função, mesmo que não haja invocação. Visualmente, ambos os casos apresentam um intervalo de tempo entre as fases de inicialização e de invocação.
**Estrutura de segmentos AWS X-Ray do Lambda no estilo novo**
A estrutura do X-Ray no estilo novo para o segmento `AWS::Lambda` é assim:
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/V2_sandbox_images/v2_XRay_structure.png)
Nesse novo formato, o subsegmento `Init` representa a fase de inicialização do ciclo de vida do ambiente de execução do Lambda.
Não há segmento de invocação no novo formato. Em vez disso, os subsegmentos dos clientes são anexados diretamente ao segmento `AWS::Lambda::Function`. Esse segmento contém as seguintes métricas como anotações:
+ `aws.responseLatency`: o tempo necessário para a função ser executada
+ `aws.responseDuration`: o tempo necessário para transferir a resposta para o cliente
+ `aws.runtimeOverhead`: o tempo adicional de que o runtime precisou para ser concluído
+ `aws.extensionOverhead`: o tempo adicional de que as extensões precisaram para serem concluídas
Um exemplo de rastreamento usando a estrutura de X-Ray no estilo novo é mostrado no diagrama a seguir.
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/V2_sandbox_images/my-function-2-v2.png)
Observe os dois segmentos do exemplo. Ambos têm o nome **my-function**, mas um tem a origem `AWS::Lambda` e o outro, a origem `AWS::Lambda::Function`. Se o segmento `AWS::Lambda` mostrar um erro, o serviço Lambda teve um problema. Se o segmento `AWS::Lambda::Function` mostrar um erro, sua função teve um problema.
Consulte os tópicos a seguir para obter uma introdução específica de uma linguagem ao rastreamento no Lambda:
+ [Instrumentação do código Node.js no AWS Lambda](nodejs-tracing.md)
+ [Instrumentação do código Python no AWS Lambda](python-tracing.md)
+ [Instrumentar o código Ruby no AWS Lambda](ruby-tracing.md)
+ [Instrumentação do código Java no AWS Lambda](java-tracing.md)
+ [Instrumentação do código Go no AWS Lambda](golang-tracing.md)
+ [Instrumentar o código C \$1 no AWS Lambda](csharp-tracing.md)
Para obter uma lista completa de serviços que oferecem suporte à instrumentação ativa, consulte [Serviços da AWS compatíveis](https://docs.aws.amazon.com/xray/latest/devguide/xray-usage.html#xray-usage-codechanges) no Guia do desenvolvedor do AWS X-Ray.
## Comportamento de rastreamento padrão do Lambda
Se você não tiver ativado o rastreamento `Active`, o Lambda usará o modo de rastreamento `PassThrough` por padrão.
No modo `PassThrough`, o Lambda encaminha o cabeçalho de rastreamento do X-Ray para os serviços subsequentes, mas não envia os rastreamentos automaticamente. Isso ocorre mesmo que o cabeçalho de rastreamento contenha uma decisão de amostrar a solicitação. Se o serviço antecedente não fornecer um cabeçalho de rastreamento do X-Ray, o Lambda gerará um cabeçalho e tomará a decisão de não fazer a amostragem. Porém, você pode enviar seus próprios rastreamentos chamando bibliotecas de rastreamento no código da função.
**nota**
Anteriormente, o Lambda enviava rastreamentos automaticamente quando os serviços antecedentes, como o Amazon API Gateway, adicionavam um cabeçalho de rastreamento. Não enviando rastreamentos automaticamente, o Lambda dá a você o controle para rastrear as funções que considerar importantes para si. Se a solução depender desse comportamento de rastreamento passivo, alterne para o rastreamento `Active`.
## Permissões da função de execução
O Lambda precisa das permissões a seguir para enviar dados de rastreamento para o X-Ray. Adicione-as à [função de execução](lambda-intro-execution-role.md) da sua função.
+ [xray:PutTraceSegments](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)
+ [xray:PutTelemetryRecords](https://docs.aws.amazon.com/xray/latest/api/API_PutTelemetryRecords.html)
Essas permissões estão incluídas na política gerenciada [AWSXRayDaemonWriteAccess](https://console.aws.amazon.com/iam/home?#/policies/arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess).
## Habilitar o rastreamento `Active` com a API do Lambda
Para gerenciar a configuração de rastreamento com a AWS CLI ou com o AWS SDK, use as seguintes operações de API:
+ [UpdateFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateFunctionConfiguration.html)
+ [GetFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_GetFunctionConfiguration.html)
+ [CreateFunction](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html)
O exemplo de comando da AWS CLI a seguir habilita o rastreamento ativo em uma função chamada **my-function**.
```
aws lambda update-function-configuration --function-name my-function \
--tracing-config Mode=Active
```
O modo de rastreamento faz parte da configuração específica da versão quando você publica uma versão da função. Não é possível alterar o modo de rastreamento em uma versão publicada.
## Habilitar o rastreamento `Active` com o CloudFormation
Para ativar o rastreamento ativo em um recurso `AWS::Lambda::Function` em um modelo do CloudFormation, use a propriedade `TracingConfig`.
**Example [function-inline.yml](https://github.com/awsdocs/aws-lambda-developer-guide/blob/master/templates/function-inline.yml): configuração de rastreamento**
```
Resources:
function:
Type: [AWS::Lambda::Function](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html)
Properties:
TracingConfig:
Mode: Active
...
```
Para um recurso do AWS Serverless Application Model (AWS SAM) `AWS::Serverless::Function`, use a propriedade `Tracing`.
**Example [template.yml](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-nodejs/template.yml): configuração de rastreamento**
```
Resources:
function:
Type: [AWS::Serverless::Function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html)
Properties:
Tracing: Active
...
```