@gobing-ai/ts-infra 0.2.8 → 0.3.0

package/src/telemetry/metrics.ts

@@ -3,28 +3,21 @@
  * All degrade to no-ops when telemetry is disabled.
  */
 import { type Counter, type Histogram, metrics } from '@opentelemetry/api';
-import type { MeterProvider } from '@opentelemetry/sdk-metrics';
 
 export type { Counter, Histogram } from '@opentelemetry/api';
 
-import type { TelemetryConfig } from './config';
-
-let meterProvider: MeterProvider | undefined;
 let metricsInitialized = false;
 
 export function isMetricsInitialized(): boolean {
     return metricsInitialized;
 }
 
-export function getMeterProvider(): MeterProvider {
-    return meterProvider ?? (metrics.getMeterProvider() as MeterProvider);
-}
-
 const METER_NAME = '@gobing-ai/ts-infra';
 const METER_VERSION = '0.1.0';
 
+/** Meter from the globally-registered provider (no-op when none registered). */
 function getMeter() {
-    return getMeterProvider().getMeter(METER_NAME, METER_VERSION);
+    return metrics.getMeter(METER_NAME, METER_VERSION);
 }
 
 // ── Instrument cache ────────────────────────────────────────────────
@@ -45,20 +38,6 @@ function getOrCreateHistogram(key: string, name: string, description: string, un
     return instruments[key] as Histogram;
 }
 
-// ── HTTP server ─────────────────────────────────────────────────────
-
-export function getHttpServerRequestTotal(): Counter {
-    return getOrCreateCounter('httpSrvReq', 'http.server.request.total', 'Total inbound HTTP requests', '{request}');
-}
-
-export function getHttpServerRequestDuration(): Histogram {
-    return getOrCreateHistogram('httpSrvDur', 'http.server.request.duration', 'Inbound HTTP request duration');
-}
-
-export function getHttpServerRequestErrors(): Counter {
-    return getOrCreateCounter('httpSrvErr', 'http.server.request.errors', 'Inbound HTTP 5xx errors', '{error}');
-}
-
 // ── HTTP client ─────────────────────────────────────────────────────
 
 export function getHttpClientRequestTotal(): Counter {
@@ -73,20 +52,6 @@ export function getHttpClientRequestErrors(): Counter {
     return getOrCreateCounter('httpCliErr', 'http.client.request.errors', 'Outbound HTTP errors', '{error}');
 }
 
-// ── DB ──────────────────────────────────────────────────────────────
-
-export function getDbOperationTotal(): Counter {
-    return getOrCreateCounter('dbOpTotal', 'db.client.operation.total', 'Total DB operations', '{operation}');
-}
-
-export function getDbOperationDuration(): Histogram {
-    return getOrCreateHistogram('dbOpDur', 'db.client.operation.duration', 'DB operation duration');
-}
-
-export function getDbOperationErrors(): Counter {
-    return getOrCreateCounter('dbOpErr', 'db.client.operation.errors', 'DB operation errors', '{error}');
-}
-
 // ── Event bus ───────────────────────────────────────────────────────
 
 export function getEventbusEmitsTotal(): Counter {
@@ -131,12 +96,18 @@ export function getSchedulerJobFailedTotal(): Counter {
 
 // ── Lifecycle ───────────────────────────────────────────────────────
 
-export function initMetrics(_config?: Partial<TelemetryConfig>): void {
+export function initMetrics(): void {
     if (metricsInitialized) return;
     metricsInitialized = true;
 }
 
 export function shutdownMetrics(): Promise<void> {
+    // The meter provider is owned by whoever registered it globally (the host
+    // app or `@gobing-ai/ts-infra/otel-node`). Here we only drop the instrument
+    // cache so post-shutdown getters rebuild against a fresh meter.
+    for (const key of Object.keys(instruments)) {
+        instruments[key] = undefined;
+    }
     metricsInitialized = false;
     return Promise.resolve();
 }

package/src/telemetry/otel-node.ts

@@ -0,0 +1,116 @@
+/**
+ * Opt-in Node OTLP wiring for `@gobing-ai/ts-infra`.
+ *
+ * The core telemetry surface (`initTelemetry`, `getTracer`, the metric getters)
+ * only *instruments* — it records spans and metrics against whatever OTel
+ * provider is registered globally, and degrades to no-ops when none is. This
+ * subpath is the convenience layer that actually *exports*: it builds Node
+ * tracer + meter providers wired to OTLP/HTTP and registers them globally, so
+ * the already-instrumented call sites start flowing without any core change.
+ *
+ * Import this only when you want turnkey export. It pulls the OTLP exporter
+ * packages (declared as optional peers); the main barrel never imports them, so
+ * BYO-collector consumers stay lean and avoid global-provider conflicts.
+ */
+import { metrics } from '@opentelemetry/api';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { MeterProvider, type MetricReader, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
+import { BatchSpanProcessor, NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
+
+/** Options for {@link initNodeTelemetry}. */
+export interface NodeTelemetryOptions {
+    /** Logical service name emitted on every span/metric (resource attribute). */
+    serviceName: string;
+    /** Optional service version (resource attribute). */
+    serviceVersion?: string;
+    /**
+     * OTLP/HTTP collector endpoint base, e.g. `http://localhost:4318`.
+     * Signal-specific paths (`/v1/traces`, `/v1/metrics`) are appended by the
+     * exporters. When omitted, the OTel SDK default (`http://localhost:4318`)
+     * applies, honouring the standard `OTEL_EXPORTER_OTLP_*` env vars.
+     */
+    endpoint?: string;
+    /** Extra headers sent on every OTLP request (e.g. an auth token). */
+    headers?: Record<string, string>;
+    /** Metric export interval in ms. Default: 60_000. */
+    metricExportIntervalMs?: number;
+    /** When false, skip metric export and wire traces only. Default: true. */
+    metrics?: boolean;
+}
+
+let traceProvider: NodeTracerProvider | undefined;
+let meterProvider: MeterProvider | undefined;
+
+/**
+ * Wire Node OTLP/HTTP export for traces and (by default) metrics, registering
+ * both providers globally. Idempotent: a second call is a no-op until
+ * {@link shutdownNodeTelemetry} runs.
+ *
+ * Call once at process startup, before the first span/metric is recorded.
+ */
+export function initNodeTelemetry(options: NodeTelemetryOptions): void {
+    if (traceProvider) return;
+
+    const { serviceName, serviceVersion, endpoint, headers, metricExportIntervalMs = 60_000 } = options;
+    const wireMetrics = options.metrics ?? true;
+
+    const resource = resourceFromAttributes({
+        [ATTR_SERVICE_NAME]: serviceName,
+        ...(serviceVersion ? { [ATTR_SERVICE_VERSION]: serviceVersion } : {}),
+    });
+
+    const traceExporter = new OTLPTraceExporter({
+        ...(endpoint ? { url: `${endpoint.replace(/\/$/, '')}/v1/traces` } : {}),
+        ...(headers ? { headers } : {}),
+    });
+
+    traceProvider = new NodeTracerProvider({
+        resource,
+        spanProcessors: [new BatchSpanProcessor(traceExporter)],
+    });
+    traceProvider.register();
+
+    if (wireMetrics) {
+        const metricExporter = new OTLPMetricExporter({
+            ...(endpoint ? { url: `${endpoint.replace(/\/$/, '')}/v1/metrics` } : {}),
+            ...(headers ? { headers } : {}),
+        });
+
+        const reader: MetricReader = new PeriodicExportingMetricReader({
+            exporter: metricExporter,
+            exportIntervalMillis: metricExportIntervalMs,
+        });
+
+        meterProvider = new MeterProvider({ resource, readers: [reader] });
+        metrics.setGlobalMeterProvider(meterProvider);
+    }
+}
+
+/**
+ * Flush and shut down the providers installed by {@link initNodeTelemetry}.
+ * Safe to call when nothing was initialised. Wire this to SIGTERM/SIGINT for a
+ * clean drain of buffered spans and metrics on shutdown.
+ */
+export async function shutdownNodeTelemetry(): Promise<void> {
+    const pending: Array<Promise<void>> = [];
+    if (meterProvider) {
+        pending.push(meterProvider.shutdown());
+        meterProvider = undefined;
+    }
+    if (traceProvider) {
+        pending.push(traceProvider.shutdown());
+        traceProvider = undefined;
+    }
+    metrics.disable();
+    await Promise.all(pending);
+}
+
+/** Test-only: reset module state without requiring exporter teardown to resolve. */
+export function _resetNodeTelemetry(): void {
+    meterProvider = undefined;
+    traceProvider = undefined;
+    metrics.disable();
+}

package/src/telemetry/sdk.ts

@@ -1,48 +1,44 @@
 /**
- * OpenTelemetry SDK initialisation and tracer provider management.
+ * Telemetry enablement + tracer access.
+ *
+ * The core only *instruments* against whatever tracer provider is registered
+ * globally — it never constructs or owns a provider. Provider + exporter wiring
+ * is the consumer's concern: either the host app registers its own OTel SDK, or
+ * it opts into `@gobing-ai/ts-infra/otel-node` for turnkey OTLP export. This
+ * keeps the main barrel free of any SDK runtime dependency.
  */
 import { type Tracer, trace } from '@opentelemetry/api';
-import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
 import type { TelemetryConfig } from './config';
 import { getTelemetryConfig } from './config';
 
-let tracerProvider: NodeTracerProvider | undefined;
+const TRACER_NAME = '@gobing-ai/ts-infra';
+const TRACER_VERSION = '0.1.0';
+
 let telemetryInitialized = false;
 let resolvedConfig: TelemetryConfig = getTelemetryConfig();
 
-const DEFAULT_TRACER = trace.getTracer('@gobing-ai/ts-infra', '0.1.0');
-
 export function getResolvedConfig(): TelemetryConfig {
     return resolvedConfig;
 }
 
+/**
+ * Resolve telemetry config and mark telemetry enabled. Does not register any
+ * provider — spans flow to the globally-registered provider (none ⇒ no-op).
+ */
 export function initTelemetry(config?: Partial<TelemetryConfig>): void {
     if (telemetryInitialized) return;
-
     resolvedConfig = { ...getTelemetryConfig(), ...config };
-
-    if (!resolvedConfig.enabled) {
-        telemetryInitialized = true;
-        return;
-    }
-
-    tracerProvider = new NodeTracerProvider();
-    tracerProvider.register();
     telemetryInitialized = true;
 }
 
-export async function shutdownTelemetry(): Promise<void> {
-    if (!tracerProvider) {
-        telemetryInitialized = false;
-        return;
-    }
-    await tracerProvider.shutdown();
-    tracerProvider = undefined;
+export function shutdownTelemetry(): Promise<void> {
     telemetryInitialized = false;
+    return Promise.resolve();
 }
 
+/** The infra tracer from the globally-registered provider (no-op when none). */
 export function getTracer(): Tracer {
-    return tracerProvider?.getTracer('@gobing-ai/ts-infra', '0.1.0') ?? DEFAULT_TRACER;
+    return trace.getTracer(TRACER_NAME, TRACER_VERSION);
 }
 
 export function isTelemetryEnabled(): boolean {
@@ -50,14 +46,6 @@ export function isTelemetryEnabled(): boolean {
 }
 
 export function _resetTelemetry(): void {
-    if (tracerProvider) {
-        try {
-            tracerProvider.shutdown();
-        } catch {
-            /* swallow */
-        }
-        tracerProvider = undefined;
-    }
     telemetryInitialized = false;
     resolvedConfig = getTelemetryConfig();
 }

package/dist/events/app-events.d.ts

@@ -1,7 +0,0 @@
-/**
- * Application event definitions — generic typed event map pattern.
- * Apps extend this with their own event types.
- */
-export type AppEvents = Record<string, (...args: never[]) => void>;
-export type AppInternalEvents = Record<string, (...args: never[]) => void>;
-//# sourceMappingURL=app-events.d.ts.map

package/dist/events/app-events.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"app-events.d.ts","sourceRoot":"","sources":["../../src/events/app-events.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,CAAC,CAAC;AAEnE,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,CAAC,CAAC"}

package/dist/events/app-events.js

@@ -1,4 +0,0 @@
-/**
- * Application event definitions — generic typed event map pattern.
- * Apps extend this with their own event types.
- */

package/dist/events/create-system-bus.d.ts

@@ -1,6 +0,0 @@
-import { EventBus } from '../event-bus/event-bus';
-/**
- * Factory that creates a configured system event bus.
- */
-export declare function createSystemBus(): EventBus<Record<string, (...args: never[]) => void>>;
-//# sourceMappingURL=create-system-bus.d.ts.map

package/dist/events/create-system-bus.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"create-system-bus.d.ts","sourceRoot":"","sources":["../../src/events/create-system-bus.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD;;GAEG;AACH,wBAAgB,eAAe,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,CAAC,CAAC,CAEtF"}

package/dist/events/create-system-bus.js

@@ -1,7 +0,0 @@
-import { EventBus } from '../event-bus/event-bus.js';
-/**
- * Factory that creates a configured system event bus.
- */
-export function createSystemBus() {
-    return new EventBus();
-}

package/dist/events/index.d.ts

@@ -1,3 +0,0 @@
-export type { AppEvents, AppInternalEvents } from './app-events';
-export { createSystemBus } from './create-system-bus';
-//# sourceMappingURL=index.d.ts.map

package/dist/events/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/events/index.js

@@ -1 +0,0 @@
-export { createSystemBus } from './create-system-bus.js';

package/src/events/app-events.ts

@@ -1,8 +0,0 @@
-/**
- * Application event definitions — generic typed event map pattern.
- * Apps extend this with their own event types.
- */
-
-export type AppEvents = Record<string, (...args: never[]) => void>;
-
-export type AppInternalEvents = Record<string, (...args: never[]) => void>;

package/src/events/create-system-bus.ts

@@ -1,8 +0,0 @@
-import { EventBus } from '../event-bus/event-bus';
-
-/**
- * Factory that creates a configured system event bus.
- */
-export function createSystemBus(): EventBus<Record<string, (...args: never[]) => void>> {
-    return new EventBus();
-}

package/src/events/index.ts

@@ -1,2 +0,0 @@
-export type { AppEvents, AppInternalEvents } from './app-events';
-export { createSystemBus } from './create-system-bus';