Este documento foi traduzido usando tecnologia de tradução automática de máquina. Sempre trabalhamos para apresentar traduções precisas, mas não oferecemos nenhuma garantia em relação à integridade, precisão ou confiabilidade do conteúdo traduzido. Em caso de qualquer discrepância, a versão original em inglês prevalecerá e constituirá o texto official.

Auto-Instrumentação de uma função Lambda NodeJS

Introdução

Este documento orienta você sobre como auto-instrumentar funções Lambda NodeJS usando OpenTelemetry. A auto-instrumentação simplifica o processo de adicionar observabilidade às suas funções Lambda, capturando automaticamente métricas de desempenho e informações de rastreamento.

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte:

  • Função AWS Lambda: A função que você deseja instrumentar.

  • SDK OpenTelemetry: Instalado em sua função Lambda.

  • Coletor OpenTelemetry: Implantado e configurado.

  • SUSE Observability: Uma conta com o SUSE Observability onde você enviará seus dados de telemetria.

  • Memória: Memória suficiente para executar a função Lambda, incluindo a instrumentação.

Valores fornecidos pelo ambiente

OpenTelemetry depende de vários valores de configuração para funcionar corretamente. Esses valores controlam aspectos como coleta de dados, exportação e comunicação com sistemas de backend. Para tornar sua implantação do OpenTelemetry flexível e adaptável a diferentes ambientes, você pode fornecer essas configurações por meio de variáveis de ambiente. Essa abordagem oferece vários benefícios:

  • Configuração Dinâmica: Ajuste facilmente as configurações sem alterações no código.

  • Configurações Específicas do Ambiente: Configure o OpenTelemetry de forma diferente para desenvolvimento, teste e produção.

  • Gerenciamento de Segredos: Armazene informações sensíveis, como chaves de API, de forma segura.

Para a configuração do OpenTelemetry descrita nesta documentação, você precisará definir as seguintes variáveis de ambiente:

  • VERBOSITY: Controla o nível de detalhe nos logs do OpenTelemetry.

  • OTLP_API_KEY: Autentica sua função Lambda para enviar dados ao SUSE Observability.

  • OTLP_ENDPOINT: Especifica o endereço da sua instância do SUSE Observability.

  • OPENTELEMETRY_COLLECTOR_CONFIG_FILE: Aponta para o arquivo de configuração do OpenTelemetry Collector.

  • AWS_LAMBDA_EXEC_WRAPPER: Configura o ambiente de execução da função Lambda para usar o manipulador do OpenTelemetry.

  • OTLP_INSTR_LAYER_ARN: Fornece o ARN (Amazon Resource Name) da camada de instrumentação do OpenTelemetry, que adiciona os componentes necessários para a auto-instrumentação.

  • OTLP_COLLECTOR_LAYER_ARN: Fornece o ARN da camada do coletor do OpenTelemetry, que é responsável por receber, processar e exportar dados de telemetria.

Considerações Importantes:

  • Ponto de Extremidade GRPC: O OTLP_ENDPOINT deve especificar o ponto de extremidade gRPC da sua instância do SUSE Observability sem nenhum prefixo http ou https. Use a porta 443 para comunicação segura.

  • Camadas Específicas da Região: As camadas Lambda são vinculadas à região. Certifique-se de que os ARNs que você usa para OTLP_INSTR_LAYER_ARN e OTLP_COLLECTOR_LAYER_ARN correspondam à região da AWS onde sua função Lambda está implantada.

  • Correspondência de Arquitetura: A camada do OpenTelemetry Collector é específica para a arquitetura. Escolha o ARN correto para a arquitetura da sua função Lambda (por exemplo, amd64 ou arm64).

Um exemplo completo: esteja ciente de que você precisa inserir seus próprios valores.

VERBOSITY: "normal"
OTLP_API_KEY: "<your api key for sending data to SUSE Observability here>"
OTLP_ENDPOINT: "<your-dns-name-for-suse-observability-here>:443"
OPENTELEMETRY_COLLECTOR_CONFIG_FILE: "/var/task/collector.yaml"
AWS_LAMBDA_EXEC_WRAPPER: "/opt/otel-handler"
OTLP_INSTR_LAYER_ARN: "arn:aws:lambda:<aws-region>:184161586896:layer:opentelemetry-nodejs-0_11_0:1"
OTLP_COLLECTOR_LAYER_ARN: "arn:aws:lambda:<aws-region>:184161586896:layer:opentelemetry-collector-<amd64|arm64>-0_12_0:1"

O arquivo collector.yaml.

A configuração de coleta do OTEL define como os dados coletados devem ser distribuídos. Isso é feito no arquivo collector.yaml colocado no diretório src onde os arquivos lambda podem ser encontrados. Abaixo está um exemplo de arquivo collector.yaml.

# collector.yaml in the root directory
# Set an environemnt variable 'OPENTELEMETRY_COLLECTOR_CONFIG_FILE' to
# '/var/task/collector.yaml'

receivers:
  otlp:
    protocols:
      grpc:
      http:

exporters:
  debug:
    verbosity: "${env:VERBOSITY}"
  otlp/stackstate:
    headers:
      Authorization: "SUSEObservability ${env:OTLP_API_KEY}"
    endpoint: "${env:OTLP_ENDPOINT}"

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [debug, otlp/stackstate]
      processors: []
    metrics:
      receivers: [otlp]
      exporters: [debug, otlp/stackstate]
      processors: []

Este coletor é usado para enviar os dados para um próximo coletor, que é então utilizado para amostragem de cauda, agregação de métricas, etc., antes de enviar os dados para o SUSE Observability. Este segundo coletor também precisa ser executado no ambiente do cliente.

Dependendo da funcionalidade desejada, ou com base em fatores como volumes de dados gerados por funções Lambda instrumentadas dessa forma, os coletores podem ser configurados para processamento em lote, amostragem de cauda e outras técnicas de pré-processamento para reduzir o impacto no SUSE Observability.

Siga o guia de início para configurar um coletor para enviar os dados ao SUSE Observability. A personalização da configuração do coletor para definir amostragem, filtragem, etc., pode ser encontrada na nossa documentação do coletor.

Instrumentação do AWS Lambda com Opentelemetry

Package.json

Certifique-se de adicionar "@opentelemetry/auto-instrumentations-node": "^0.55.2",+ a package.json e executar npm install para adicionar as bibliotecas de cliente de auto-instrumentação à sua função Lambda NodeJS.

Solução de problemas

Tempos de espera

Se a adição das camadas OTEL Lambda resultar em funções Lambda que excedem o tempo limite (a verificação dos logs pode indicar que o coletor foi solicitado a encerrar enquanto ainda estava ocupado, por exemplo, ao visualizar a seguinte entrada de log):

{
    "level": "info",
    "ts": 1736867469.2312617,
    "caller": "internal/retry_sender.go:126",
    "msg": "Exporting failed. Will retry the request after interval.",
    "kind": "exporter",
    "data_type": "traces",
    "name": "otlp/stackstate",
    "error": "rpc error: code = Canceled desc = context canceled",
    "interval": "5.125929689s"
}

pouco depois de receber a instrução para encerrar:

{
    "level": "info",
    "ts": 1736867468.4311068,
    "logger": "lifecycle.manager",
    "msg": "Received SHUTDOWN event"
}

Isso indica que os recursos alocados para a função Lambda não são suficientes para permitir sua execução, considerando também o esforço adicional imposto pela instrumentação OTEL. Para remediar essa situação, a alocação de memória e as configurações de tempo limite da função Lambda podem ser ajustadas conforme necessário para permitir que ela conclua seu trabalho, ao mesmo tempo em que possibilita o sucesso na coleta de telemetria.

Tente modificar as propriedades MemorySize e TimeOut das funções Lambda que estão falhando.

MemorySize: 256
Timeout: 25

Observe que a alocação de memória padrão é 128MB.

Observe que o incremento de memória é de 128MB.

Observe que o Timeout é um valor inteiro que denota segundos.

Autenticação e Filtragem de IP de Origem

Se você encontrar error 403 Unauthorized ao enviar dados do coletor para seu cluster, ou para qualquer coletor de pré-processamento ou proxy, verifique se o endereço IP de origem do gateway NAT da VPC corresponde ao que está na lista de permissões do coletor, também verifique se o mecanismo de autenticação escolhido corresponde à origem e ao destino, e também se as credenciais (segredos, etc.) estão configuradas corretamente.

Para mais informações sobre como configurar a autenticação para o coletor OpenTelemetry, consulte a documentação oficial.

Referências

Documentos de auto-instrumentação → https://opentelemetry.io/docs/faas/lambda-auto-instrument/

Documentos do coletor → https://opentelemetry.io/docs/faas/lambda-collector/

Página de Lançamentos do GitHub para encontrar os últimos ARNs → https://github.com/open-telemetry/opentelemetry-lambda/releases

Configuração do Exportador OTLP → https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/