AWS Lambda Node.js — Instrumentação Zero-Code com Elven Observability Layer

Visão Geral

A Elven fornece Layers de instrumentação para AWS Lambda, permitindo:

• Captura automática de logs, métricas e traces.

• Envio de dados para a plataforma Elven Observability com zero código.

• Totalmente gerenciado via Layers e variáveis de ambiente.

• Compatível com qualquer linguagem de runtime da Lambda, através do nosso bootstrap universal.

Esta documentação descreve como instrumentar sua Lambda com as Layers oficiais da Elven.

Pré-requisitos

• A função Lambda já deve estar implementada e funcional.

• Permissão para modificar a configuração da Lambda (Layers e variáveis de ambiente).

• Ter o Tenant ID e Token de autenticação fornecidos pela Elven Observability.

Se você não possui o Tenant ID e Token, acesse:

https://elvenobservability.com

Ou solicite ao time de suporte da Elven.

Configurando a Lambda

Passo 1 — Adicionar a Layer Elven

Escolha a Layer conforme o seu caso:

Layer	ARN
elven-instrumentation-js (completo: logs + metrics + traces)	(usar a lista de ARNs abaixo)

Exemplo (us-east-1):

arn:aws:lambda:us-east-1:204595508824:layer:elven-instrumentation-js:1

• No console AWS Lambda, vá em sua função > Configuration > Layers > Add a layer.

• Adicione a Layer pelo ARN da sua região.

Passo 2 — Alterar o Handler

Muito importante: Por padrão, a Layer Elven intercepta a execução da Lambda através do Bootstrap próprio.

Você deve:

Definir o verdadeiro path do seu handler na variável de ambiente AWS_LAMBDA_FUNCTION_HANDLER.

Exemplo:

AWS_LAMBDA_FUNCTION_HANDLER=src/index.handler

Definir o bootstrap da Elven:

No console, adicione:

AWS_LAMBDA_EXEC_WRAPPER=/opt/bootstrap

Isso garante que o bootstrap Elven inicialize primeiro, antes de chamar seu handler real.

Passo 3 — Configurar as variáveis de ambiente

Abaixo a lista completa:

Variável	Descrição	Exemplo
AWS_LAMBDA_FUNCTION_HANDLER	Caminho real do seu handler	src/index.handler
AWS_LAMBDA_EXEC_WRAPPER	Sempre /opt/bootstrap	/opt/bootstrap
LOKI_URL	Endpoint do Loki da Elven	https://loki.elvenobservability.com/loki/api/v1/push
LOKI_AUTH_TOKEN	Token de autenticação	(fornecido pela Elven)
LOKI_TENANT_ID	Tenant ID do cliente	(fornecido pela Elven)
LOKI_APP_NAME	Nome da aplicação (para labeling)	my-app
LOKI_COOPERATIVE_MODE	Habilita modo resiliente	true
LOKI_PURE_HANDLER	Modo seguro de interceptação	true
LOKI_SAFE_INIT	Habilita inicialização protegida	true
OTEL_EXPORTER_OTLP_ENDPOINT	Endpoint do seu OTEL Collector	http://my-otel-collector.com:4318
OTEL_SERVICE_NAME	Nome do serviço (traces)	my-app
OTEL_RESOURCE_ATTRIBUTES	Atributos adicionais de recurso	service.name=my-app,environment=production
OTEL_LAMBDA_TRACE_MODE	Ativa captura de traces	capture
OTEL_LOG_LEVEL	Log interno do SDK	error
OTEL_PROPAGATORS	Propagadores ativos	tracecontext,baggage,xray
OTEL_TRACES_SAMPLER	Sampling de traces	always_on

Nota importante:

• As variáveis LOKI_AUTH_TOKEN e LOKI_TENANT_ID são fornecidas pela Elven.

• É necessário também possuir um OpenTelemetry Collector ativo e acessível para o envio de traces e métricas (OTEL_EXPORTER_OTLP_ENDPOINT).

• Caso não possua o Token, Tenant ID ou Collector configurado, entre em contato com o suporte da Elven.

Passo 4 — Deploy

Agora basta salvar e fazer o deploy da sua Lambda.

A instrumentação será automática.

Exemplos práticos

Exemplo 100% funcional

Imagine sua Lambda original configurada com handler:

Handler: src/index.handler

Após instrumentação com a Elven:

• No campo Handler da Lambda (console AWS), deixe o que quiser (não importa).

• Adicione:

AWS_LAMBDA_FUNCTION_HANDLER=src/index.handler
AWS_LAMBDA_EXEC_WRAPPER=/opt/bootstrap
# e todas as variáveis do bloco 3

Pronto. Não é necessário alterar código.

Problemas comuns & Troubleshooting

Problema	Causa	Solução
Cannot find handler.	AWS_LAMBDA_FUNCTION_HANDLER não está definido corretamente.	Verifique o path exato do handler, incluindo subpastas.
Timeout na inicialização.	Falha de rede para conectar Loki/OTEL.	Verifique se sua Lambda tem acesso à internet ou endpoints privados.
Dados não aparecem no Elven.	Token ou Tenant incorretos.	Solicite novos dados de autenticação ao suporte.

Suporte & Contato

Caso precise de ajuda para configuração, onboarding ou troubleshooting, entre em contato:

📧 [email protected]

🌐 https://elvenobservability.com

ARNs completos das Layers (por região)

• us-east-1: arn:aws:lambda:us-east-1:204595508824:layer:elven-instrumentation-js:1

• us-east-2: arn:aws:lambda:us-east-2:204595508824:layer:elven-instrumentation-js:1

• us-west-1: arn:aws:lambda:us-west-1:204595508824:layer:elven-instrumentation-js:1

• us-west-2: arn:aws:lambda:us-west-2:204595508824:layer:elven-instrumentation-js:1

• sa-east-1: arn:aws:lambda:sa-east-1:204595508824:layer:elven-instrumentation-js:1