Instrumentação do código Go no AWS Lambda

O Lambda se integra ao AWS X-Ray para ajudar você a rastrear, depurar e otimizar aplicações do Lambda. É possível usar o X-Ray para rastrear uma solicitação enquanto ela atravessa recursos na aplicação, o que pode incluir funções Lambda e outros produtos da AWS.

Para enviar dados de rastreamento ao X-Ray, você pode usar uma das duas bibliotecas SDK:

• AWS Distro for OpenTelemetry (ADOT): uma distribuição segura, pronta para produção e com suporte na AWS do SDK OpenTelemetry (OTel).

• AWS X-Ray SDK para Go: um SDK para geração e envio de dados de rastreamento ao X-Ray.

Cada um dos SDKs oferece maneiras de enviar dados de telemetria ao serviço do X-Ray. Em seguida, é possível usar o X-Ray para visualizar, filtrar e obter insights sobre as métricas de performance da aplicação para identificar problemas e oportunidades de otimização.

Importante

Os SDKs do X-Ray e do Powertools para AWS Lambda fazem parte de uma solução de instrumentação totalmente integrada oferecida pela AWS. As camadas do Lambda para ADOT fazem parte de um padrão em todo o setor para instrumentação de rastreamento que coleta mais dados em geral, mas pode não ser adequado para todos os casos de uso. É possível implementar o rastreamento de ponta a ponta no X-Ray usando ambas as soluções. Para saber mais sobre como escolher entre elas, consulte Como escolher entre os SDKs do AWS Distro para OpenTelemetry e do X-Ray.

Usar o ADOT para instrumentar funções Go

O ADOT fornece camadas do Lambda totalmente gerenciadas que empacotam tudo o que você precisa para coletar dados de telemetria usando o SDK do OTel. Ao consumir essa camada, é possível instrumentar suas funções Lambda sem precisar modificar nenhum código de função. Você também pode configurar sua camada para fazer a inicialização personalizada do OTel. Para obter mais informações, consulte Custom configuration for the ADOT Collector on Lambda (Configuração personalizada para o ADOT Collector no Lambda) na documentação do ADOT.

Para runtimes Go, você pode adicionar a camada do Lambda gerenciada pela AWS para ADOT Go a fim de instrumentar suas funções automaticamente. Para obter instruções detalhadas sobre como adicionar essa camada, consulte Suporte do AWS Distro for OpenTelemetry Lambda para Go, na documentação do ADOT.

Usar o SDK do X-Ray para instrumentar suas funções Go

Para registrar detalhes sobre as chamadas feitas pela sua função do Lambda para outros recursos na sua aplicação, você também pode usar o AWS X-Ray SDK para Go. Para obter o SDK, baixe-o do Repositório do GitHub com go get:

go get github.com/aws/aws-xray-sdk-go

Para instrumentar clientes do AWS SDK, passe o cliente para o método xray.AWS(). Em seguida, você pode rastrear chamadas usando a versão WithContext do método.

svc := s3.New(session.New())
xray.AWS(svc.Client)
...
svc.ListBucketsWithContext(ctx aws.Context, input *ListBucketsInput)

Depois de adicionar as dependências corretas e fazer as devidas mudanças de código, ative o rastreamento na configuração da sua função usando o console do Lambda ou a API.

Ativar o rastreamento com o console do Lambda

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 do console do Lambda.

2. Escolha uma função.

3. Escolha Configuration (Configuração) e depois Monitoring and operations tools (Ferramentas de monitoramento e operações).

4. Selecione a opção Editar.

5. Em X-Ray, ative a opção Active tracing (Rastreamento ativo).

6. Escolha Salvar.

Ativar o rastreamento com a API do Lambda

Configure o rastreamento na sua função do Lambda com aAWS CLI ou o AWS SDK, usando as seguintes operações de API:

• UpdateFunctionConfiguration

• GetFunctionConfiguration

• CreateFunction

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.

Ativar o rastreamento com o AWS CloudFormation

Para ativar o rastreamento ativo em um recurso AWS::Lambda::Function em um modelo do AWS CloudFormation, use a propriedade TracingConfig.

exemplo function-inline.yml: configuração de rastreamento

Resources:
  function:
    Type: AWS::Lambda::Function
    Properties:
      TracingConfig:
        Mode: Active
      ...

Para um recurso do AWS Serverless Application Model (AWS SAM) AWS::Serverless::Function, use a propriedade Tracing.

exemplo template.yml: configuração de rastreamento

Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      Tracing: Active
      ...

Interpretar um rastreamento do X-Ray

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 da função. Caso contrário, adicione a política AWSXRayDaemonWriteAccess à função de execução.

Após configurar o rastreamento ativo, você pode observar solicitações específicas por meio da aplicação. O grafo de serviço do X-Ray exibe informações sobre sua aplicação e todos os componentes. O exemplo a seguir mostra uma aplicação com duas funções. A função principal processa eventos e, às vezes, retorna erros. A segunda função de cima para baixo processa erros que aparecem no primeiro grupo de logs e usa o AWS SDK para chamar o X-Ray, o Amazon Simple Storage Service (Amazon S3) e o Amazon CloudWatch Logs.

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 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:

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 exemplo a seguir mostra um rastreamento com esses dois segmentos. 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.

Este exemplo expande o segmento AWS::Lambda::Function para mostrar seus três subsegmentos.

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.

O exemplo de rastreamento mostrado aqui ilustra o segmento de função no estilo antigo. As diferenças entre os segmentos no estilo antigo e no estilo novo são descritas nos próximos parágrafos.

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.

O segmento de função no estilo antigo contém os seguintes subsegmentos:

• Inicialização: representa o tempo gasto carregando a função e executando o código de inicialização. Esse subsegmento aparece somente para o primeiro evento que cada instância da função processa.

• Invocação: representa o tempo gasto na execução do código do manipulador.

• Sobrecarga: representa o tempo gasto pelo runtime do Lambda preparando-se para lidar com o próximo evento.

O segmento de função no estilo novo não contém um subsegmento Invocation. Em vez disso, os subsegmentos dos clientes são anexados diretamente ao segmento da função. Para obter mais informações sobre a estrutura dos segmentos de função no estilo antigo e no estilo novo, consulte Noções básicas sobre rastreamentos do X-Ray.

Você também pode instrumentar clientes HTTP, registrar consultas SQL e criar subsegmentos personalizados com anotações e metadados. Para obter mais informações, consulte AWS X-Ray SDK para Go, no Guia do desenvolvedor do AWS X-Ray.

Definição de preço

Você pode usar o rastreamento do X-Ray gratuitamente todos os meses até determinado limite como parte do nível gratuito da AWS. Além do limite, o X-Ray cobra por armazenamento e recuperação de rastreamento. Para obter mais informações, consulte Preços do AWS X-Ray.