Loki Console Logger JS – Documentação

Elven Observability Official Logger

Um coletor de logs, eventos e exceções para apps Node.js que envia tudo ao Grafana Loki. Oferece interceptação automática de console, suporte a labels dinâmicas, envio assíncrono com buffer e integração instantânea com o Elven Stack.

1✨ Features

⚡ Alta performance com buffer assíncrono e envio em lote

🔗 Captura automática de:

console.log, console.error, console.warn, etc
Exceções não tratadas
Eventos personalizados via trackEvent

🏷️ Suporte a labels fixas e dinâmicas (com trace/span id via OpenTelemetry)

📦 Buffer com envio em lote configurável

✅ Resiliente a falhas de rede

🧵 Compatível com apps simples ou complexos (ex: web servers, workers)

🔁 Garantia de envio no encerramento do processo

2📦 Instalação

npm install loki-console-logger-js

3🚀 Uso Básico

import { interceptConsole, trackEvent } from "loki-console-logger-js";

interceptConsole({
  url: "https://loki.elvenobservability.com/loki/api/v1/push",
  tenantId: "seu-tenant", // Seu Tenant ID
  appName: "my-js-app",
  authToken: "seu-token", // Seu JWT
  batchSize: 10,
  flushInterval: 2000,
  labels: { env: "production" },
  dynamicLabels: {
    hostname: () => "api-js-01.local",
  },
});

console.log("Isso será enviado ao Loki!");
trackEvent("usuario_cadastrado", { user_id: 123 });
throw new Error("Erro de teste!"); // Capturado automaticamente

4⚙️ Opções de Configuração

Parâmetro	Tipo	Descrição	Padrão
`url`	`string`	Endpoint do Loki (Push API)	—
`tenantId`	`string`	Usado no header `X-Scope-OrgID`	—
`appName`	`string`	Nome da aplicação (label fixa)	—
`authToken`	`string`	Token JWT para autenticação	`undefined`
`batchSize`	`number`	Tamanho do buffer antes de forçar envio	`10`
`flushInterval`	`number` (ms)	Tempo máximo antes do envio (ms)	`2000`
`labels`	`Record<string, string>`	Labels fixas por log	`{}`
`dynamicLabels`	`Record<string, () => string>`	Labels geradas dinamicamente a cada envio	`{}`

5🧪 Exemplo com Express.js

import express from "express";
import { interceptConsole, trackEvent } from "loki-console-logger-js";

interceptConsole({
  url: "https://loki.elvenobservability.com/loki/api/v1/push",
  tenantId: "seu-tenantId",
  authToken: "seu-token",
  appName: "express-app",
  labels: { env: "dev" },
  dynamicLabels: {
    hostname: () => "devbox-js",
  },
});

const app = express();

app.get("/ping", (req, res) => {
  console.log("ping chamado");
  trackEvent("ping");
  res.send({ message: "pong" });
});

app.get("/erro", () => {
  throw new Error("Erro proposital");
});

app.listen(3000, () => {
  console.log("Servidor iniciado na porta 3000");
});

6💡 Boas Práticas

Situação	Recomendações
Scripts curtos (CLI, cron)	Prefira `process.exit()` no final, já que o envio é forçado via `process.on`
Apps web ou workers	A configuração padrão já garante envio em background
Ambientes com alta concorrência	Use `batchSize` alto (20+) e ajuste `flushInterval` para evitar sobrecarga
Ambientes com OpenTelemetry	Labels `trace_id` e `span_id` são capturados automaticamente

7🧯 Troubleshooting

Problema	Causa comum	Solução
Logs não aparecem no Loki	`tenantId`, `authToken` ou `labels` errados	Verifique headers e use `trackEvent()` para testar
Logs incompletos	Processo encerrando rápido demais	Use `process.exit()` ou aguarde flush automático
Falha no envio	Loki indisponível ou token inválido	Verifique a URL e o token JWT

8🔄 Flush manual (opcional)

Atualmente o envio é automático com flush no exit, SIGINT, uncaughtException, etc.

Mas se quiser forçar o envio manual:

import { flushLogs } from "loki-console-logger-js";

flushLogs(); // Envia os logs imediatamente

9📤 Eventos customizados

trackEvent("usuario_ativo", {
  user_id: "abc123",
  source: "mobile",
});

No Loki aparecerá como:

[EVENT] usuario_ativo {"user_id": "abc123", "source": "mobile"}

10📁 Formato dos Logs no Loki

Cada log enviado inclui:

Timestamp com nanossegundos
Labels fixas e dinâmicas (ex: app, env, trace_id)
Prefixo do tipo de log ([LOG], [ERROR], [EVENT], etc)
Conteúdo serializado se necessário (objetos, erros)

11📄 Licença

Este projeto é licenciado sob a MIT License.

12🙌 Contribuindo

Fork este repositório
Crie uma branch com sua melhoria
Envie um Pull Request Toda ajuda é bem-vinda para tornar o logger JS ainda mais poderoso!

13 🧠 Integração com OpenTelemetry

Este logger se integra automaticamente com o OpenTelemetry, capturando os IDs de trace e span ativos no contexto atual.

Isso permite correlação perfeita entre logs e traces no Grafana Tempo, permitindo investigações completas ponta a ponta.

🔗 O que já está incluso:

trace_id e span_id são adicionados automaticamente como labels dinâmicas
Nenhuma configuração extra é necessária, desde que o app já use o OpenTelemetry

🧪 Exemplo com traces

import { context, trace } from "@opentelemetry/api";
import { interceptConsole } from "loki-console-logger-js";

// Inicialize o OpenTelemetry antes:
const tracer = trace.getTracer("minha-lib");

interceptConsole({
  url: "<https://loki.elvenobservability.com/loki/api/v1/push>",
  tenantId: "elven",
  appName: "meu-app",
  labels: { env: "prod" },
});

tracer.startActiveSpan("processarPedido", (span) => {
  console.log("Processando pedido");
  span.end();
});

📈 No Loki:

Cada log conterá automaticamente:

{trace_id="abcdef123", span_id="12345678", ...}

Você poderá fazer queries no Loki filtrando por trace_id e, com isso, visualizar os logs do mesmo trace mostrado no Grafana Tempo (ou trace view da Elven Platform).

14 💚 Feito com amor pela Elven Observability

Dúvidas ou sugestões? Fale com a gente!