Tooark OpenTelemetry Node.js

Pacote para inicializar e configurar OpenTelemetry automaticamente em aplicações Node.js (TypeScript/JavaScript). Facilita tracing, métricas e logs via OTLP com configuração por variáveis de ambiente.

O que o pacote faz

• Inicializa o SDK OpenTelemetry (tracing, métricas, logs) com configurações baseadas em variáveis de ambiente.
• Registra instrumentações automáticas via @opentelemetry/auto-instrumentations-node (HTTP, Express, drivers DB suportados, etc.).
• Cria LoggerProvider quando logs estão habilitados e exporta logs via OTLP.
• Exportadores suportados: OTLP via gRPC (padrão) ou HTTP/protobuf.
• Expõe getLogger(name) para produzir logs estruturados que correlacionam traceId/spanId.

Instalação

npm install @tooark/opentelemetry-nodejs

Uso rápido (zero-code)

1. Adicione o preload no package.json para garantir que o OpenTelemetry seja inicializado antes do seu código (se usar variáveis de ambiente com dotenv, carregue-o primeiro)

{
  "scripts": {
    "start": "node -r dotenv/config -r @tooark/opentelemetry-nodejs app.js"
  }
}

2. Exemplo mínimo de .env (valores sugeridos)

SERVICE_NAME=example-service
SERVICE_VERSION=1.1.0
SERVICE_NAMESPACE=default
DEPLOYMENT_ENVIRONMENT=development
OTEL_COLLECTOR_ENDPOINT=http://localhost:4317

3. Execute sua aplicação

npm start

Observação: o pacote chama startInstrumentation() automaticamente quando importado. Se preferir controle programático, não pré-carregue o pacote e inicialize manualmente no seu bootstrap (ou modifique o código fonte para expor APIs de inicialização).

Variáveis de ambiente (completas)

As opções podem ser definidas via .env ou variáveis de ambiente do ambiente de execução.

• SERVICE_NAME: Nome do serviço. Default: unknown-service.

• SERVICE_VERSION: Versão do serviço. Default: 0.0.0.

• SERVICE_NAMESPACE: Namespace do serviço. Default: default.

• SERVICE_INSTANCE_ID: ID da instância do serviço. Default: hostname do host.

• DEPLOYMENT_ENVIRONMENT: Ambiente do deploy (production/staging/etc). Default: unknown_environment.

• OTEL_RESOURCE_PROVIDER: Nome do provedor (atributo provider.name). Default: unknown_provider.

• OTEL_RESOURCE_CLUSTER_NAME: Nome do cluster (atributo provider.cluster.name). Default: unknown_cluster.

• OTLP_ENDPOINT: Endpoint base para OTLP (ex: http://collector:4317).

• OTEL_COLLECTOR_ENDPOINT: Fallback para OTLP_ENDPOINT quando não informado (padrão internal). Default: http://localhost:4317.

• OTLP_DEFAULT_PROTOCOL: grpc ou http/protobuf. Default: grpc.

• OTLP_ENABLED: Habilita exportação OTLP. Default: true.

• OTLP_PROCESSOR_TYPE: batch ou simple. Default: batch.

• OTLP_HEADERS: Cabeçalhos adicionais para o exportador OTLP (ex: api-key=xxx,env=prod).

• OTLP_SERVERLESS_OPTIMIZED: Otimização para ambientes serverless. Default: false.

• OTLP_MAX_QUEUE_SIZE: 2048 (fila do batch exporter).

• OTLP_SCHEDULED_DELAY_MILLISECONDS: 5000 (atraso programado do batch).

• OTLP_EXPORTER_TIMEOUT_MILLISECONDS: 30000 (timeout de exportação).

• OTLP_MAX_EXPORT_BATCH_SIZE: 512 (tamanho máximo do lote).

• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: Override para endpoint de traces.

• OTEL_EXPORTER_OTLP_METRICS_ENDPOINT: Override para endpoint de métricas.

• OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: Override para endpoint de logs.

• OTEL_API_VERSION: Força o valor de telemetry.sdk.version (caso não seja possível resolvê-lo automaticamente).

-- Logs

• LOG_ENABLED: Habilita logs do OpenTelemetry (padrão: true).
• LOG_INCLUDE_FORMATTED_MESSAGE: Inclui mensagem formatada. Default: true.
• LOG_INCLUDE_SCOPES: Inclui scopes/exceções. Default: true.
• LOG_PARSE_STATE_VALUES: Tenta parsear valores de estado. Default: true.

-- Métricas

• METRICS_ENABLED: Habilita métricas. Default: true.
• RUNTIME_METRICS_ENABLED: Habilita métricas de runtime (CPU, memória). Default: true.
• METER_NAME: Nome do meter principal. Default: AppMetric.
• ADDITIONAL_METERS: Lista CSV de meters adicionais.

-- Tracing

• TRACING_ENABLED: Habilita tracing. Default: true.
• TRACING_SAMPLING_RATE: Taxa de amostragem (0..1). Default: 1.
• IGNORE_SPECIFIC_PATH: CSV de prefixos/rotas a ignorar.
• IGNORE_PATH: CSV de rotas padrão a ignorar (/health, /metrics, etc.).
• APP_ACTIVITY_SOURCE: Fonte de atividade (default AppActivitySource).
• ADDITIONAL_SOURCES: CSV de fontes adicionais.

-- Dados sensíveis

• HIDE_QUERY_PARAMETERS: Remove query string das URLs. Default: true.
• HIDE_HEADERS: Oculta valores de headers nas spans/atributos. Default: true.
• SENSITIVE_REQUEST_HEADERS: CSV de headers considerados sensíveis (padrão inclui authorization, cookie, x-api-key, etc.).

Essas variáveis cobrem a maioria das configurações internas do pacote. Para valores não listados aqui, verifique src/Options/optionsClasses.ts.

Exemplos de uso

• Usar o logger estruturado do pacote:

const { getLogger } = require('@tooark/opentelemetry-nodejs');
const logger = getLogger('my-service');

logger.info('Application started');
logger.error('Something went wrong', { code: 123 });

• Encaminhar console para o logger (snippet opcional — cole antes do seu app rodar):

const { getLogger } = require('@tooark/opentelemetry-nodejs');
const consoleOtel = getLogger('console');

['log','info','warn','error','debug'].forEach((level) => {
  const orig = console[level].bind(console);

  console[level] = (...args) => {
    try { consoleOtel[level === 'log' ? 'info' : level](args.map(a => (typeof a === 'string' ? a : JSON.stringify(a))).join(' ')); } catch {}
    orig(...args);
  };
});

// Interceptar stdout (ex.: ferramentas que apenas escrevem em stdout)
const origStdoutWrite = process.stdout.write.bind(process.stdout);
process.stdout.write = (chunk, encoding, cb) => {
  try { consoleOtel.info(typeof chunk === 'string' ? chunk : chunk.toString(encoding)); } catch {}
  return origStdoutWrite(chunk, encoding, cb);
};

• Integrar pino escrevendo no logger do pacote:

const pino = require('pino');
const { getLogger } = require('@tooark/opentelemetry-nodejs');
const otelLogger = getLogger('pino');
const pinoStream = { write: (msg) => otelLogger.info(msg.trim()) };
const logger = pino({}, pinoStream);

logger.info('hello from pino');

Boas práticas & dicas

• Carregue dotenv/config antes do pacote quando usar .env para garantir leitura correta das variáveis.
• Se usar autenticação no Collector, configure OTLP_HEADERS com key=value (ex.: api-key=XXXXX).
• gRPC (porta 4317) é o modo padrão e recomendado para desempenho; use OTLP_DEFAULT_PROTOCOL=http/protobuf se precisar HTTP (porta 4318).
• Preferir getLogger() para logs estruturados (permite correlação com traces via traceId/spanId).
• Em ambientes serverless, considere OTLP_SERVERLESS_OPTIMIZED=true para reduzir overhead de exportação.

Depuração

• O pacote escreve mensagens de inicialização e erros no console (ex.: [otel_collector] Logger provider initialized).
• Se não aparecerem dados no collector, verifique: conectividade com OTEL_COLLECTOR_ENDPOINT, OTLP_ENABLED, LOG_ENABLED/METRICS_ENABLED/TRACING_ENABLED, e se há autenticação necessária via OTLP_HEADERS.

Releases e contribuições

• Histórico de releases: veja a pasta notes/.
• Bugs e solicitações: abra issues em https://github.com/Tooark/tooark-observability-nodejs