Instrumentar o código Ruby no AWS Lambda

O Lambda se integra ao AWS X-Ray para permitir que você rastreie, depure e otimize aplicativos do Lambda. É possível usar o X-Ray para rastrear uma solicitação à medida que ela atravessa recursos na aplicação, da API de frontend ao armazenamento e aos banco de dados no backend. Ao simplesmente adicionar a biblioteca do X-Ray SDK à configuração de compilação, é possível registrar erros e latência para qualquer chamada que a função faça para um serviço da AWS.

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.

Para alternar o rastreamento ativo na sua função do Lambda usando o console, siga as etapas abaixo:

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.

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.

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

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.

É possível instrumentar o código do manipulador para gravar metadados e rastrear chamadas downstream. Para registrar detalhes sobre chamadas feitas pelo manipulador para outros recursos e serviços, use o X-Ray SDK for Ruby. Para obter o SDK, adicione o pacote aws-xray-sdk às dependências do aplicativo.

# Gemfile
source 'https://rubygems.org'

gem 'aws-xray-sdk', '0.11.4'
gem 'aws-sdk-lambda', '1.39.0'
gem 'test-unit', '3.3.5'

Para instrumentar clientes do AWS SDK, solicite o módulo aws-xray-sdk/lambda depois de criar um cliente no código de inicialização.

# lambda_function.rb
require 'logger'
require 'json'
require 'aws-sdk-lambda'
$client = Aws::Lambda::Client.new()
$client.get_account_settings()

require 'aws-xray-sdk/lambda'

def lambda_handler(event:, context:)
  logger = Logger.new($stdout)
  ...

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.

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

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 The X-Ray SDK for Ruby no Guia do desenvolvedor do AWS X-Ray.

Habilitar o rastreamento ativo 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:

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 ativo 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.

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.

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

Armazenar dependências de runtime em uma camada

Se você usar o X-Ray SDK para instrumentar os clientes do AWS SDK com seu código de função, seu pacote de implantação poderá se tornar bastante grande. Para evitar o upload de dependências de runtime todas as vezes que você atualizar seu código de função, empacote o SDK do X-Ray em uma camada do Lambda.

O exemplo a seguir mostra um recurso AWS::Serverless::LayerVersion que armazena o X-Ray SDK for Ruby.

Resources:
  function:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: function/.
      Tracing: Active
      Layers:
        - !Ref libs
      ...
  libs:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: blank-ruby-lib
      Description: Dependencies for the blank-ruby sample app.
      ContentUri: lib/.
      CompatibleRuntimes:
        - ruby2.5

Com essa configuração, você atualizará a camada de biblioteca somente se alterar as dependências de runtime. Já que o pacote de implantação de função inclui apenas o seu código, isso pode ajudar a reduzir o tempo de upload.

A criação de uma camada de dependências requer alterações de compilação para gerar o arquivo da camada antes da implantação. Para obter um exemplo funcional, consulte o aplicativo de exemplo blank-ruby.