@gobing-ai/ts-infra 0.2.7 → 0.2.9

package/src/job-queue/db-job-queue.ts

@@ -0,0 +1,178 @@
+import type { QueueJobDao, QueueJobRecord, QueueStats } from '@gobing-ai/ts-db';
+import {
+    getQueueJobCompletedTotal,
+    getQueueJobEnqueuedTotal,
+    getQueueJobFailedTotal,
+    getQueueJobProcessingDuration,
+} from '../telemetry/metrics';
+import type { EnqueueOptions, Job, JobHandler, JobQueue, QueueConsumer, QueueConsumerConfig } from './types';
+
+/** DB-backed job queue implementation over `@gobing-ai/ts-db`'s `QueueJobDao`. */
+export class DBJobQueue<T = unknown> implements JobQueue<T> {
+    constructor(readonly dao: QueueJobDao) {}
+
+    async enqueue(type: string, payload: T, options?: EnqueueOptions): Promise<string> {
+        const id = await this.dao.enqueue(type, payload, options);
+        getQueueJobEnqueuedTotal().add(1, { type });
+        return id;
+    }
+
+    async enqueueBatch(jobs: Array<{ type: string; payload: T } & EnqueueOptions>): Promise<string[]> {
+        const ids = await this.dao.enqueueBatch(jobs);
+        getQueueJobEnqueuedTotal().add(jobs.length);
+        return ids;
+    }
+
+    async stats(): Promise<QueueStats> {
+        return this.dao.getStats();
+    }
+}
+
+/** DB-backed queue consumer with polling, retry, and visibility-timeout handling. */
+export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
+    private readonly handlers = new Map<string, JobHandler<T>>();
+    private readonly pollInterval: number;
+    private readonly batchSize: number;
+    private readonly maxConcurrency: number;
+    private readonly visibilityTimeout: number;
+    private readonly baseDelay: number;
+    private readonly maxDelay: number;
+    private readonly drainTimeoutMs: number;
+    private timer: ReturnType<typeof setTimeout> | null = null;
+    private running = false;
+    private inFlight = 0;
+
+    constructor(
+        private readonly dao: QueueJobDao,
+        config: QueueConsumerConfig = {},
+    ) {
+        this.pollInterval = config.pollInterval ?? 1_000;
+        this.batchSize = config.batchSize ?? 10;
+        this.maxConcurrency = config.maxConcurrency ?? this.batchSize;
+        this.visibilityTimeout = config.visibilityTimeout ?? 30_000;
+        this.baseDelay = config.baseDelay ?? 1_000;
+        this.maxDelay = config.maxDelay ?? 60_000;
+        this.drainTimeoutMs = config.drainTimeoutMs ?? 30_000;
+    }
+
+    register(type: string, handler: JobHandler<T>): void {
+        this.handlers.set(type, handler);
+    }
+
+    async start(): Promise<void> {
+        if (this.running) return;
+        this.running = true;
+        this.schedule(0);
+    }
+
+    async stop(): Promise<void> {
+        this.running = false;
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+
+        const deadline = Date.now() + this.drainTimeoutMs;
+        while (this.inFlight > 0 && Date.now() < deadline) {
+            await sleep(10);
+        }
+    }
+
+    async stats(): Promise<QueueStats> {
+        return this.dao.getStats();
+    }
+
+    /** Process one batch immediately. Useful for tests, schedulers, and manual drains. */
+    async processOnce(): Promise<number> {
+        await this.dao.resetStuckJobs(this.visibilityTimeout);
+        await this.dao.failExpiredJobs();
+
+        const jobs = await this.dao.claimReady(this.batchSize);
+        let processed = 0;
+
+        for (let index = 0; index < jobs.length; index += this.maxConcurrency) {
+            const batch = jobs.slice(index, index + this.maxConcurrency);
+            await Promise.all(
+                batch.map(async (job) => {
+                    this.inFlight += 1;
+                    try {
+                        await this.processJob(job);
+                        processed += 1;
+                    } finally {
+                        this.inFlight -= 1;
+                    }
+                }),
+            );
+        }
+
+        return processed;
+    }
+
+    private schedule(delay: number): void {
+        this.timer = setTimeout(() => {
+            void this.poll();
+        }, delay);
+    }
+
+    private async poll(): Promise<void> {
+        if (!this.running) return;
+        try {
+            await this.processOnce();
+        } finally {
+            if (this.running) this.schedule(this.pollInterval);
+        }
+    }
+
+    private async processJob(record: QueueJobRecord): Promise<void> {
+        const job = toJob<T>(record);
+        const handler = this.handlers.get(job.type);
+        if (handler === undefined) {
+            await this.failOrRetry(job, new Error(`No handler registered for job type "${job.type}"`));
+            return;
+        }
+
+        const startMs = performance.now();
+        try {
+            await handler(job);
+            await this.dao.markCompleted(job.id);
+            getQueueJobCompletedTotal().add(1, { type: job.type });
+            getQueueJobProcessingDuration().record(performance.now() - startMs, { type: job.type });
+        } catch (error) {
+            getQueueJobProcessingDuration().record(performance.now() - startMs, { type: job.type });
+            await this.failOrRetry(job, error);
+        }
+    }
+
+    private async failOrRetry(job: Job<T>, error: unknown): Promise<void> {
+        const attempts = job.attempts + 1;
+        const message = error instanceof Error ? error.message : String(error);
+        if (attempts >= job.maxRetries) {
+            await this.dao.markFailed(job.id, attempts, message);
+            getQueueJobFailedTotal().add(1, { type: job.type });
+            return;
+        }
+
+        const delay = Math.min(this.maxDelay, this.baseDelay * 2 ** Math.max(0, attempts - 1));
+        await this.dao.markForRetry(job.id, attempts, message, Date.now() + delay);
+    }
+}
+
+function toJob<T>(record: QueueJobRecord): Job<T> {
+    return {
+        id: record.id,
+        type: record.type,
+        payload: JSON.parse(record.payload) as T,
+        status: record.status as Job<T>['status'],
+        attempts: record.attempts,
+        maxRetries: record.maxRetries,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        nextRetryAt: record.nextRetryAt,
+        lastError: record.lastError,
+        processingAt: record.processingAt,
+    };
+}
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/job-queue/index.ts

@@ -1,3 +1,4 @@
+export { DBJobQueue, DBQueueConsumer } from './db-job-queue';
 export type {
     EnqueueOptions,
     Job,

package/src/job-queue/types.ts

@@ -1,10 +1,8 @@
 /**
  * Job queue types for async work processing with retry.
  *
- * **Types only** — the DB-backed `DbQueue` and `DbConsumer` implementations
- * that drive the job-queue subsystem live in `@spur/core`. These interfaces
- * are provided here so `EventBus` and other infra components can reference
- * the queue contract without a circular dependency on the DB layer.
+ * The concrete DB-backed implementations live beside these interfaces in
+ * `DBJobQueue` and `DBQueueConsumer`.
  */
 
 export interface Job<T = unknown> {
@@ -30,6 +28,7 @@ export interface EnqueueOptions {
 export interface JobQueue<T = unknown> {
     enqueue(type: string, payload: T, options?: EnqueueOptions): Promise<string>;
     enqueueBatch(jobs: Array<{ type: string; payload: T } & EnqueueOptions>): Promise<string[]>;
+    stats(): Promise<QueueStats>;
 }
 
 export type JobHandler<T = unknown> = (job: Job<T>) => Promise<void>;
@@ -49,7 +48,6 @@ export interface QueueConsumerConfig {
     baseDelay?: number;
     maxDelay?: number;
     drainTimeoutMs?: number;
-    maxPollBackoff?: number;
 }
 
 export interface QueueConsumer<T = unknown> {

package/src/logger.ts

@@ -30,14 +30,14 @@ class ConsoleLogger implements Logger {
 
     constructor(
         private readonly category: string,
-        private readonly minLevel: LogLevel = 'info',
         context: Record<string, unknown> = {},
     ) {
         this.context = { category, ...context };
     }
 
     private log(level: LogLevel, msg: string, data?: Record<string, unknown>): void {
-        if (LEVEL_ORDER[level] < LEVEL_ORDER[this.minLevel]) return;
+        // Read the level dynamically so re-initialization affects cached loggers too.
+        if (LEVEL_ORDER[level] < LEVEL_ORDER[globalLevel]) return;
         if (globalMuted) return;
 
         const entry = {
@@ -86,7 +86,7 @@ class ConsoleLogger implements Logger {
     }
 
     child(context: Record<string, unknown>): Logger {
-        return new ConsoleLogger(this.category, this.minLevel, { ...this.context, ...context });
+        return new ConsoleLogger(this.category, { ...this.context, ...context });
     }
 }
 
@@ -109,7 +109,7 @@ export function getLogger(category: string): Logger {
     const existing = loggers.get(category);
     if (existing) return existing;
 
-    const logger = new ConsoleLogger(category, globalLevel);
+    const logger = new ConsoleLogger(category);
     loggers.set(category, logger);
     return logger;
 }

package/src/scheduler/cloudflare.ts

@@ -2,6 +2,7 @@
  * Cloudflare Workers scheduler adapter using Cron Triggers.
  * Uses minimal local type declarations — no @cloudflare/workers-types dependency.
  */
+import { getSchedulerJobExecutedTotal, getSchedulerJobFailedTotal } from '../telemetry/metrics';
 import type { ScheduledAction, SchedulerAdapter } from './types';
 
 interface CfScheduledEvent {
@@ -39,7 +40,13 @@ export class CloudflareSchedulerAdapter implements SchedulerAdapter {
     handleScheduledEvent(event: CfScheduledEvent, ctx: CfEventContext): void {
         const action = this.entries.get(event.cron);
         if (action) {
-            ctx.waitUntil(action());
+            getSchedulerJobExecutedTotal().add(1, { cron: event.cron });
+            ctx.waitUntil(
+                action().catch((error: unknown) => {
+                    getSchedulerJobFailedTotal().add(1, { cron: event.cron });
+                    throw error;
+                }),
+            );
         }
     }
 }

package/src/scheduler/factory.ts

@@ -1,6 +1,7 @@
 /**
  * Scheduler factory — selects adapter based on runtime.
  */
+import { NoopSchedulerAdapter } from './noop';
 import type { ScheduledAction, SchedulerAdapter } from './types';
 
 let runtimeAdapter: SchedulerAdapter | undefined;
@@ -30,7 +31,7 @@ export function getSchedulerAdapter(): SchedulerAdapter | undefined {
 export function initScheduler(cronEntries?: Array<[string, ScheduledAction]>): SchedulerAdapter {
     // Default: create a noop adapter. Apps inject their own via setSchedulerAdapter.
     if (!runtimeAdapter) {
-        runtimeAdapter = createNoopScheduler();
+        runtimeAdapter = new NoopSchedulerAdapter();
     }
 
     if (cronEntries) {
@@ -41,17 +42,3 @@ export function initScheduler(cronEntries?: Array<[string, ScheduledAction]>): S
 
     return runtimeAdapter;
 }
-
-function createNoopScheduler(): SchedulerAdapter {
-    return {
-        register(): void {
-            /* noop */
-        },
-        start(): Promise<void> {
-            return Promise.resolve();
-        },
-        stop(): Promise<void> {
-            return Promise.resolve();
-        },
-    };
-}

package/src/scheduler/node.ts

@@ -2,6 +2,11 @@
  * Node.js scheduler adapter using a simple setInterval-based approach.
  * No external cron library dependency — cron expressions are parsed minimally.
  */
+import {
+    getSchedulerJobDuration,
+    getSchedulerJobExecutedTotal,
+    getSchedulerJobFailedTotal,
+} from '../telemetry/metrics';
 import type { ScheduledAction, SchedulerAdapter } from './types';
 
 /** Simple helper to parse cron-like interval strings into milliseconds. */
@@ -74,10 +79,15 @@ export class NodeSchedulerAdapter implements SchedulerAdapter {
     }
 
     private async _onScheduledTick(entry: ScheduledEntry): Promise<void> {
+        const startMs = performance.now();
+        getSchedulerJobExecutedTotal().add(1, { cron: entry.cron });
         try {
             await entry.action();
         } catch {
             // Swallow — scheduler errors should not crash the process
+            getSchedulerJobFailedTotal().add(1, { cron: entry.cron });
+        } finally {
+            getSchedulerJobDuration().record(performance.now() - startMs, { cron: entry.cron });
         }
     }
 }

package/src/telemetry/config.ts

@@ -9,10 +9,6 @@ export interface TelemetryConfig {
     serviceName: string;
     /** Deployment environment (development, staging, production). */
     environment: string;
-    /** OTLP exporter endpoint (e.g. `http://localhost:4318/v1/traces`). */
-    exporterEndpoint?: string | undefined;
-    /** Export protocol — only `http` is supported in v1. */
-    exporterProtocol: 'http';
     /**
      * Debug-only DB statement capture.
      *
@@ -32,7 +28,6 @@ export interface TelemetryConfigPartial {
     enabled?: boolean | undefined;
     serviceName?: string | undefined;
     environment?: string | undefined;
-    exporterEndpoint?: string | undefined;
     dbStatementDebug?: boolean | undefined;
     /** Deployment environment fallback (from app.env). */
     appEnv?: string | undefined;
@@ -42,7 +37,6 @@ const DEFAULTS = {
     enabled: true as const,
     serviceName: 'ts-libs' as const,
     environment: 'development' as const,
-    exporterProtocol: 'http' as const,
 };
 
 /**
@@ -56,8 +50,6 @@ export function getTelemetryConfig(configPartial: TelemetryConfigPartial = {}):
         enabled,
         serviceName,
         environment: configPartial.environment ?? configPartial.appEnv ?? DEFAULTS.environment,
-        exporterEndpoint: configPartial.exporterEndpoint,
-        exporterProtocol: DEFAULTS.exporterProtocol,
         dbStatementDebug: configPartial.dbStatementDebug ?? false,
     };
 }

package/src/telemetry/index.ts

@@ -2,17 +2,11 @@ export { getTelemetryConfig, type TelemetryConfig, type TelemetryConfigPartial }
 export { extractSqlOperation, sanitizeSql } from './db-sanitize';
 export {
     type Counter,
-    getDbOperationDuration,
-    getDbOperationErrors,
-    getDbOperationTotal,
     getEventbusEmitsTotal,
     getEventbusErrorsTotal,
     getHttpClientRequestDuration,
     getHttpClientRequestErrors,
     getHttpClientRequestTotal,
-    getHttpServerRequestDuration,
-    getHttpServerRequestErrors,
-    getHttpServerRequestTotal,
     getQueueJobCompletedTotal,
     getQueueJobEnqueuedTotal,
     getQueueJobFailedTotal,

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();
 }