Aplicação

APM Kmind para Node.js

Instrumente Node.js 18 ou superior com OpenTelemetry e logs correlacionados.

1. Instale o pacote

npm install kmind-apm

2. Configure o ambiente

OTEL_ENABLE_TRACE=true
OTEL_SERVICE_NAME=minha-api
OTEL_EXPORTER_OTLP_ENDPOINT=https://tempo.kmind.com.br/v1/traces
OTEL_TENANT_ID=minha-organizacao
OTEL_CLUSTER_NAME=meu-cluster-producao

3. Inicialize antes do framework

import 'kmind-apm/init';
import express from 'express';

4. Variaveis e compatibilidade

Requer Node.js 18+ e TypeScript 4.8+. Express 4/5, Apollo Server 4, NestJS 9/10 e Node.js sem framework sao suportados.

OTEL_ENABLE_TRACE=true
OTEL_SERVICE_NAME=customer-api
OTEL_EXPORTER_OTLP_ENDPOINT=<ENDPOINT_INFORMADO_PELO_KMIND>
OTEL_TENANT_ID=customer
OTEL_CLUSTER_NAME=customer-prd
DEBUG_HTTP_REQUESTS=false
ENABLE_TRACE_DEBUG=false

5. Exemplos por framework

Express

import 'kmind-apm/init';
import express from 'express';
const app = express();
app.get('/', (req, res) => res.json({ status: 'ok' }));
app.listen(3000);

NestJS

import 'kmind-apm/init';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT || 3000);
}
bootstrap();

Apollo Server e Node.js

import 'kmind-apm/init';
import { ApolloServer } from '@apollo/server';
const server = new ApolloServer({ typeDefs, resolvers });

// Sem framework: importe kmind-apm/init antes do código da aplicação.

6. Kubernetes, .env e Docker

Forneca as mesmas variaveis ao Deployment, StatefulSet, arquivo .env ou container. Publique uma nova versão da aplicação depois da configuração.

env:
  - name: OTEL_ENABLE_TRACE
    value: 'true'
  - name: OTEL_SERVICE_NAME
    value: 'customer-api'
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: '<ENDPOINT_INFORMADO_PELO_KMIND>'

7. Validar a instalação

Gere requisições reais ou de teste e confirme no Kmind que o serviço aparece com o mesmo valor de OTEL_SERVICE_NAME e que os traces foram recebidos.

npm list kmind-apm
curl https://SUA_APLICACAO/health

8. Troubleshooting

Se a aplicação não aparecer, valide OTEL_ENABLE_TRACE, OTEL_SERVICE_NAME e o endpoint. Teste DNS, TLS, firewall e egress a partir do mesmo ambiente da aplicação.

curl <OTEL_EXPORTER_OTLP_ENDPOINT>
ENABLE_TRACE_DEBUG=true
DEBUG_HTTP_REQUESTS=true

Use os modos de diagnóstico apenas temporariamente e retorne ambos para false em produção.

9. Atualização e remoção

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

npm uninstall kmind-apm

Ao remover, elimine a inicialização e as variáveis OTEL exclusivas da integração, gere uma nova build e publique novamente.