Kmind APM para Node.js

• Uma aplicacao com Node.js 18.19+ ou 20.6+ e acesso ao npm.
• Acesso ao Console Kmind para criar um servico Backend / APM Node.
• Acesso HTTPS de saida do servidor para ingest.kmind.com.br.

1. Em Clusters, escolha o ambiente onde o backend sera executado.
2. Adicione um servico do tipo Backend / APM Node.
3. Conclua o wizard e copie a service key exibida na conexao.
4. Cadastre a chave como segredo no ambiente de deploy da API ou worker.

Instale o pacote no projeto. Para a instrumentacao automatica detectar Express, NestJS, HTTP, bancos de dados e outros modulos suportados, carregue o Kmind antes deles.

npm install kmind-apm

# Producao com JavaScript compilado
node --require kmind-apm/init dist/main.js

# Desenvolvimento com TypeScript e tsx
node --require kmind-apm/init --import tsx src/main.ts

Configure as variaveis no ambiente que executa o processo. Em producao, prefira os secrets do provedor a um arquivo .env versionado.

# .env
KMIND_APPLICATION_NAME=orders-api
KMIND_SERVICE_KEY=kms_COLE_A_CHAVE_PRIVADA_AQUI
KMIND_OTLP_ENDPOINT=https://ingest.kmind.com.br/v1/server

# Controles opcionais
KMIND_APM_ENABLED=true
KMIND_TRACE_SAMPLE_RATE=1
KMIND_CAPTURE_LOGS=true
KMIND_APM_DEBUG=false

Tambem e possivel chamar init manualmente, desde que essa seja a primeira importacao da aplicacao e aconteca antes de framework, driver de banco ou cliente HTTP.

import { init } from "kmind-apm";

init({
  applicationName: "orders-api",
  serviceKey: process.env.KMIND_SERVICE_KEY,
});

// Importe Express, NestJS, banco de dados e clientes HTTP somente depois.

Em APIs que controlam o proprio processo, finalize o SDK durante o desligamento. Isso da tempo para enviar o lote final sem atrasar o encerramento indefinidamente.

import { stopTracing } from "kmind-apm";

const server = app.listen(3000);

async function shutdown() {
  server.close();
  await stopTracing();
}

process.on("SIGTERM", () => void shutdown());
process.on("SIGINT", () => void shutdown());

1. Publique a aplicacao com as variaveis configuradas.
2. Faca uma requisicao real para um endpoint da API.
3. Confira os logs do processo para erros de rede ou de configuracao.
4. No Kmind, abra Aplicacoes e localize o KMIND_APPLICATION_NAME configurado.

# Confirme a versao instalada
npm list kmind-apm

# Teste a API a partir de um cliente
curl https://api.exemplo.com/health

O logger do pacote grava JSON no stdout ou stderr e, quando KMIND_CAPTURE_LOGS=true, envia a mesma informacao ao Kmind com o traceId e spanId ativos. Use-o para eventos de negocio e falhas que precisam aparecer no Logs Explorer.

import { logger } from "kmind-apm";

logger.info("Pedido criado", { order_id: order.id, total: order.total });
logger.warn("Provedor esta lento", { provider: "pagamentos", timeout_ms: 1200 });
logger.error("Pagamento recusado", { order_id: order.id, error_code: error.code });

Para Express, os middlewares opcionais registram requisicoes de diagnostico e erros nao tratados. O errorHandler deve ser o ultimo middleware da cadeia.

import express from "express";
import { errorHandler, requestLogger } from "kmind-apm";

const app = express();
app.use(requestLogger);

app.get("/orders/:id", (req, res) => {
  res.json({ id: req.params.id });
});

app.use(errorHandler);

Quando uma aplicacao usa o Kmind APM Web e chama uma API instrumentada, o cabecalho W3C traceparent mantem o mesmo trace entre navegador e servidor. O APM Node extrai esse contexto automaticamente.

1. No frontend, inclua o host da API em propagateTraceTo.
2. No CORS da API, permita o cabecalho traceparent em chamadas cross-origin.
3. Nao substitua ou remova esse cabecalho em middlewares ou proxies.

// Kmind APM Web
init({
  applicationName: "portal-cliente",
  clientKey: "kmw_...",
  propagateTraceTo: ["api.exemplo.com"],
});

// API: mantenha o traceparent recebido e inicialize kmind-apm antes do framework.

import { init } from "kmind-apm";

init({
  applicationName: "orders-api",
  serviceKey: process.env.KMIND_SERVICE_KEY,
  endpoint: "https://ingest.kmind.com.br/v1/server",
  sampleRate: 0.25,
  captureLogs: true,
  enabled: true,
  debug: false,
});

• applicationName: nome exibido no Kmind. Se omitido, usa KMIND_APPLICATION_NAME, OTEL_SERVICE_NAME ou node-service.
• sampleRate e KMIND_TRACE_SAMPLE_RATE: amostragem de traces novos entre 0 e 1. Comece com 1 e reduza apenas quando o volume justificar.
• captureLogs e KMIND_CAPTURE_LOGS: habilitam ou desabilitam apenas a exportacao de logs do logger.
• enabled: false ou KMIND_APM_ENABLED=false: desliga a coleta sem alterar o comportamento da aplicacao.

A instrumentacao envia traces, metricas e logs de forma assincrona. O exportador de metricas roda a cada 60 segundos, usa timeout de cinco segundos e limita uma exportacao simultanea. Se o gateway estiver indisponivel, a aplicacao continua atendendo suas requisicoes normalmente.

Inicialize o pacote uma unica vez por processo. Chamadas repetidas de initsao seguras, mas nao inicializam um segundo SDK. Para reduzir volume, use amostragem em vez de criar logica manual nos endpoints.

A aplicacao nao aparece no Console

Verifique KMIND_SERVICE_KEY, KMIND_APPLICATION_NAME, acesso de saida para o gateway e se houve ao menos uma requisicao apos o deploy. Habilite KMIND_APM_DEBUG=true temporariamente para diagnosticar a inicializacao.

Nao ha traces automaticos

Garanta que kmind-apm/init seja carregado antes de Express, NestJS, drivers de banco e clientes HTTP. Reinicie o processo depois de corrigir a ordem dos imports.

Logs ficam em zero

Confirme KMIND_CAPTURE_LOGS=true e use o logger exportado pelo pacote. Logs de bibliotecas externas e chamadas diretas a console.log nao sao reenviados automaticamente.

Nao ha trace entre frontend e API

Confirme propagateTraceTo no frontend, o CORS da API para traceparent e a instrumentacao do backend antes dos imports do framework.

# Atualizar
npm install kmind-apm@latest
npm list kmind-apm

# Remover
npm uninstall kmind-apm

Para remover completamente, retire kmind-apm/init ou a chamada de init, os middlewares opcionais e as variaveis KMIND_* do ambiente antes de publicar uma nova versao.