AWS Lambda

Spans por invocação com wrapLambda e métricas da plataforma com a camada fg-tracker-lambda-extension.

Conferido com o código e os pacotes publicados em 2026-10-16

SDK e extensão

São duas peças independentes; use uma ou as duas.

Peças para AWS Lambda
Peça	O que mede	Exige código?
`tracker.wrapLambda` do `fg-tracker-sdk`	Um trace por invocação, com as queries e chamadas HTTP feitas dentro dela.	sim, envolver o handler
Camada `fg-tracker-lambda-extension` (0.2.0)	Invocações, erros, timeouts, cold starts, duração, memória e concorrência, pela Telemetry API da Lambda.	não, só a camada e duas variáveis

Spans por invocação (wrapLambda)

handler.mjs

import { createTracker } from 'fg-tracker-sdk';

const tracker = createTracker({
  apiKey: process.env.FG_TRACKER_KEY,
  endpoint: process.env.FG_TRACKER_URL,
  serviceName: 'checkout-worker',
});

export const handler = tracker.wrapLambda(async (event) => {
  // ...
  return { statusCode: 200 };
}, { flushTimeoutMs: 1000 });

Cada invocação vira um span raiz custom chamado lambda <função>, com faas.coldStart e o id da requisição. No painel, ele aparece como job (em Traces, use Raiz: Jobs ou Todas).
Sem a camada, o fim de cada invocação espera o envio por até flushTimeoutMs (1 s), para não perder spans no congelamento do ambiente. Com a API fora do ar, a invocação atrasa no máximo esse prazo.
Com a camada instalada, o SDK não segura a resposta: a fila é enviada no encerramento do ambiente.
A partir da versão 0.11.0, continua o trace de quem disparou a função quando o evento tem origem única: um record SQS publicado por um client instrumentado, EventBridge com detail.traceparent ou HTTP com header traceparent. Veja Filas e eventos; continueTrace: false desliga.
Só handlers async; handlers com callback não são suportados.

Publicar a camada da extensão

A camada é regional e fica na sua conta. O pacote do npm já traz o zip pronto (dist/layer.zip); publique-o na região da função com a AWS CLI:

terminal

npm pack fg-tracker-lambda-extension@0.2.0
tar -xzf fg-tracker-lambda-extension-0.2.0.tgz package/dist/layer.zip
aws lambda publish-layer-version \
  --layer-name fg-tracker-extension \
  --zip-file fileb://package/dist/layer.zip \
  --compatible-runtimes nodejs20.x nodejs22.x nodejs24.x \
  --compatible-architectures x86_64 arm64

O comando devolve o LayerVersionArn. Repita em cada região onde houver funções. O zip é reproduzível: a mesma versão do pacote sempre gera o mesmo conteúdo.

Anexar à função

No CDK:

stack.ts

const layer = lambda.LayerVersion.fromLayerVersionArn(this, 'FgTracker', '<arn_da_camada_publicada>');

new lambda.Function(this, 'Checkout', {
  runtime: lambda.Runtime.NODEJS_22_X,
  layers: [layer],
  environment: {
    FG_TRACKER_URL: 'https://tracker-api.fortground.com.br',
    FG_TRACKER_KEY: process.env.FG_TRACKER_KEY!,   // fgsk_…, vindo do seu cofre de segredos
  },
  // ...
});

Variáveis da extensão

Variáveis lidas pela extensão
Variável	Padrão	Uso
`FG_TRACKER_URL`	—	URL base da API. Sem ela, a extensão fica ociosa e a função segue normal.
`FG_TRACKER_KEY`	—	Chave de servidor `fgsk_…` (a pública `stk_` só funciona no modo legado).
`FG_TRACKER_INFRA_INTERVAL_MS`	`60000`	Janela de envio; cai para 5 s enquanto alguém observa o diagrama de infraestrutura no painel.
`FG_TRACKER_DEBUG`	—	`1` registra cada envio no log da função.

O SDK, ao contrário da extensão, não lê FG_TRACKER_URL sozinho: no createTracker, passe endpoint: process.env.FG_TRACKER_URL como no exemplo.

Limites

Só runtimes Node.js 20, 22 e 24 (a extensão roda com o Node do próprio runtime), x86_64 ou arm64. Python, Java e runtimes customizados não são suportados.
A extensão nunca derruba a função: sem configuração ou sem rede, ela fica ociosa.
Custo aproximado: 15 a 25 MB de memória e 50 a 100 ms a mais no cold start (estimativa do pacote, não medida nesta documentação).