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 support@elvenobservability.com