Monitorando logs do AWS Lambda com ClickStack usando Rotel

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.

Regiões disponíveis:

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

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:
      # ... other configuration ...
      Layers:
        - arn:aws:lambda:{region}:418653438961:layer:rotel-extension-{arch}:{version}

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:

# Required: ClickStack OTLP endpoint
ROTEL_OTLP_EXPORTER_ENDPOINT=https://clickstack.example.com:4317

# Optional: Authentication headers
ROTEL_OTLP_EXPORTER_CUSTOM_HEADERS="Authorization=<YOUR_INGESTION_API_KEY>"

# Optional: Service name (defaults to Lambda function name)
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"
    }
  ]
}

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

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"

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

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

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

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

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

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

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