Kmind APM Web

• Uma aplicacao web publicada ou em desenvolvimento, com Node.js e npm para instalar dependencias.
• Acesso ao Console Kmind para cadastrar o servico Frontend / APM Web.
• A URL onde o site roda, como https://app.exemplo.com ou http://localhost:5173.

1. Em Clusters, escolha ou crie um cluster do tipo Cloud.
2. Adicione um servico do tipo Frontend / APM Web.
3. Informe as origens permitidas. Cada origem deve conter protocolo e host, por exemplo https://app.exemplo.com.
4. Conclua o wizard e copie a client key exibida na etapa de conexao.

Instale o pacote e chame init uma unica vez, logo no ponto de entrada do navegador.

npm install kmind-apm-web

import { init } from "kmind-apm-web";

init({
  applicationName: "portal-cliente",
  clientKey: "kmw_COLE_A_SUA_CHAVE_AQUI",
  captureConsole: true,
});

Troque portal-cliente por um nome estavel e facil de reconhecer no Console. Nao use o nome do cluster como nome da aplicacao: nexus_cliente e nexus_admin podem usar a mesma client key e aparecerao como aplicacoes separadas.

1. Abra o site em uma origem permitida.
2. Em DevTools > Network, confirme GET /v1/apm/status com resposta { "active": true }.
3. Navegue, clique em elementos e faca uma chamada HTTP para gerar traces e metricas.
4. No Kmind, abra Aplicacoes e selecione o applicationName configurado.

// Teste opcional de log. Remova depois de validar.
import { logger } from "kmind-apm-web";
logger.info("Kmind APM Web configurado com sucesso");

Erros globais do navegador sao registrados automaticamente. Para eventos de negocio, use o logger do Kmind; ele associa o log ao trace ativo quando existir.

import { logger } from "kmind-apm-web";

logger.info("Checkout iniciado", { cartId: "c_123" });
logger.warn("Estoque baixo", { sku: "sku-42" });
logger.error("Pagamento recusado", { provider: "cartao" });

captureConsole: true coleta somente console.warn e console.error. Ele nao coleta console.log para evitar ruido, dados desnecessarios e custo operacional. Os logs sao enviados em lote; aguarde alguns segundos antes de consultar o Logs Explorer.

Para relacionar uma tela com a API que ela chama, informe somente os hosts autorizados em propagateTraceTo. O SDK adiciona o cabecalho traceparent apenas nesses destinos.

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

Os wrappers sao opcionais. O pacote base funciona em qualquer framework; use um wrapper quando quiser integracao de rota e Error Boundary pronta.

React com Vite

npm install kmind-apm-web-react

// src/main.tsx
import { initKmindReact, KmindErrorBoundary } from "kmind-apm-web-react";
initKmindReact({ captureConsole: true });
root.render(<KmindErrorBoundary><App /></KmindErrorBoundary>);

# .env
VITE_KMIND_APPLICATION_NAME=portal-cliente
VITE_KMIND_CLIENT_KEY=kmw_...

Vue 3 com Vite

npm install kmind-apm-web-vue

// src/main.ts
import { createApp } from "vue";
import { initKmindVue, installKmindVue } from "kmind-apm-web-vue";
initKmindVue({ captureConsole: true });
const app = createApp(App);
app.use(router);
installKmindVue(app, router);
app.mount("#app");

# .env
VITE_KMIND_APPLICATION_NAME=portal-cliente
VITE_KMIND_CLIENT_KEY=kmw_...

Next.js

npm install kmind-apm-web-next

// app/kmind-provider.tsx
"use client";
import { useEffect } from "react";
import { initKmindNext, KmindNextNavigation } from "kmind-apm-web-next";

export function KmindProvider() {
  useEffect(() => { initKmindNext({ captureConsole: true }); }, []);
  return <KmindNextNavigation />;
}

# .env.local
NEXT_PUBLIC_KMIND_APPLICATION_NAME=portal-cliente
NEXT_PUBLIC_KMIND_CLIENT_KEY=kmw_...

Renderize o provider no layout do app. A inicializacao deve ocorrer somente no cliente, nunca durante SSR.

init({
  applicationName: "portal-cliente",
  clientKey: "kmw_...",
  endpoint: "https://ingest.kmind.com.br/v1",
  statusEndpoint: "https://ingest.kmind.com.br/v1/apm/status",
  sampleRate: 0.2,
  slowTraceThresholdMs: 1200,
  captureConsole: true,
  propagateTraceTo: ["api.exemplo.com"],
  privacy: {
    redactAttributeKeys: ["email", "cpf", "authorization", "user.id"],
    redactUrlQueryKeys: ["token", "session"],
  },
  scrub: (value, key) => key === "order.id" ? "[redacted]" : value,
});

• sampleRate: proporcao de traces normais enviados, entre 0 e 1. Comece com 0.2 em sites muito acessados.
• slowTraceThresholdMs: traces lentos acima desse tempo sao preservados mesmo fora da amostra.
• privacy e scrub: removem dados sensiveis antes de qualquer envio.
• enabled: false: desliga toda a coleta sem remover o codigo de integracao.

A biblioteca opera em modo best effort: falhas de telemetria nao interrompem fetch, XHR, navegacao ou o fluxo normal do site. Os eventos usam fila limitada, lotes de ate 20 itens e timeout de tres segundos. Sob pressao, a telemetria e descartada antes de disputar memoria ou conexoes com a aplicacao.

Nao inicialize o pacote mais de uma vez. Em SPAs, inicialize no bootstrap e deixe os wrappers registrarem as trocas de rota.

Status retorna 403 ou erro de CORS

Cadastre a origem exata no Console. https://app.exemplo.com, http://localhost:5173 e https://www.exemplo.com sao origens diferentes.

Metricas aparecem, mas logs ficam em zero

Use logger.info para um teste ou habilite captureConsole: true. A SDK nao envia automaticamente todos os console.log.

Nao ha trace entre frontend e API

Confirme que o host da API esta em propagateTraceTo, que o backend aceita traceparent e que a API tambem esta instrumentada.

A aplicacao nao aparece no Console

Confira a client key, o applicationName, a origem permitida e a resposta de /v1/apm/status. Depois gere navegacao ou uma chamada HTTP real.

npm install kmind-apm-web@latest

# React, Vue ou Next.js
npm install kmind-apm-web-react@latest
npm install kmind-apm-web-vue@latest
npm install kmind-apm-web-next@latest

# Remocao
npm uninstall kmind-apm-web

Para remover completamente, elimine a chamada de init, wrappers e variaveis publicas do build antes de publicar uma nova versao do frontend.