@camino-tec/otel-sdk

SDK genérico de observabilidade OpenTelemetry para aplicações Node.js.
Configura traces (OTLP HTTP), métricas (OTLP gRPC) e logs (bridge pino → OTEL Logs API) com uma única chamada.

Instalação

npm install @camino-tec/otel-sdk
# ou
yarn add @camino-tec/otel-sdk

Uso básico

import { initializeObservability } from '@camino-tec/otel-sdk';

const sdk = initializeObservability({
  serviceName: 'meu-servico',
  serviceVersion: '1.0.0',
});

Logs: bridge pino → OpenTelemetry

A função createOtelLogStream() retorna um Writable stream do Node.js que recebe linhas JSON do pino e emite LogRecord via OpenTelemetry Logs API — sem precisar de loader hooks ou monkey-patching. Funciona em ESM e CJS.

Setup básico com pino

import pino from 'pino';
import { initializeObservability, createOtelLogStream } from '@camino-tec/otel-sdk';

const sdk = initializeObservability({ serviceName: 'meu-app' });
const log = pino({ level: 'debug' }, createOtelLogStream());

log.info('Aplicação iniciada');
log.error({ userId: 42 }, 'Falha ao processar requisição');

Setup com pino.multistream (pino-pretty + OTEL)

import pino from 'pino';
import { initializeObservability, createOtelLogStream } from '@camino-tec/otel-sdk';

const sdk = initializeObservability({ serviceName: 'meu-app' });

const log = pino(
  { level: 'debug' },
  pino.multistream([
    {
      level: 'info',
      stream: pino.transport({
        target: 'pino-pretty',
        options: { colorize: true },
      }),
    },
    { level: 'debug', stream: createOtelLogStream() },
  ]),
);

log.info('Visível no terminal E enviado ao collector');
log.debug({ requestId: 'abc-123' }, 'Só vai pro collector');

Shutdown (obrigatório para CLIs/scripts)

Para scripts ou CLIs que terminam, é necessário chamar sdk.shutdown() para garantir que todos os logs/traces/métricas pendentes sejam exportados antes do processo encerrar:

async function main() {
  const sdk = initializeObservability({ serviceName: 'meu-cli' });
  const log = pino({ level: 'info' }, createOtelLogStream());

  log.info('Processando...');
  // ... lógica do script ...

  await sdk.shutdown();
}

main();

Em servidores HTTP de longa duração, o flush acontece periodicamente e o shutdown() deve ser chamado no handler de SIGTERM/SIGINT.

Variáveis de ambiente

| Variável | Descrição | |---|---| | SERVICE_NAME | Nome do serviço (pode ser passado via serviceName nas options) | | SERVICE_VERSION | Versão do serviço (default: 1.0.0) | | OTEL_EXPORTER_OTLP_ENDPOINT | Endpoint base OTLP | | OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | Endpoint específico para traces | | OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | Endpoint específico para métricas |

Licença

UNLICENSED