Instrumentação Lambda com Serverless Framework e Elven Plugin

Sumário

• Visão geral
• Pré-requisitos
• Instalação
• Quick Start
• Configuração do plugin
• Referência de opções
• Controle por função
• Variáveis de ambiente injetadas
• Layers aplicadas
• Exemplos completos
• Boas práticas
• Troubleshooting
• FAQ

Visão geral

O elven-instrumentation-serverless-plugin automatiza toda a instrumentação das suas funções Lambda. Com uma única configuração no serverless.yml, o plugin:

1. Adiciona as layers de OpenTelemetry e Elven Log Extension em cada função
2. Injeta todas as variáveis de ambiente necessárias para traces e logs
3. Detecta a arquitetura (x86_64/arm64) e aplica as layers corretas
4. Gera nomes de serviço padronizados automaticamente ({service}_{stage}_{function})

┌──────────────────────────────────────────────────────────────┐
│                   serverless.yml                             │
│                                                              │
│  plugins:                                                    │
│    - elven-instrumentation-serverless-plugin                 │
│                                                              │
│  custom:                                                     │
│    elvenLayerPlugin:                                         │
│      tenant: "meu-tenant"        ──────┐                     │
│      token: "meu-token"                │                     │
│                                        ▼                     │
│                              ┌─────────────────┐             │
│                              │  Plugin injeta:  │             │
│                              │  - 2 layers      │             │
│                              │  - 14+ env vars  │             │
│                              └────────┬────────┘             │
│                                       │                      │
│  functions:                           ▼                      │
│    api:      ← layers + envs injetados automaticamente       │
│    worker:   ← layers + envs injetados automaticamente       │
│    cron:     ← layers + envs injetados automaticamente       │
└──────────────────────────────────────────────────────────────┘

Pré-requisitos

• Serverless Framework v3 ou v4 instalado
• Node.js 18+
• Coletor OpenTelemetry (OTLP) implantado na sua infraestrutura (a Elven realiza o deploy do collector no seu ambiente — não é um endpoint compartilhado)
• Credenciais da Elven Observability:
• Tenant ID
• API Token
• Endpoint do seu Collector OTLP

Instalação

npm install --save-dev elven-instrumentation-serverless-plugin

Adicione o plugin no serverless.yml:

plugins:
  - elven-instrumentation-serverless-plugin

Verificar instalação:

npx serverless print 2>&1 | grep -i elven

Quick Start

1. Configure o plugin no serverless.yml

service: minha-api

provider:
  name: aws
  runtime: nodejs20.x
  region: us-east-1

plugins:
  - elven-instrumentation-serverless-plugin

custom:
  elvenLayerPlugin:
    tenant: "seu-tenant-id"
    token: "seu-api-token"

functions:
  hello:
    handler: handler.hello
    events:
      - http:
          path: /hello
          method: get

2. Deploy normalmente

npx serverless deploy

O plugin automaticamente:

• Adiciona as layers de OTel e Log Extension na função
• Injeta as variáveis de ambiente com nome de serviço minha-api_dev_hello
• Configura o endpoint OTLP e Loki da Elven

Pronto! Ao invocar a função, traces e logs já aparecem na Elven Observability.

Output do plugin no deploy

✅ [Elven] Instrumented function: minha-api_dev_hello (x86_64)
🏗️  [Elven] Architecture: x86_64
📍 [Elven] Region: us-east-1
📦 [Elven] Default layers applied:
      - arn:aws:lambda:us-east-1:184161586896:layer:opentelemetry-nodejs-0_20_0:1
      - arn:aws:lambda:us-east-1:911167927290:layer:elven-lambda-log-extension:8

Configuração do plugin

Todas as opções ficam dentro de custom.elvenLayerPlugin no serverless.yml:

custom:
  elvenLayerPlugin:
    # === Obrigatórios ===
    tenant: "seu-tenant-id"
    token: "seu-api-token"

    # === Opcionais ===
    region: "us-east-1"                                    # default: us-east-1
    collector_endpoint: "https://otel-collector.minha-infra.com:4318"  # URL do seu collector
    logs_endpoint: "https://loki.elvenobservability.com"   # default: endpoint Elven
    architecture: "x86_64"                                 # default: x86_64
    log_version: "8"                                       # versão da layer de logs (x86_64)
    log_version_arm64: "7"                                 # versão da layer de logs (arm64)
    enabled_instrumentations: "http,express,pg"            # default: todas
    disabled_instrumentations: ""                          # default: nenhuma
    layers:                                                # override completo das layers
      - "arn:aws:lambda:us-east-1:..."
      - "arn:aws:lambda:us-east-1:..."

Referência de opções

Opções obrigatórias

Opções opcionais

Ordem de resolução da arquitetura

A arquitetura é resolvida nesta ordem de precedência:

1. custom.elvenLayerPlugin.architecture
2. Variável de ambiente LAMBDA_ARCHITECTURE
3. provider.architecture do Serverless
4. Default: x86_64

Para funções individuais, function.architecture tem prioridade sobre o valor global.

Controle por função

Desabilitar instrumentação em uma função específica

Adicione disableElven: true na função:

functions:
  api:
    handler: handler.api
    # instrumentada normalmente

  internal:
    handler: handler.internal
    disableElven: true
    # NÃO será instrumentada

  worker:
    handler: handler.worker
    # instrumentada normalmente

Output no deploy:

✅ [Elven] Instrumented function: minha-api_dev_api (x86_64)
⚠️  [Elven] Skipping instrumentation for function: internal
✅ [Elven] Instrumented function: minha-api_dev_worker (x86_64)

Sobrescrever variáveis por função

O plugin não sobrescreve variáveis de ambiente já definidas na função. Isso permite customizar por função:

functions:
  api:
    handler: handler.api
    # Usa configuração padrão do plugin

  heavy-worker:
    handler: handler.worker
    environment:
      OTEL_TRACES_SAMPLER: "traceidratio"
      OTEL_TRACES_SAMPLER_ARG: "0.1"
      # Sampling de 10% — demais variáveis são injetadas pelo plugin

Funções com arquiteturas diferentes

O plugin detecta a arquitetura por função e aplica as layers corretas:

provider:
  architecture: x86_64  # padrão para todas

functions:
  api:
    handler: handler.api
    # usa x86_64 (do provider)

  ml-inference:
    handler: handler.inference
    architecture: arm64
    # usa arm64 — layers arm64 aplicadas automaticamente

Variáveis de ambiente injetadas

O plugin injeta as seguintes variáveis em cada função:

OpenTelemetry (Traces)

Elven Log Extension (Logs)

Nota sobre LOKI_URL: O plugin envia apenas a URL base (ex: https://loki.elvenobservability.com). A log extension appenda /loki/api/v1/push automaticamente.

Naming convention automática

O OTEL_SERVICE_NAME segue o padrão:

{serviceName}_{stage}_{functionName}

Exemplo: serviço ecommerce, stage prod, função checkout → ecommerce_prod_checkout

Layers aplicadas

O plugin adiciona automaticamente duas layers:

x86_64

arm64

Override de layers

Para usar layers customizadas (ex: versão diferente ou layer própria):

custom:
  elvenLayerPlugin:
    tenant: "meu-tenant"
    token: "meu-token"
    layers:
      - "arn:aws:lambda:us-east-1:184161586896:layer:opentelemetry-nodejs-0_20_0:1"
      - "arn:aws:lambda:us-east-1:911167927290:layer:elven-lambda-log-extension:8"

Ao definir layers, a seleção automática por arquitetura é desabilitada. Certifique-se de usar as layers corretas para a arquitetura das suas funções.

Exemplos completos

Exemplo 1 — API REST simples

service: users-api

provider:
  name: aws
  runtime: nodejs20.x
  region: us-east-1
  stage: ${opt:stage, 'dev'}

plugins:
  - elven-instrumentation-serverless-plugin

custom:
  elvenLayerPlugin:
    tenant: "meu-tenant"
    token: "meu-api-token"

functions:
  getUsers:
    handler: src/handlers/users.list
    events:
      - http:
          path: /users
          method: get

  getUser:
    handler: src/handlers/users.get
    events:
      - http:
          path: /users/{id}
          method: get

  createUser:
    handler: src/handlers/users.create
    events:
      - http:
          path: /users
          method: post

Exemplo 2 — Microserviço com múltiplas arquiteturas

service: ml-pipeline

provider:
  name: aws
  runtime: nodejs20.x
  region: us-east-1
  architecture: x86_64

plugins:
  - elven-instrumentation-serverless-plugin

custom:
  elvenLayerPlugin:
    tenant: "meu-tenant"
    token: "meu-api-token"
    region: "us-east-1"

functions:
  api:
    handler: src/api.handler
    events:
      - http:
          path: /predict
          method: post

  inference:
    handler: src/inference.handler
    architecture: arm64
    memorySize: 1024
    timeout: 30
    events:
      - sqs:
          arn: !GetAtt InferenceQueue.Arn

  data-ingestion:
    handler: src/ingestion.handler
    timeout: 300
    events:
      - schedule: rate(5 minutes)

Exemplo 3 — Instrumentações seletivas com funções excluídas

service: ecommerce

provider:
  name: aws
  runtime: nodejs20.x
  region: us-east-1

plugins:
  - elven-instrumentation-serverless-plugin

custom:
  elvenLayerPlugin:
    tenant: "meu-tenant"
    token: "meu-api-token"
    enabled_instrumentations: "http,express,pg,redis,undici"

functions:
  checkout:
    handler: src/checkout.handler
    events:
      - http:
          path: /checkout
          method: post

  payments:
    handler: src/payments.handler
    events:
      - sqs:
          arn: !GetAtt PaymentsQueue.Arn

  # Função interna — sem necessidade de observabilidade
  migrations:
    handler: src/migrations.handler
    disableElven: true
    events:
      - schedule: rate(1 day)

Exemplo 4 — Usando variáveis do Serverless para credenciais

Para não hardcodar credenciais no serverless.yml:

custom:
  elvenLayerPlugin:
    tenant: ${env:ELVEN_TENANT}
    token: ${env:ELVEN_TOKEN}
    region: ${self:provider.region}

Deploy passando as variáveis:

ELVEN_TENANT=meu-tenant ELVEN_TOKEN=meu-token npx serverless deploy

Ou usando SSM Parameter Store:

custom:
  elvenLayerPlugin:
    tenant: ${ssm:/elven/tenant}
    token: ${ssm:/elven/token}

Exemplo 5 — Customizar sampling por função

custom:
  elvenLayerPlugin:
    tenant: "meu-tenant"
    token: "meu-token"

functions:
  # Função com alto volume → sampling de 10%
  high-traffic-api:
    handler: src/api.handler
    environment:
      OTEL_TRACES_SAMPLER: "traceidratio"
      OTEL_TRACES_SAMPLER_ARG: "0.1"
    events:
      - http:
          path: /search
          method: get

  # Função crítica → capturar tudo (default do plugin)
  checkout:
    handler: src/checkout.handler
    events:
      - http:
          path: /checkout
          method: post

Boas práticas

Credenciais seguras

Nunca hardcode credenciais no serverless.yml. Use uma das opções:

# Opção 1: Variáveis de ambiente
tenant: ${env:ELVEN_TENANT}
token: ${env:ELVEN_TOKEN}

# Opção 2: SSM Parameter Store
tenant: ${ssm:/elven/tenant}
token: ${ssm:/elven/token~true}  # ~true para decrypt SecureString

# Opção 3: Secrets Manager
tenant: ${ssm:/aws/reference/secretsmanager/elven-tenant}

Instrumentações seletivas

Habilite apenas as instrumentações que o projeto realmente usa. Menos instrumentações = cold start mais rápido:

custom:
  elvenLayerPlugin:
    enabled_instrumentations: "http,pg,redis,undici"

Instrumentações disponíveis: http, express, graphql, grpc, hapi, ioredis, koa, mongodb, mysql, net, pg, redis, memcached, mongoose, amqplib, bunyan, cassandra-driver, connect, kafkajs, knex, mysql2, nestjs-core, pino, restify, socket.io, undici, winston

Timeout da função

As layers adicionam \~200-400ms de overhead no cold start. Certifique-se de que o timeout acomoda isso:

provider:
  timeout: 10  # mínimo recomendado

Para funções com múltiplas instrumentações, considere 30 segundos.

Memória

Mais memória = mais CPU = cold start mais rápido. Para funções instrumentadas, recomendamos pelo menos 256 MB:

provider:
  memorySize: 256

Stages

O plugin usa o stage do Serverless para compor o nome do serviço e o atributo environment:

# Deploy em staging → nomes: ecommerce_staging_checkout
npx serverless deploy --stage staging

# Deploy em production → nomes: ecommerce_production_checkout
npx serverless deploy --stage production

Troubleshooting

O deploy falha com erro de layer

Sintoma: Erro Layer version arn:aws:lambda:... does not exist.

Causas possíveis:

1. Região incorreta — A layer não está disponível na região configurada. Verifique region no plugin
2. Versão inexistente — Verifique se log_version / log_version_arm64 estão corretos

# Verificar se a layer existe na região
aws lambda get-layer-version <br>
  --layer-name opentelemetry-nodejs-0_20_0 <br>
  --version-number 1 <br>
  --region us-east-1 <br>
  --query "LayerVersionArn"

A função falha ao iniciar (timeout ou crash)

Sintoma: Runtime.ExitError ou timeout no cold start.

Verificações:

1. Timeout muito baixo — Aumente para pelo menos 10 segundos
2. Layer incompatível com a arquitetura — Verifique se a função arm64 está recebendo a layer arm64
3. Wrapper incorreto — O plugin seta AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler. Se a layer OTel não estiver presente, isso causa crash

# Verificar configuração da função após deploy
npx serverless info --verbose

Traces não aparecem na Elven

Sintoma: Função executa normalmente, mas nenhum trace aparece.

Verificações:

1. Confirme que collector_endpoint está correto
2. Confirme que o token é válido
3. Se sobrescreveu OTEL_TRACES_SAMPLER na função, verifique o valor

# Ver as variáveis de ambiente da função
aws lambda get-function-configuration <br>
  --function-name minha-api-dev-hello <br>
  --query "Environment.Variables" <br>
  --output table

Logs não aparecem no Loki

Sintoma: Traces funcionam, mas logs não aparecem.

Verificações:

1. logs_endpoint deve ser a URL base (sem /loki/api/v1/push). A extension adiciona o path automaticamente * Correto: https://loki.elvenobservability.com * Errado: https://loki.elvenobservability.com/loki/api/v1/push
2. Confirme que tenant e token estão corretos
3. Habilite debug temporariamente na função:

functions:
  minha-funcao:
    handler: handler.handler
    environment:
      DEBUG: "true"

Depois invoque e verifique os logs no CloudWatch.

Plugin não aparece no output do deploy

Sintoma: Nenhuma mensagem [Elven] no deploy.

Verificações:

1. O plugin está na seção plugins do serverless.yml
2. O pacote está instalado: npm ls elven-instrumentation-serverless-plugin
3. A seção custom.elvenLayerPlugin existe (mesmo que vazia, o plugin precisa ser listado em plugins)

Variáveis de ambiente não são injetadas

Sintoma: A função não tem as variáveis esperadas.

Causa: O plugin não sobrescreve variáveis já definidas na função. Se você definiu OTEL_SERVICE_NAME manualmente na função, o plugin não vai substituir.

Verificação:

npx serverless print --path functions.minhaFuncao.environment

FAQ

Preciso configurar algo em cada função? Não. O plugin instrumenta todas as funções automaticamente. A única configuração necessária é o bloco custom.elvenLayerPlugin com tenant e token.

Posso desabilitar em funções específicas? Sim. Adicione disableElven: true na definição da função.

Funciona com Serverless Framework v4? Sim. O plugin é compatível com v3 e v4 do Serverless Framework.

O plugin funciona com outros runtimes além de Node.js? As layers padrão do plugin são para Node.js. Para outros runtimes (Python, Java, Ruby), use a opção layers para especificar as layers corretas. Consulte a documentação de instrumentação Lambda manual para os ARNs de cada runtime.

O plugin sobrescreve minhas variáveis de ambiente? Não. O plugin só injeta variáveis que não existem na função. Se você definir uma variável manualmente, ela tem prioridade.

O plugin sobrescreve minhas layers? Não. O plugin adiciona as layers sem remover as existentes. Não há duplicação — se a layer já existe, não é adicionada novamente.

Como atualizar a versão das layers? Altere log_version e log_version_arm64 no custom.elvenLayerPlugin. Para a layer OTel, use a opção layers com os ARNs atualizados.

Posso usar com monorepo / múltiplos serverless.yml? Sim. Cada serverless.yml é independente. Use a mesma configuração elvenLayerPlugin em cada um, preferencialmente via variáveis de ambiente ou SSM para evitar duplicação.

Qual o impacto no tamanho do deployment? As layers não contam no limite de 50 MB do pacote de deploy (ZIP). Elas contam no limite total de 250 MB (código + layers descomprimidos).

Posso usar junto com outros plugins do Serverless? Sim. O plugin roda no hook before:package:initialize e não interfere com outros plugins. A ordem no plugins array geralmente não importa.

Como vejo quais variáveis o plugin injetou? Use npx serverless print para ver a configuração completa resolvida, ou verifique direto na AWS:

aws lambda get-function-configuration <br>
  --function-name {service}-{stage}-{function} <br>
  --query "Environment.Variables"