Monitorando logs do AWS Lambda com ClickStack usando Rotel

Monitorando logs do AWS Lambda com ClickStack usando Rotel

TL;DR

Este guia mostra como monitorar funções do AWS Lambda com o ClickStack usando a Rotel Lambda Extension para coletar e encaminhar logs das funções, logs da extensão e dados do OpenTelemetry diretamente para o ClickHouse. Você aprenderá a:

• Implantar a camada da Rotel Lambda Extension nas suas funções Lambda
• Configurar a extensão para exportar logs e traces para o ClickStack
• Opcionalmente, desativar o CloudWatch Logs para reduzir custos

Essa abordagem pode reduzir significativamente seus custos de observabilidade no Lambda, eliminando completamente o uso do CloudWatch Logs.

Tempo necessário: 5 a 10 minutos

​

Integração com funções Lambda existentes

Esta seção aborda como configurar suas funções AWS Lambda existentes para enviar logs e traces ao ClickStack usando a Rotel Lambda Extension.

​

Pré-requisitos

• Instância do ClickStack em execução
• Funções do AWS Lambda para monitorar
• AWS CLI configurada com as permissões adequadas
• Perfil de execução do Lambda com permissões para adicionar camadas

1. ​

   Escolha a camada apropriada do Rotel Lambda Extension

   Escolha a camada do Lambda que corresponda à arquitetura de runtime da sua função Lambda. O campo {version} depende da região da AWS em que você está implantando. Consulte a página de lançamentos para encontrar os números de versão mais recentes correspondentes à sua região.

   Arquitetura	ARN
   x86-64/amd64	arn:aws:lambda:{region}:418653438961:layer:rotel-extension-amd64:{version}
   arm64	arn:aws:lambda:{region}:418653438961:layer:rotel-extension-arm64:{version}

   Regiões disponíveis:

   • us-east-, us-west-
   • eu-central-1, eu-north-1, eu-west-
   • ca-central-1
   • ap-southeast-, ap-northeast-
   • ap-south-1
   • sa-east-1
2. ​

   Adicione a layer do Rotel à sua função Lambda

   Nestes exemplos, substitua {arch}, {region} e {version} pelos valores apropriados acima.

   Opção 1: AWS Console

   1. Abra o console do AWS Lambda
   2. Acesse sua função Lambda
   3. Role até a seção Layers e clique em Add a layer
   4. Selecione Specify an ARN
   5. Insira o ARN da layer do Rotel:
      arn:aws:lambda:{region}:418653438961:layer:rotel-extension-{arch}:{version}
      
   6. Clique em Add

   Opção 2: AWS CLI

   aws lambda update-function-configuration \
     --function-name my-function \
     --layers arn:aws:lambda:{region}:418653438961:layer:rotel-extension-{arch}:{version}
   

   Opção 3: AWS SAM

   Resources:
     MyFunction:
       Type: AWS::Serverless::Function
       Properties:
         # ... outras configurações ...
         Layers:
           - arn:aws:lambda:{region}:418653438961:layer:rotel-extension-{arch}:{version}
   
3. ​

   Configure a extensão para exportar para o ClickStack

   A Rotel Lambda Extension é configurada por meio de variáveis de ambiente. Você precisa configurar o endpoint do exporter OTLP para apontar para sua instância do ClickStack. Os exemplos presumem que sua função do AWS Lambda consegue acessar a instância do ClickStack.

   Configuração básica (variáveis de ambiente)

   Adicione estas variáveis de ambiente à sua função do Lambda:

   # Obrigatório: endpoint OTLP do ClickStack
   ROTEL_OTLP_EXPORTER_ENDPOINT=https://clickstack.example.com:4317
   
   # Opcional: cabeçalhos de autenticação
   ROTEL_OTLP_EXPORTER_CUSTOM_HEADERS="Authorization=<YOUR_INGESTION_API_KEY>"
   
   # Opcional: nome do serviço (padrão: nome da função Lambda)
   ROTEL_OTEL_RESOURCE_ATTRIBUTES="service.name=my-lambda-api,service.version=1.0.0"
   

   Configuração avançada (usando um arquivo .env)

   Para configurações mais complexas, crie um arquivo rotel.env no pacote da sua função Lambda:

   rotel.env:

   ROTEL_OTLP_EXPORTER_ENDPOINT=https://clickstack.example.com:4317
   ROTEL_OTLP_EXPORTER_CUSTOM_HEADERS="Authorization=<YOUR_INGESTION_API_KEY>"
   ROTEL_OTEL_RESOURCE_ATTRIBUTES="service.name=my-lambda-api,deployment.environment=production"
   

   Em seguida, defina a variável de ambiente para apontar para este arquivo:

   ROTEL_ENV_FILE=/var/task/rotel.env
   

   Como usar o AWS Secrets Manager ou o Parameter Store

   Para implantações em produção, armazene valores sensíveis, como chaves de API, no AWS Secrets Manager ou no Parameter Store:

   Exemplo de AWS Secrets Manager:

   ROTEL_OTLP_EXPORTER_ENDPOINT=https://clickstack.example.com:4317
   ROTEL_OTLP_EXPORTER_CUSTOM_HEADERS="Authorization=${arn:aws:secretsmanager:us-east-1:123456789012:secret:clickstack-api-key-abc123}"
   

   Exemplo do AWS Parameter Store:

   ROTEL_OTLP_EXPORTER_ENDPOINT=https://clickstack.example.com:4317
   ROTEL_OTLP_EXPORTER_CUSTOM_HEADERS="Authorization=${arn:aws:ssm:us-east-1:123456789012:parameter/clickstack-api-key}"
   

   Permissões do IAM necessárias:

   Adicione estas permissões à função de execução do Lambda:

   Para o Secrets Manager:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "secretsmanager:GetSecretValue",
           "secretsmanager:BatchGetSecretValue"
         ],
         "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:clickstack-api-key-*"
       }
     ]
   }
   

   Para o Parameter Store:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "ssm:GetParameters"
         ],
         "Resource": "arn:aws:ssm:us-east-1:123456789012:parameter/clickstack-api-key"
       }
     ]
   }
   

   As chamadas à API da AWS para recuperar segredos acrescentam 100 a 150 ms à latência de cold start. Os segredos são recuperados em lotes (de até 10) e apenas na inicialização, portanto as invocações subsequentes não são afetadas.

4. ​

   Teste a integração

   Invoque sua função Lambda para verificar se os logs estão sendo enviados para o ClickStack:

   aws lambda invoke \
     --function-name my-function \
     --payload '{"test": "data"}' \
     response.json
   

   Verifique se há erros nos logs do Lambda:

   aws logs tail /aws/lambda/my-function --follow
   
5. ​

   Verifique os logs no HyperDX

   Depois de concluir a configuração, faça login no HyperDX (a UI do ClickStack) e verifique se os logs estão chegando:

   Procure estes atributos-chave nos logs:

   • service.name: Nome da sua função Lambda
   • faas.name: Nome da função AWS Lambda
   • faas.invocation_id: ID exclusivo da invocação
   • cloud.provider: “aws”
   • cloud.platform: “aws_lambda”

​

Desabilitando o CloudWatch Logs (otimização de custos)

Por padrão, o AWS Lambda envia todos os logs para o CloudWatch Logs, o que pode sair caro em escala. Depois de verificar que os logs estão chegando ao ClickStack, você pode desabilitar o logging do CloudWatch para reduzir custos.

1. ​

   Remova as permissões do CloudWatch do perfil de execução

   1. Abra o AWS Console e navegue até AWS Lambda
   2. Acesse sua função Lambda
   3. Selecione Configuration → Permissions
   4. Clique no nome do perfil de execução para abrir o console do IAM
   5. Edite a role e remova quaisquer actions logs:*:
      • Se estiver usando uma policy personalizada, edite-a para remover logs:CreateLogGroup, logs:CreateLogStream e logs:PutLogEvents
      • Se estiver usando a policy gerenciada pela AWS AWSLambdaBasicExecutionRole, remova-a da role
   6. Salve a role
2. ​

   Verifique se o logging do CloudWatch está desabilitado

   Invoque sua função novamente e verifique se:

   1. Nenhum novo log stream do CloudWatch é criado
   2. Os logs continuam aparecendo no ClickStack/HyperDX

   # Isso não deve mostrar nenhum novo log stream após a alteração da policy
   aws logs describe-log-streams \
     --log-group-name /aws/lambda/my-function \
     --order-by LastEventTime \
     --descending \
     --max-items 5
   

​

Adicionando a instrumentação automática do OpenTelemetry

A Rotel Lambda Extension funciona perfeitamente com camadas de instrumentação automática do OpenTelemetry para coletar traces distribuídos e métricas, além de logs.

1. ​

   Escolha a camada de instrumentação da sua linguagem

   A AWS fornece camadas de instrumentação automática do OpenTelemetry para várias linguagens:

   Linguagem	Padrão de ARN da camada
   Node.js	arn:aws:lambda:{region}:901920570463:layer:aws-otel-nodejs-{arch}-ver-{version}
   Python	arn:aws:lambda:{region}:901920570463:layer:aws-otel-python-{arch}-ver-{version}
   Java	arn:aws:lambda:{region}:901920570463:layer:aws-otel-java-agent-{arch}-ver-{version}

   Encontre as versões mais recentes no repositório AWS OpenTelemetry Lambda.

2. ​

   Adicione as duas camadas à sua função

   Adicione as duas camadas: a camada de extensão do Rotel e a camada de instrumentação:

   aws lambda update-function-configuration \
     --function-name my-function \
     --layers \
       arn:aws:lambda:{region}:418653438961:layer:rotel-extension-{arch}:{version} \
       arn:aws:lambda:{region}:901920570463:layer:aws-otel-nodejs-{arch}-ver-1-30-2:1
   
3. ​

   Configure a instrumentação automática

   Defina a variável de ambiente AWS_LAMBDA_EXEC_WRAPPER para ativar a instrumentação automática:

   Para Node.js:

   AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler
   

   Para Python:

   AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument
   

   Para Java:

   AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler
   
4. ​

   Verifique os traces no HyperDX

   Depois de invocar sua função:

   1. Acesse a visualização Traces no HyperDX
   2. Você deverá ver traces com spans da sua função Lambda
   3. Os traces serão correlacionados com os logs por meio dos atributos trace_id e span_id

​

Aplicativos de exemplo

Confira o aplicativo de exemplo em Python que demonstra a Rotel Lambda Extension:

• Python + ClickHouse: Aplicativo Python com instrumentação manual com OpenTelemetry, enviando traces e logs diretamente para o ClickHouse

​

Participe da comunidade Rotel

Se você tiver dúvidas sobre o Rotel, entre no servidor do Discord da Rotel e compartilhe seu feedback ou suas perguntas. Confira a Rotel Lambda Extension para contribuir com melhorias.

​

Recursos adicionais

• Rotel Lambda Extension: Código-fonte e documentação detalhada
• Rotel Core: O plano de dados leve do OTel que dá suporte à extensão