@gobing-ai/ts-infra 0.1.0

package/src/telemetry/metrics.ts

@@ -0,0 +1,150 @@
+/**
+ * OpenTelemetry metrics — lazy-initialized instruments.
+ * 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';
+
+function getMeter() {
+    return getMeterProvider().getMeter(METER_NAME, METER_VERSION);
+}
+
+// ── Instrument cache ────────────────────────────────────────────────
+
+const instruments: Record<string, Counter | Histogram | undefined> = {};
+
+function getOrCreateCounter(key: string, name: string, description: string, unit = '{operation}'): Counter {
+    if (!instruments[key]) {
+        instruments[key] = getMeter().createCounter(name, { description, unit });
+    }
+    return instruments[key] as Counter;
+}
+
+function getOrCreateHistogram(key: string, name: string, description: string, unit = 'ms'): Histogram {
+    if (!instruments[key]) {
+        instruments[key] = getMeter().createHistogram(name, { description, unit });
+    }
+    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 {
+    return getOrCreateCounter('httpCliReq', 'http.client.request.total', 'Total outbound HTTP requests', '{request}');
+}
+
+export function getHttpClientRequestDuration(): Histogram {
+    return getOrCreateHistogram('httpCliDur', 'http.client.request.duration', 'Outbound HTTP request duration');
+}
+
+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 {
+    return getOrCreateCounter('ebEmit', 'eventbus.emits.total', 'Total event bus emits', '{emit}');
+}
+
+export function getEventbusErrorsTotal(): Counter {
+    return getOrCreateCounter('ebErr', 'eventbus.errors.total', 'Event bus errors', '{error}');
+}
+
+// ── Queue ───────────────────────────────────────────────────────────
+
+export function getQueueJobEnqueuedTotal(): Counter {
+    return getOrCreateCounter('qEnq', 'queue.jobs.enqueued', 'Total jobs enqueued', '{job}');
+}
+
+export function getQueueJobCompletedTotal(): Counter {
+    return getOrCreateCounter('qComp', 'queue.jobs.completed', 'Total jobs completed', '{job}');
+}
+
+export function getQueueJobFailedTotal(): Counter {
+    return getOrCreateCounter('qFail', 'queue.jobs.failed', 'Total jobs failed', '{job}');
+}
+
+export function getQueueJobProcessingDuration(): Histogram {
+    return getOrCreateHistogram('qProcDur', 'queue.jobs.processing_duration', 'Job processing duration');
+}
+
+// ── Scheduler ───────────────────────────────────────────────────────
+
+export function getSchedulerJobExecutedTotal(): Counter {
+    return getOrCreateCounter('schedExec', 'scheduler.jobs.executed', 'Total scheduled job executions', '{execution}');
+}
+
+export function getSchedulerJobDuration(): Histogram {
+    return getOrCreateHistogram('schedDur', 'scheduler.jobs.duration', 'Scheduled job duration');
+}
+
+export function getSchedulerJobFailedTotal(): Counter {
+    return getOrCreateCounter('schedFail', 'scheduler.jobs.failed', 'Failed scheduled jobs', '{failure}');
+}
+
+// ── Lifecycle ───────────────────────────────────────────────────────
+
+export function initMetrics(_config?: Partial<TelemetryConfig>): void {
+    if (metricsInitialized) return;
+    metricsInitialized = true;
+}
+
+export function shutdownMetrics(): Promise<void> {
+    metricsInitialized = false;
+    return Promise.resolve();
+}
+
+export function _resetMetrics(): void {
+    for (const key of Object.keys(instruments)) {
+        instruments[key] = undefined;
+    }
+    metricsInitialized = false;
+    metrics.disable();
+}

package/src/telemetry/sdk.ts

@@ -0,0 +1,65 @@
+/**
+ * OpenTelemetry SDK initialisation and tracer provider management.
+ */
+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;
+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;
+}
+
+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;
+    telemetryInitialized = false;
+}
+
+export function getTracer(): Tracer {
+    return tracerProvider?.getTracer('@gobing-ai/ts-infra', '0.1.0') ?? DEFAULT_TRACER;
+}
+
+export function isTelemetryEnabled(): boolean {
+    return telemetryInitialized && resolvedConfig.enabled;
+}
+
+export function _resetTelemetry(): void {
+    if (tracerProvider) {
+        try {
+            tracerProvider.shutdown();
+        } catch {
+            /* swallow */
+        }
+        tracerProvider = undefined;
+    }
+    telemetryInitialized = false;
+    resolvedConfig = getTelemetryConfig();
+}
+
+export { context, propagation, trace } from '@opentelemetry/api';

package/src/telemetry/tracing.ts

@@ -0,0 +1,64 @@
+/**
+ * High-level tracing helpers for application code.
+ */
+
+import { context, type Span, type SpanOptions, type Tracer, trace } from '@opentelemetry/api';
+import { getTracer } from './sdk';
+
+export async function traceAsync<T>(
+    name: string,
+    fn: (span: Span) => Promise<T>,
+    options?: SpanOptions,
+    tracer?: Tracer,
+): Promise<T> {
+    const resolvedTracer = tracer ?? getTracer();
+    return resolvedTracer.startActiveSpan(name, options ?? {}, async (span) => {
+        try {
+            return await fn(span);
+        } catch (err) {
+            span.setStatus({ code: 2, message: err instanceof Error ? err.message : String(err) });
+            throw err;
+        } finally {
+            span.end();
+        }
+    });
+}
+
+export function traceSync<T>(name: string, fn: (span: Span) => T, options?: SpanOptions, tracer?: Tracer): T {
+    const resolvedTracer = tracer ?? getTracer();
+    return resolvedTracer.startActiveSpan(name, options ?? {}, (span) => {
+        try {
+            return fn(span);
+        } catch (err) {
+            span.setStatus({ code: 2, message: err instanceof Error ? err.message : String(err) });
+            throw err;
+        } finally {
+            span.end();
+        }
+    });
+}
+
+export function addSpanAttributes(attributes: Record<string, string | number | boolean>): void {
+    const span = trace.getActiveSpan();
+    if (span?.isRecording()) {
+        span.setAttributes(attributes);
+    }
+}
+
+export function addSpanEvent(name: string, attributes?: Record<string, string | number | boolean>): void {
+    const span = trace.getActiveSpan();
+    if (span?.isRecording()) {
+        span.addEvent(name, attributes);
+    }
+}
+
+export function getActiveSpan(): Span | undefined {
+    return trace.getActiveSpan() ?? undefined;
+}
+
+export function withSpan<T>(span: Span, fn: () => T): T {
+    return context.with(trace.setSpan(context.active(), span), fn);
+}
+
+export type { Span, SpanOptions, Tracer } from '@opentelemetry/api';
+export { context, propagation, trace } from './sdk';