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

1️⃣ 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.

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:

Ou solicite ao time de suporte da 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.

Muito importante!

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

Você deve:

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

Exemplo:

AWS_LAMBDA_FUNCTION_HANDLER=src/index.handler

2️⃣ 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.

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.

Agora basta salvar e fazer o deploy da sua Lambda.

A instrumentação será automática.

Imagine sua Lambda original configurada com handler:

Handler: src/index.handler

Após instrumentação com a Elven:

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.

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

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

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