Monitorización de logs de AWS Lambda con ClickStack usando Rotel

Elige la capa de Lambda que coincida con la arquitectura del entorno de ejecución de tu función Lambda. El campo {version} depende de la región de AWS en la que la estés desplegando. Consulta la página de releases para ver los números de versión más recientes correspondientes a tu región.

Regiones disponibles:

• 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

En estos ejemplos, sustituye {arch}, {region} y {version} por los valores adecuados indicados arriba.

Opción 1: Consola de AWS

1. Abre la consola de AWS Lambda
2. Ve a tu función Lambda
3. Desplázate hasta la sección Layers y haz clic en Add a layer
4. Selecciona Specify an ARN
5. Introduce el ARN de la capa Rotel:

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

6. Haz clic en Add

Opción 2: AWS CLI

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

Opción 3: AWS SAM

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      # ... other configuration ...
      Layers:
        - arn:aws:lambda:{region}:418653438961:layer:rotel-extension-{arch}:{version}

Rotel Lambda Extension se configura mediante variables de entorno. Debes configurar el endpoint del exportador OTLP para que apunte a tu instancia de ClickStack. Los ejemplos asumen que tu función de AWS Lambda puede acceder a la instancia de ClickStack.

Configuración básica (variables de entorno)

Agrega estas variables de entorno a tu función de 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"

Configuración avanzada (con el archivo .env)

Para configuraciones más complejas, crea un archivo rotel.env en el paquete de tu función 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"

A continuación, configura la variable de entorno para que apunte a este archivo:

ROTEL_ENV_FILE=/var/task/rotel.env

Uso de AWS Secrets Manager o de Parameter Store

Para implementaciones de producción, almacena valores confidenciales, como claves de API, en AWS Secrets Manager o Parameter Store:

Ejemplo 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}"

Ejemplo de 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}"

Permisos de IAM necesarios:

Añada estos permisos a su rol de ejecución de Lambda:

Para 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 Parameter Store:

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

Invoca tu función Lambda para comprobar que los logs se están enviando a ClickStack:

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

Revise los logs de Lambda para ver si hay errores:

aws logs tail /aws/lambda/my-function --follow

Una vez configurado, inicia sesión en HyperDX (la UI de ClickStack) y verifica que los logs se estén enviando:

Busca estos atributos clave en los logs:

• service.name: El nombre de tu función Lambda
• faas.name: Nombre de la función AWS Lambda
• faas.invocation_id: ID de invocación único
• cloud.provider: "aws"
• cloud.platform: "aws_lambda"

1. Abre la consola de AWS y ve a AWS Lambda
2. Ve a tu función Lambda
3. Selecciona Configuration → Permissions
4. Haz clic en el nombre del rol de ejecución para abrir la consola de IAM
5. Edita el rol y elimina cualquier acción logs:*:
   • Si usas una política personalizada, edítala para quitar logs:CreateLogGroup, logs:CreateLogStream y logs:PutLogEvents
   • Si usas la política administrada por AWS AWSLambdaBasicExecutionRole, quítala del rol
6. Guarda el rol

Invoca tu función de nuevo y verifica que:

1. No se creen nuevos streams de logs en CloudWatch
2. Los logs sigan apareciendo en ClickStack/HyperDX

# Esto no debería mostrar nuevos streams de logs después del cambio de política
aws logs describe-log-streams \
  --log-group-name /aws/lambda/my-function \
  --order-by LastEventTime \
  --descending \
  --max-items 5

AWS ofrece capas de autoinstrumentación de OpenTelemetry para varios lenguajes:

Consulta las versiones más recientes en el repositorio de AWS OpenTelemetry Lambda.

Agrega ambas capas: la capa de extensión de Rotel y la capa de instrumentación:

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

Define la variable de entorno AWS_LAMBDA_EXEC_WRAPPER para habilitar la autoinstrumentación:

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

Después de invocar tu función:

1. Ve a la vista Traces de HyperDX
2. Deberías ver trazas con spans de tu función Lambda
3. Las trazas aparecerán correlacionadas con los logs mediante los atributos trace_id y span_id