O que é o stread-track?
É o APM interno da Stread para backends Node.js. Mede latência p50/p95/p99 por endpoint, grava traces em waterfall, detecta N+1 e loops, centraliza logs, envia alertas por e-mail e WhatsApp e explica problemas com IA.
143 ms. 26 queries. 25 iguais.
Num trace do projeto demo, GET /api/tasks/:id/events roda select * from users where id = ? 25 vezes no mesmo request. O stread-track marca isso sozinho, com limiar de 10×.
trace dc1a2554 · demo-stread-console · 12/09 11:07
O que é o stread-track
stread-track é o APM (Application Performance Monitoring) interno da Stread para backends Node.js. Ele mede o tempo de resposta de cada endpoint (p50, p95, p99), grava traces completos em waterfall, detecta automaticamente N+1 e loops, centraliza logs, dispara alertas por e-mail e WhatsApp e explica os problemas com IA. A instrumentação leva três linhas de código.
01Como funciona
Do request ao alerta em quatro passos
O SDK gera spans, a API grava e roda os detectores, o painel consulta e as regras avisam. Nada de agente na máquina nem sidecar.
- 01
passo 01
SDK
Três linhas na sua app Express, NestJS ou Next.js. Zero dependências de runtime; spans encadeados por AsyncLocalStorage.
app.use(tracker.express()) - 02
passo 02
Ingest
A cada 2 s (ou 200 spans) o SDK envia um lote agrupado por traceId para POST /v1/ingest, autenticado pela chave stk_… do projeto.
POST /v1/ingest → 202 { accepted } - 03
passo 03
Detecção
Quatro detectores rodam a cada lote: N+1, loop, endpoint lento e erro. Issues têm fingerprint estável, então a mesma causa vira uma linha só.
n+1:GET /orders/:id:select … ×37 - 04
passo 04
Alerta e insight
Regras por projeto (p95 dobrou, 5xx em rajada, query lenta) avisam por e-mail e WhatsApp. A IA diagnostica o trace e sugere a correção.
[stread-track] critical · checkout · p95 2,4 s
02Workflow em vídeo
Três fluxos, dezesseis segundos cada
Integração, detecção de N+1 com alerta e conexão pelo MCP. Cenas geradas a partir do produto, sem stock.
Vídeo selecionado: Integração em 3 linhas
03Recursos
O que o painel mostra
Fatos medidos por projeto. Quem decide a gravidade é o operador.
Latência p50 / p95 / p99
Tempo de resposta, throughput e taxa de erro por endpoint. Ranking de rotas lentas e sparkline de 24 pontos.
p50 42 ms · p95 180 ms · p99 610 ms
Traces em waterfall
HTTP → queries → chamadas externas, com duração, profundidade e o span exato que ficou lento.
http.server · db.query · http.client
N+1 e loops
A mesma query ou chamada repetida dezenas de vezes num único request vira uma issue com contagem e severidade.
≥ 10 spans iguais sob o mesmo pai
Logs com busca
pino, winston ou Nest logger enviam para a plataforma. Busca por texto, frase, key=value e correlação com o trace.
retenção 7 dias · tail ao vivo
Alertas por e-mail e WhatsApp
Sete regras prontas ao criar o projeto: pico de requests, taxa de erro, rajada 5xx, regressão de p95, query lenta, timeouts, issue crítica.
cooldown 30 min por fingerprint
IA Insights
Pergunte por que o p95 subiu. O modelo consulta os mesmos dados do painel e responde com diagnóstico, evidências e recomendações.
só metadados de spans vão ao modelo
MCP plug-and-play
Servidor MCP para Claude Code, Cursor e Windsurf: o agente cria o projeto, instrumenta o código e verifica a ingestão sozinho.
npx -y stread-track-mcp
04Integração
Três linhas e o primeiro trace chega
stread-track-sdk não tem dependências de runtime. Cria um span http.server por request, db.query para cada query do pg e http.client para fetch, encadeados por AsyncLocalStorage.
- 3linhas
- 0deps de runtime
- 2 spor lote
- 200spans por lote
- Envio em lote a cada 2 s ou 200 spans, fora do caminho da resposta.
tracker.instrumentPg(pool)para drizzle, kysely, knex ou pg puro.- Sem SDK: qualquer linguagem envia JSON para
POST /v1/ingest.
server.ts
import { createTracker } from 'stread-track-sdk';const tracker = createTracker({ apiKey: process.env.STREAD_TRACK_KEY!, serviceName: 'minha-api' });app.use(tracker.express()); // antes de qualquer outro middleware/rotasrc/main.ts
import { createTracker } from 'stread-track-sdk';export const tracker = createTracker({ apiKey: process.env.STREAD_TRACK_KEY!, serviceName: 'stread-execution' });app.use(tracker.express()); // dentro do bootstrap(), antes de helmet/cors/pipesapp/api/users/[id]/route.ts
import { createTracker } from 'stread-track-sdk';const tracker = createTracker({ apiKey: process.env.STREAD_TRACK_KEY!, serviceName: 'stread-media-kit' });export const GET = tracker.wrapNextRoute(async (req) => Response.json({ ok: true }));logger.ts
import pino from 'pino';export const logger = pino({ transport: { target: 'stread-track-sdk/pino', options: { apiKey: process.env.STREAD_TRACK_KEY, service: 'minha-api' } } }); // traceId correlacionadopnpm add stread-track-sdk · Node ≥ 20 · ESM (CommonJS via require() no Node ≥ 22.12)
Plug-and-play com IA (MCP)
Peça ao agente: “conecte meu projeto ao stread-track”
O servidor MCP stread-track-mcp expõe projetos, métricas, traces e logs para qualquer agente que fale MCP. O prompt instrument-project guia o agente: detectar o framework, instalar o SDK, aplicar middleware, pg e logs, rodar e verificar a ingestão.
Qual IA você usa?
terminal
$ claude mcp add stread-track -e STREAD_TRACK_URL=https://api.track.stread.com.br -e STREAD_TRACK_API_KEY=stk_... -- npx -y stread-track-mcpDepois, no terminal: claude → "conecte meu projeto ao stread-track".
- track_status
- track_list_projects
- track_create_project
- track_get_overview
- track_list_endpoints
- track_list_issues
- track_get_trace
- track_search_logs
- track_instrumentation_guide
- track_verify_ingest
Interno da Stread
Sem plano, sem cobrança: é a ferramenta dos times da Stread
Projetos e chaves stk_… são criados no painel por quem tem conta na Stread Identity. Cada app manda spans e logs para o seu próprio projeto; retenção de 14 dias para spans e 7 para logs.
05Perguntas frequentes
Respostas diretas
Quais frameworks o SDK suporta?
Express, NestJS (platform-express), Next.js App Router (route handlers no runtime Node), pg.Pool (e ORMs sobre ele como drizzle, kysely e knex), fetch global e spans manuais. Logs via pino, winston e o logger do Nest. Qualquer linguagem pode enviar spans direto para POST /v1/ingest.
Como o N+1 é detectado?
O SDK normaliza o SQL (where id = 1 e where id = 2 viram where id = ?). Se dez ou mais spans db.query com o mesmo nome aparecem sob o mesmo span pai dentro de um trace, o detector cria uma issue N+1 com contagem, tempo total e severidade.
Quanto custa em latência para a aplicação?
O middleware cria um span por request e enfileira em memória; o envio acontece em lote a cada 2 segundos (ou 200 spans) fora do caminho da resposta. O timer usa unref(), então não segura o processo, e uma falha de envio é logada uma vez e reenviada no próximo lote.
Quais dados a IA Insights recebe?
Só metadados de spans: rotas, durações, queries normalizadas, atributos e as issues. O modelo consulta esses dados por tools (as mesmas consultas do painel) e não tem acesso ao banco nem ao código da aplicação instrumentada.
Posso usar fora da Stread?
Hoje o stread-track é uma ferramenta interna dos times da Stread, sem plano público nem cobrança. Projetos e chaves são criados no painel por quem tem conta na Stread Identity.