@questpie/observability 3.17.0

package/dist/index.d.mts

@@ -0,0 +1,72 @@
+import { Attributes } from "@opentelemetry/api";
+import { LogRecordProcessor } from "@opentelemetry/sdk-logs";
+import { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { ObservabilityAdapter } from "questpie/observability";
+
+//#region src/otel-adapter.d.ts
+
+interface OtelObservabilityOptions {
+  /** `service.name`. Required — an unnamed service is unusable in any backend. */
+  serviceName: string;
+  serviceVersion?: string;
+  /** Becomes `deployment.environment.name`. */
+  environment?: string;
+  /**
+   * OTLP/HTTP base endpoint, e.g. `http://localhost:4318`. Omit to skip the
+   * OTLP exporter entirely — useful with `console: true` in development.
+   */
+  otlpEndpoint?: string;
+  otlpHeaders?: Record<string, string>;
+  /**
+   * Head sampling ratio, 0..1. Wrapped in a parent-based sampler, so a
+   * sampled upstream request stays sampled here regardless of the ratio.
+   * Omit for always-on.
+   */
+  samplingRatio?: number;
+  /** Also print spans to stdout. Development only — it is very noisy. */
+  console?: boolean;
+  /** Metric export interval. Default 60s, matching the OTLP default. */
+  metricIntervalMs?: number;
+  /** Extra resource attributes, merged last so they can override the above. */
+  resourceAttributes?: Attributes;
+  /**
+   * Additional span processors, appended after the OTLP and console ones.
+   *
+   * `BasicTracerProvider` takes its processors at construction and has no
+   * `addSpanProcessor`, so without this there is no way to attach a different
+   * exporter (Jaeger, Zipkin, a custom enricher) or to capture spans in memory
+   * for a test — which is how the span-tree assertions in this package's
+   * `otel-tree.test.ts` work.
+   */
+  spanProcessors?: SpanProcessor[];
+  /**
+   * Additional log-record processors, appended after the OTLP one. Same
+   * reasoning as `spanProcessors`: `LoggerProvider` takes its processors at
+   * construction, so without this there is no way to capture records in a test
+   * or send them anywhere else.
+   */
+  logRecordProcessors?: LogRecordProcessor[];
+}
+/**
+ * Build the OTel-backed adapter.
+ *
+ * ```ts
+ * import { otelObservability } from "@questpie/observability";
+ *
+ * export default runtimeConfig({
+ *   observability: {
+ *     adapter: otelObservability({
+ *       serviceName: "my-app",
+ *       otlpEndpoint: "http://localhost:4318",
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * The providers are created eagerly — `runtimeConfig` is evaluated at startup,
+ * which is early enough, and it means the first request is already traced
+ * rather than racing an async init.
+ */
+declare function otelObservability(options: OtelObservabilityOptions): ObservabilityAdapter;
+//#endregion
+export { type OtelObservabilityOptions, otelObservability };

package/dist/index.mjs

@@ -0,0 +1,204 @@
+import { SpanStatusCode, context, isSpanContextValid, metrics, propagation, trace } from "@opentelemetry/api";
+import { SeverityNumber, logs } from "@opentelemetry/api-logs";
+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { BatchLogRecordProcessor, LoggerProvider } from "@opentelemetry/sdk-logs";
+import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { AlwaysOnSampler, BasicTracerProvider, BatchSpanProcessor, ConsoleSpanExporter, ParentBasedSampler, SimpleSpanProcessor, TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
+
+//#region src/otel-adapter.ts
+/**
+* OpenTelemetry adapter for QUESTPIE.
+*
+* Composes the SDK by hand rather than using `@opentelemetry/sdk-node` or
+* `auto-instrumentations-node`. That is deliberate and was validated on Bun
+* 1.3.14: a manually composed provider initialises and exports under plain
+* `bun run` with no `--require` flag, no preload, and no monkey-patching of
+* built-ins — which is what auto-instrumentation relies on and what tends to be
+* fragile outside Node.
+*
+* Everything here implements the framework-side interfaces from
+* `questpie/observability`. The framework itself has no OpenTelemetry
+* dependency; this package is the only place OTel appears.
+*/
+/** OTel severity numbers for the four levels the framework logger exposes. */
+const SEVERITY = {
+	debug: SeverityNumber.DEBUG,
+	info: SeverityNumber.INFO,
+	warn: SeverityNumber.WARN,
+	error: SeverityNumber.ERROR
+};
+const SPAN_KINDS = {
+	internal: 0,
+	server: 1,
+	client: 2,
+	producer: 3,
+	consumer: 4
+};
+/** Drops undefined values — OTel rejects them, the framework type allows them. */
+function toOtelAttributes(attributes) {
+	if (!attributes) return {};
+	const out = {};
+	for (const [key, value] of Object.entries(attributes)) if (value !== void 0) out[key] = value;
+	return out;
+}
+function wrapSpan(span) {
+	return {
+		setAttribute(key, value) {
+			span.setAttribute(key, value);
+		},
+		setAttributes(attributes) {
+			span.setAttributes(toOtelAttributes(attributes));
+		},
+		recordError(error) {
+			const err = error instanceof Error ? error : new Error(String(error));
+			span.recordException(err);
+			span.setStatus({
+				code: SpanStatusCode.ERROR,
+				message: err.message
+			});
+		},
+		addEvent(name, attributes) {
+			span.addEvent(name, toOtelAttributes(attributes));
+		},
+		end() {
+			span.end();
+		}
+	};
+}
+function wrapTracer(tracer) {
+	return { startActiveSpan(name, options, fn) {
+		const spanOptions = {
+			kind: options.kind ? SPAN_KINDS[options.kind] : void 0,
+			attributes: toOtelAttributes(options.attributes)
+		};
+		const run = () => tracer.startActiveSpan(name, spanOptions, (span) => fn(wrapSpan(span)));
+		if (!options.carrier) return run();
+		return context.with(propagation.extract(context.active(), options.carrier), run);
+	} };
+}
+function wrapMeter(meter) {
+	return {
+		createCounter(name, options) {
+			const counter = meter.createCounter(name, options);
+			return { add(value, attributes) {
+				counter.add(value, toOtelAttributes(attributes));
+			} };
+		},
+		createHistogram(name, options) {
+			const histogram = meter.createHistogram(name, options);
+			return { record(value, attributes) {
+				histogram.record(value, toOtelAttributes(attributes));
+			} };
+		}
+	};
+}
+function buildSampler(ratio) {
+	if (ratio === void 0) return new AlwaysOnSampler();
+	return new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(ratio) });
+}
+/**
+* Build the OTel-backed adapter.
+*
+* ```ts
+* import { otelObservability } from "@questpie/observability";
+*
+* export default runtimeConfig({
+*   observability: {
+*     adapter: otelObservability({
+*       serviceName: "my-app",
+*       otlpEndpoint: "http://localhost:4318",
+*     }),
+*   },
+* });
+* ```
+*
+* The providers are created eagerly — `runtimeConfig` is evaluated at startup,
+* which is early enough, and it means the first request is already traced
+* rather than racing an async init.
+*/
+function otelObservability(options) {
+	const resource = resourceFromAttributes({
+		[ATTR_SERVICE_NAME]: options.serviceName,
+		...options.serviceVersion ? { [ATTR_SERVICE_VERSION]: options.serviceVersion } : {},
+		...options.environment ? { "deployment.environment.name": options.environment } : {},
+		...options.resourceAttributes
+	});
+	const spanProcessors = [];
+	if (options.otlpEndpoint) spanProcessors.push(new BatchSpanProcessor(new OTLPTraceExporter({
+		url: `${options.otlpEndpoint.replace(/\/$/, "")}/v1/traces`,
+		headers: options.otlpHeaders
+	})));
+	if (options.console) spanProcessors.push(new SimpleSpanProcessor(new ConsoleSpanExporter()));
+	if (options.spanProcessors) spanProcessors.push(...options.spanProcessors);
+	const tracerProvider = new BasicTracerProvider({
+		resource,
+		sampler: buildSampler(options.samplingRatio),
+		spanProcessors
+	});
+	const contextManager = new AsyncLocalStorageContextManager();
+	contextManager.enable();
+	context.setGlobalContextManager(contextManager);
+	propagation.setGlobalPropagator(new W3CTraceContextPropagator());
+	trace.setGlobalTracerProvider(tracerProvider);
+	const meterProvider = new MeterProvider({
+		resource,
+		readers: options.otlpEndpoint ? [new PeriodicExportingMetricReader({
+			exporter: new OTLPMetricExporter({
+				url: `${options.otlpEndpoint.replace(/\/$/, "")}/v1/metrics`,
+				headers: options.otlpHeaders
+			}),
+			exportIntervalMillis: options.metricIntervalMs ?? 6e4
+		})] : []
+	});
+	metrics.setGlobalMeterProvider(meterProvider);
+	const logRecordProcessors = [];
+	if (options.otlpEndpoint) logRecordProcessors.push(new BatchLogRecordProcessor({ exporter: new OTLPLogExporter({
+		url: `${options.otlpEndpoint.replace(/\/$/, "")}/v1/logs`,
+		headers: options.otlpHeaders
+	}) }));
+	if (options.logRecordProcessors) logRecordProcessors.push(...options.logRecordProcessors);
+	const loggerProvider = new LoggerProvider({
+		resource,
+		processors: logRecordProcessors
+	});
+	logs.setGlobalLoggerProvider(loggerProvider);
+	const otelLogger = loggerProvider.getLogger("questpie");
+	return {
+		tracer(name) {
+			return wrapTracer(tracerProvider.getTracer(name));
+		},
+		activeSpanContext() {
+			const active = trace.getActiveSpan()?.spanContext();
+			if (!active || !isSpanContextValid(active)) return void 0;
+			return {
+				traceId: active.traceId,
+				spanId: active.spanId
+			};
+		},
+		meter(name) {
+			return wrapMeter(meterProvider.getMeter(name));
+		},
+		emitLog(record) {
+			otelLogger.emit({
+				severityNumber: SEVERITY[record.level] ?? SeverityNumber.INFO,
+				severityText: record.level.toUpperCase(),
+				body: record.message,
+				attributes: toOtelAttributes(record.attributes)
+			});
+		},
+		async shutdown() {
+			await tracerProvider.shutdown();
+			await meterProvider.shutdown();
+			await loggerProvider.shutdown();
+		}
+	};
+}
+
+//#endregion
+export { otelObservability };

package/package.json

@@ -0,0 +1,71 @@
+{
+	"name": "@questpie/observability",
+	"version": "3.17.0",
+	"description": "OpenTelemetry adapter for QUESTPIE — traces and metrics via OTLP",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/questpie/questpie.git",
+		"directory": "packages/observability"
+	},
+	"files": [
+		"dist"
+	],
+	"type": "module",
+	"sideEffects": false,
+	"main": "./dist/index.mjs",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.mts",
+	"exports": {
+		".": {
+			"types": "./src/exports/index.ts",
+			"default": "./src/exports/index.ts"
+		},
+		"./package.json": {
+			"types": "./package.json",
+			"default": "./package.json"
+		}
+	},
+	"publishConfig": {
+		"access": "public",
+		"exports": {
+			".": {
+				"types": "./dist/index.d.mts",
+				"default": "./dist/index.mjs"
+			},
+			"./package.json": {
+				"types": "./package.json",
+				"default": "./package.json"
+			}
+		}
+	},
+	"scripts": {
+		"build": "tsdown",
+		"check-types": "tsc --noEmit",
+		"test": "bun test --timeout=60000 test/"
+	},
+	"dependencies": {
+		"@opentelemetry/api": "^1.9.0",
+		"@opentelemetry/api-logs": "^0.221.0",
+		"@opentelemetry/context-async-hooks": "^2.2.0",
+		"@opentelemetry/core": "^2.2.0",
+		"@opentelemetry/exporter-logs-otlp-http": "^0.221.0",
+		"@opentelemetry/exporter-metrics-otlp-http": "^0.221.0",
+		"@opentelemetry/exporter-trace-otlp-http": "^0.221.0",
+		"@opentelemetry/resources": "^2.2.0",
+		"@opentelemetry/sdk-logs": "^0.221.0",
+		"@opentelemetry/sdk-metrics": "^2.2.0",
+		"@opentelemetry/sdk-trace-base": "^2.2.0",
+		"@opentelemetry/semantic-conventions": "^1.43.0"
+	},
+	"devDependencies": {
+		"@electric-sql/pglite": "^0.3.14",
+		"bun-types": "latest",
+		"drizzle-kit": "1.0.0-beta.6-4414a19",
+		"drizzle-orm": "1.0.0-beta.6-4414a19",
+		"tsdown": "^0.18.3"
+	},
+	"peerDependencies": {
+		"questpie": "workspace:^"
+	}
+}