Primeiro trace em 10 minutos

Este guia vai do zero ao primeiro trace com uma API Express mínima. Cada comando foi executado como está aqui; só a chave e, se você usar outra porta, o endereço mudam. Para NestJS, Next.js ou outro framework, faça os passos 1 a 4 e siga para o guia do SDK Node.js.

Antes de começar

• Node.js 20.6 ou mais novo (o exemplo usa node --env-file) e npm. O SDK é ESM.
• Um e-mail em que você recebe mensagens, ou uma conta Google ou Meta.
• Saída HTTPS da sua máquina ou servidor para tracker-api.fortground.com.br.

1. Crie a conta

Abra tracker.fortground.com.br/register e preencha Nome, E-mail e Senha (mínimo de 12 caracteres, com maiúscula, minúscula e número). Clique em Criar conta. Se a página mostrar Continuar com Google ou Continuar com Meta, você pode entrar por eles; nesse caso o e-mail já vem confirmado e o passo 2 é pulado.

A conta é a conta Fortground, a mesma dos outros apps da Fortground: se você já tem uma, use Entrar.

2. Confirme o e-mail

Depois do cadastro o painel abre Confirme seu e-mail. O link não é enviado sozinho: clique em Enviar link de confirmação. Chega uma mensagem com o assunto Confirme seu e-mail · FG Tracker; abra o link no mesmo navegador em que você entrou e clique em Confirmar meu e-mail.

3. Crie o projeto

A tela Configuração inicial abre na etapa Seu projeto. Digite o Nome do projeto (por exemplo, Checkout API) e clique em Criar meu projeto. Mais tarde, outros projetos são criados em Todos os projetos → Novo projeto.

• Quem cria é owner do projeto e pode convidar outras pessoas como admin ou viewer.
• Ambientes e serviços não são cadastrados: eles vêm de cada span (environment e serviceName). Um projeto costuma reunir os serviços de um mesmo sistema; o ambiente separa produção, homologação e desenvolvimento.

4. Copie a chave de servidor

Na etapa Primeira conexão, escolha Instalar SDK. O card Chave deste projeto tem o botão Copiar variáveis .env, que copia duas linhas: FG_TRACKER_KEY=fgsk_… e FG_TRACKER_URL=…. A chave também fica em Configurações → Geral → Chaves de ingestão (só owner e admin a veem).

Projetos criados antes de 15/10/2026 podem ainda não ter chave de servidor: em Chaves de ingestão, clique em Gerar chave de servidor.

5. Instale o SDK

Num diretório novo (ou no seu projeto, se ele já usa ESM):

mkdir checkout-api && cd checkout-api
npm init -y
npm pkg set type=module
npm install express fg-tracker-sdk

Crie o arquivo .env com o que você copiou no passo 4 e acrescente o ambiente:

# .env (não versione este arquivo)
FG_TRACKER_KEY=fgsk_<chave_de_servidor_do_projeto>
FG_TRACKER_URL=https://tracker-api.fortground.com.br
FG_TRACKER_ENV=development

echo ".env" >> .gitignore

6. Conecte a aplicação

Crie server.js. O tracker nasce antes do app, o middleware entra antes de qualquer rota e o encerramento chama tracker.shutdown().

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

// 1. Crie o tracker antes do app e das rotas.
const tracker = createTracker({
  apiKey: process.env.FG_TRACKER_KEY,     // chave de servidor fgsk_… (nunca no navegador)
  endpoint: process.env.FG_TRACKER_URL,   // sem isto o SDK envia para http://localhost:4050
  serviceName: 'checkout-api',            // vira o "serviço" no painel
  // environment: lido de FG_TRACKER_ENV (ou APP_ENV / NODE_ENV)
  debug: true,                            // mostra cada envio no console; desligue depois
});

const app = express();
app.use(tracker.express()); // 2. Primeiro middleware, antes de qualquer rota.

app.get('/hello/:name', (req, res) => {
  res.json({ hello: req.params.name, traceId: tracker.currentTraceId() });
});

const port = Number(process.env.PORT ?? 3000);
const server = app.listen(port, () => console.log(`ouvindo em http://localhost:${port}/hello/mundo`));

// 3. Encerramento: envia o que estiver na fila antes de sair (até 10 s).
for (const signal of ['SIGINT', 'SIGTERM']) {
  process.once(signal, async () => {
    server.close();
    await tracker.shutdown();
    process.exit(0);
  });
}

7. Rode e faça uma requisição

node --env-file=.env server.js

curl -i http://localhost:3000/hello/mundo

HTTP/1.1 200 OK
x-trace-id: f9fb55cd4dc84cf7015c1fae86aa4fc3
Content-Type: application/json; charset=utf-8

{"hello":"mundo","traceId":"f9fb55cd4dc84cf7015c1fae86aa4fc3"}

Cerca de 2 segundos depois, o terminal 1 mostra o envio (por causa do debug: true):

ouvindo em http://localhost:3000/hello/mundo
[fg-tracker] enviados 1 spans (562 bytes).

O header x-trace-id é o id do trace. Guarde-o para achar a requisição no painel.

8. Veja o trace no painel

1. Volte ao painel. Na etapa Primeira conexão, o aviso Aguardando o primeiro sinal vira Primeiro sinal recebido. Clique em Continuar e em Abrir meu projeto. Se você saiu e entrou de novo, o painel abre a lista Projetos: clique em Abrir no seu projeto.
2. No menu lateral, abra Traces. A requisição aparece como GET /hello/:name, serviço checkout-api, ambiente development. O painel atualiza a cada 15 segundos.
3. Clique na linha para ver o waterfall. O endereço da página termina com o mesmo id do header x-trace-id.

9. Encerre sem perder spans

Pare o servidor com Ctrl+C. O handler chama tracker.shutdown(), que envia o que estiver na fila em até 10 segundos antes de sair. Em produção, o mesmo vale para o SIGTERM do orquestrador. Quando estiver tudo certo, remova debug: true.

Scripts e jobs que terminam sozinhos não precisam do handler: o SDK envia a fila no beforeExit. Em AWS Lambda use wrapLambda (veja AWS Lambda).

Nada apareceu?

• Terminal 1 mostra falha ao enviar para http://localhost:4050/v1/ingest: falta o endpoint ou o .env não foi carregado (rode com --env-file=.env).
• Mostra ingest respondeu 401 (lote descartado): a chave está errada ou foi rotacionada. Copie de novo em Chaves de ingestão.
• Mostra a API recusou 1 span(s) (ex.: public_key_not_allowed): você usou a chave pública stk_ num projeto restrito. Use a fgsk_.
• Nenhuma linha [fg-tracker]: o middleware ficou depois das rotas ou a requisição não passou por este processo.
• O console mostra o envio, mas o painel não: confira o projeto selecionado, a janela Últimas 24 horas e o filtro Raiz: HTTP.

O roteiro completo está em Sem dados no painel?

Próximos passos

• SDK Node.js: NestJS, Next.js, Postgres, chamadas HTTP de saída, logs, erros e amostragem.
• Navegador: erros do front com a chave pública e o trace ligado à API.
• MCP: consulte traces e issues pelo seu agente de código.
• API HTTP: leitura com token pessoal e ingestão a partir de outras linguagens.