@novahelm/logger

Structured logging for NovaHelm — Pino-based logger with Sentry error reporting, OpenTelemetry tracing, request ID propagation, and pretty-printing in development.

Quick Start

pnpm add @novahelm/logger

import { createLogger } from "@novahelm/logger";

const logger = createLogger({
  level: "info",
  serviceName: "web",
  sentryDsn: "https://...",        // optional — errors auto-reported
  otlpEndpoint: "http://...:4318", // optional — OpenTelemetry traces
  pretty: true,                    // auto-detected from NODE_ENV
});

logger.info("Server started");
logger.error(new Error("Something broke")); // also sent to Sentry

OpenTelemetry Tracing

Create spans and propagate trace context:

import { initOtel, withSpan, getTracer } from "@novahelm/logger";

// Initialize (done automatically if otlpEndpoint is set)
initOtel({ serviceName: "api", otlpEndpoint: "http://localhost:4318" });

// Wrap async work in a span
const result = await withSpan("process-order", async (span) => {
  span.setAttribute("orderId", order.id);
  return processOrder(order);
});

Trace Context Propagation

Thread trace IDs through async operations with AsyncLocalStorage:

import { withTraceId, getTraceId, getTraceContext } from "@novahelm/logger";

await withTraceId("req-abc-123", async () => {
  // Anywhere in this async tree:
  const traceId = getTraceId(); // "req-abc-123"
  const ctx = getTraceContext(); // { traceId, spanId, ... }
});

Request ID Middleware

Extract or generate request IDs from HTTP headers:

import { extractRequestId, requestIdHeaders } from "@novahelm/logger";

// In middleware
const requestId = extractRequestId(req.headers);
// Returns x-request-id header value or generates a new UUID

// Set response headers
const headers = requestIdHeaders(requestId);

API Reference

| Export | Description | |--------|-------------| | createLogger(config) | Create a Pino logger with Sentry + OTel integration | | withTraceId(id, fn) | Run async code with a trace ID in context | | getTraceId() | Get the current trace ID | | getTraceContext() | Get the full trace context | | initOtel(config) | Initialize OpenTelemetry SDK | | getTracer() | Get the OTel tracer instance | | withSpan(name, fn) | Wrap work in an OTel span | | isOtelInitialized() | Check if OTel is active | | extractRequestId(headers) | Extract or generate a request ID | | requestIdHeaders(id) | Build response headers with request ID |