Monitorando logs do AWS Lambda com ClickStack usando Rotel

TL;DREste 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

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

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

Abra o console do AWS Lambda
Acesse sua função Lambda
Role até a seção Layers e clique em Add a layer
Selecione Specify an ARN

Insira o ARN da layer do Rotel:

arn:aws:lambda:{region}:418653438961:layer:rotel-extension-{arch}:{version}

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}

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.

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

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.

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

Abra o AWS Console e navegue até AWS Lambda
Acesse sua função Lambda
Selecione Configuration → Permissions
Clique no nome do perfil de execução para abrir o console do IAM
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
Salve a role

Verifique se o logging do CloudWatch está desabilitado

Invoque sua função novamente e verifique se:

Nenhum novo log stream do CloudWatch é criado
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.

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.

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

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

Verifique os traces no HyperDX

Depois de invocar sua função:

Acesse a visualização Traces no HyperDX
Você deverá ver traces com spans da sua função Lambda
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

​Integração com funções Lambda existentes

​Pré-requisitos

​Escolha a camada apropriada do Rotel Lambda Extension

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

Opção 1: AWS Console

Opção 2: AWS CLI

Opção 3: AWS SAM

​Configure a extensão para exportar para o ClickStack

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

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

Como usar o AWS Secrets Manager ou o Parameter Store

​Teste a integração

​Verifique os logs no HyperDX

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

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

​Verifique se o logging do CloudWatch está desabilitado

​Adicionando a instrumentação automática do OpenTelemetry

​Escolha a camada de instrumentação da sua linguagem

​Adicione as duas camadas à sua função

​Configure a instrumentação automática

​Verifique os traces no HyperDX

​Aplicativos de exemplo

​Participe da comunidade Rotel

​Recursos adicionais

Integração com funções Lambda existentes

Pré-requisitos

Escolha a camada apropriada do Rotel Lambda Extension

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

Configure a extensão para exportar para o ClickStack

Teste a integração

Verifique os logs no HyperDX

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

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

Verifique se o logging do CloudWatch está desabilitado

Adicionando a instrumentação automática do OpenTelemetry

Escolha a camada de instrumentação da sua linguagem

Adicione as duas camadas à sua função

Configure a instrumentação automática

Verifique os traces no HyperDX

Aplicativos de exemplo

Participe da comunidade Rotel

Recursos adicionais