Elven Serverless Plugin

O Elven Serverless Plugin facilita a instrumentação automática das suas funções AWS Lambda no Serverless Framework, adicionando a Layer de observabilidade, configurando as variáveis de ambiente e preparando suas funções para envio de traces, logs e métricas para o seu stack LGTM.

Pré-requisitos

• Node.js 14.x ou superior

• Serverless Framework instalado (npm install -g serverless)

• Conta AWS configurada

• Acesso ao painel Elven Observability

Instalação

Adicione o plugin no seu projeto:

# com Yarn
yarn add elven-serverless-plugin

# com NPM
npm install elven-serverless-plugin

Configuração no Serverless Framework

No seu arquivo serverless.yml (ou .ts, .js), adicione o plugin na lista:

plugins:
  - elven-serverless-plugin

Caso já utilize outros plugins, apenas insira o elven-serverless-plugin junto deles.

Em seguida, configure o plugin na seção custom:

custom:
  elvenPlugin:
    tenant: "${env:TENANT_ID}"            # Tenant ID fornecido no Elven Observability
    token: "${env:OTEL_API_TOKEN}"        # Token gerado no Elven Observability
    endpoint: "${env:COLLECTOR_URL}"      # URL do seu OTLP Collector
    loki_url: "${env:LOKI_URL}"           # URL do Loki (opcional, padrão é fornecido)
    env: ${opt:stage, 'dev'}              # Ambiente (dev, staging, prod)
    region: ${opt:region, 'us-east-1'}    # Região AWS
    version: 5                            # Versão da Layer de instrumentação

Sobre os valores

• Você pode passar os valores diretamente (plain text), por exemplo:

tenant: "acme-tenant"
token: "eyJhbGciOiJIUzI1NiIs..."
endpoint: "<https://my-collector.com/otlp/v1>"

• Melhor prática: use variáveis de ambiente para evitar exposição de dados sensíveis no código.

Exemplo de arquivo .env

TENANT_ID=acme-tenant
OTEL_API_TOKEN=eyJhbGciOiJIUzI1NiIs...
COLLECTOR_URL=https://collector.elvenobservability.com/otlp/v1
LOKI_URL=https://loki.elvenobservability.com

Como obter tenant e token

Acesse https://elvenobservability.com/, faça login no seu painel e gere o Tenant ID e o Token de API na seção de configurações do projeto.

Caso tenha qualquer dificuldade, nosso time de suporte está pronto para ajudar. Entre em contato pelo próprio painel ou com seu contato dedicado.

O que o plugin faz automaticamente

• Adiciona a Layer de observabilidade nas suas funções Lambda.

• Configura as variáveis de ambiente necessárias para OpenTelemetry e Loki.

• Gera nomes padronizados para os serviços no formato: service_stage_functionName

• Permite desativar a instrumentação em funções específicas:

functions:
  myFunction:
    handler: handler.myFunction
    disableOtel: true

Deploy

Execute o deploy do seu serviço:

# Deploy para ambiente de desenvolvimento
serverless deploy --stage dev --region us-east-1

# Deploy para produção
serverless deploy --stage prod --region us-east-1

Verificando a Instrumentação

1. Após o deploy, acesse o AWS Console.

2. Verifique se a Layer foi adicionada às suas funções.

3. Confira as variáveis de ambiente nas configurações da Lambda.

4. Execute uma função e verifique os traces no painel Elven.

Boas práticas

• Sempre use variáveis de ambiente para token, tenant e endpoint.

• Defina a versão da Layer no elvenPlugin para garantir consistência entre ambientes.

• Nomeie os serviços e funções de forma clara para facilitar a análise no Grafana e Loki.

• Revise as variáveis injetadas na função durante o deploy para garantir que tudo está correto.

Troubleshooting

Problema	Causa provável	O que verificar
Traces ou logs não aparecem no Grafana	Endpoint ou token incorretos	Revise os valores no ambiente.
Função não instrumentada	disableOtel: true aplicado?	Confirme na config da função.
Lambda com latência alta	Collector ou Loki indisponível	Teste o endpoint e revise timeout.
Variável ausente na função	Sobrescrita na config da função?	Verifique o serverless.yml

Exemplo completo

service: my-awesome-service

plugins:
  - elven-serverless-plugin

custom:
  elvenPlugin:
    tenant: "${env:TENANT_ID}"
    token: "${env:OTEL_API_TOKEN}"
    endpoint: "${env:COLLECTOR_URL}"
    loki_url: "${env:LOKI_URL}"
    env: ${opt:stage, 'dev'}
    region: ${opt:region, 'us-east-1'}
    version: 5

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

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

  processData:
    handler: handler.processData
    events:
      - sqs:
          arn: ${cf:my-queue.QueueArn}
    disableOtel: true  # Exemplo: desativa a instrumentação nesta função

  analyticsJob:
    handler: handler.analytics
    events:
      - schedule: rate(1 hour)

Recursos Adicionais

• Documentação do Serverless Framework

• OpenTelemetry para Lambda

• AWS Lambda Layers

• Suporte Elven

Precisa de ajuda? Entre em contato com nosso time de suporte através do painel Elven Observability ou envie um email para [email protected].