feat: Initial tracing setup (peer deps + utils)

Author: elliott-with-the-longest-name-on-github

packages/kit/package.json

@@ -33,6 +33,7 @@
 		"vitefu": "^1.0.6"
 	},
 	"devDependencies": {
+		"@opentelemetry/api": "^1.0.0",
 		"@playwright/test": "catalog:",
 		"@sveltejs/vite-plugin-svelte": "^5.0.1",
 		"@types/connect": "^3.4.38",
@@ -47,10 +48,16 @@
 		"vitest": "catalog:"
 	},
 	"peerDependencies": {
+		"@opentelemetry/api": "^1.0.0",
 		"@sveltejs/vite-plugin-svelte": "^3.0.0 || ^4.0.0-next.1 || ^5.0.0",
 		"svelte": "^4.0.0 || ^5.0.0-next.0",
 		"vite": "^5.0.3 || ^6.0.0"
 	},
+	"peerDependenciesMeta": {
+		"@opentelemetry/api": {
+			"optional": true
+		}
+	},
 	"bin": {
 		"svelte-kit": "svelte-kit.js"
 	},

packages/kit/src/runtime/server/telemetry/get-tracer.js

@@ -0,0 +1,21 @@
+/** @import { Tracer } from '@opentelemetry/api' */
+import { trace } from '@opentelemetry/api';
+import { noop_tracer } from './noop-tracer.js';
+
+/**
+ * @param {Object} [options={}] - Configuration options
+ * @param {boolean} [options.is_enabled=false] - Whether tracing is enabled
+ * @param {Tracer} [options.tracer] - Custom tracer instance
+ * @returns {Tracer} The tracer instance
+ */
+export function get_tracer({ is_enabled = false, tracer } = {}) {
+	if (!is_enabled) {
+		return noop_tracer;
+	}
+
+	if (tracer) {
+		return tracer;
+	}
+
+	return trace.getTracer('sveltekit');
+}

packages/kit/src/runtime/server/telemetry/noop-tracer.js

@@ -0,0 +1,75 @@
+/** @import { Tracer, Span, SpanContext } from '@opentelemetry/api' */
+
+/**
+ * Tracer implementation that does nothing (null object).
+ * @type {Tracer}
+ */
+export const noop_tracer = {
+	/**
+	 * @returns {Span}
+	 */
+	startSpan() {
+		return noop_span;
+	},
+
+	/**
+	 * @param {unknown} _name
+	 * @param {unknown} arg_1
+	 * @param {unknown} [arg_2]
+	 * @param {Function} [arg_3]
+	 * @returns {unknown}
+	 */
+	startActiveSpan(_name, arg_1, arg_2, arg_3) {
+		if (typeof arg_1 === 'function') {
+			return arg_1(noop_span);
+		}
+		if (typeof arg_2 === 'function') {
+			return arg_2(noop_span);
+		}
+		if (typeof arg_3 === 'function') {
+			return arg_3(noop_span);
+		}
+	}
+};
+
+/**
+ * @type {Span}
+ */
+const noop_span = {
+	spanContext() {
+		return noop_span_context;
+	},
+	setAttribute() {
+		return this;
+	},
+	setAttributes() {
+		return this;
+	},
+	addEvent() {
+		return this;
+	},
+	setStatus() {
+		return this;
+	},
+	updateName() {
+		return this;
+	},
+	end() {
+		return this;
+	},
+	isRecording() {
+		return false;
+	},
+	recordException() {
+		return this;
+	}
+};
+
+/**
+ * @type {SpanContext}
+ */
+const noop_span_context = {
+	traceId: '',
+	spanId: '',
+	traceFlags: 0
+};

packages/kit/src/runtime/server/telemetry/record-span.js

@@ -0,0 +1,65 @@
+/** @import { SpanAttributes, Span, Tracer } from '@opentelemetry/api' */
+import { SpanStatusCode } from '@opentelemetry/api';
+import { HttpError, Redirect } from '../../control.js';
+
+/**
+ * @template T
+ * @param {Object} options
+ * @param {string} options.name
+ * @param {Tracer} options.tracer
+ * @param {SpanAttributes} options.attributes
+ * @param {function(Span): Promise<T>} options.fn
+ * @returns {Promise<T>}
+ */
+export function record_span({ name, tracer, attributes, fn }) {
+	return tracer.startActiveSpan(name, { attributes }, async (span) => {
+		try {
+			const result = await fn(span);
+			span.end();
+			return result;
+		} catch (error) {
+			if (error instanceof HttpError) {
+				span.setAttributes({
+					[`${name}.result.type`]: 'known_error',
+					[`${name}.result.status`]: error.status,
+					[`${name}.result.message`]: error.body.message
+				});
+				span.recordException({
+					name: 'HttpError',
+					message: error.body.message
+				});
+				span.setStatus({
+					code: SpanStatusCode.ERROR,
+					message: error.body.message
+				});
+			} else if (error instanceof Redirect) {
+				span.setAttributes({
+					[`${name}.result.type`]: 'redirect',
+					[`${name}.result.status`]: error.status,
+					[`${name}.result.location`]: error.location
+				});
+			} else if (error instanceof Error) {
+				span.setAttributes({
+					[`${name}.result.type`]: 'unknown_error'
+				});
+				span.recordException({
+					name: error.name,
+					message: error.message,
+					stack: error.stack
+				});
+				span.setStatus({
+					code: SpanStatusCode.ERROR,
+					message: error.message
+				});
+			} else {
+				span.setAttributes({
+					[`${name}.result.type`]: 'unknown_error'
+				});
+				span.setStatus({ code: SpanStatusCode.ERROR });
+			}
+			span.end();
+
+			throw error;
+		}
+	});
+}

packages/kit/src/runtime/server/telemetry/settings.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Telemetry configuration.
+ */
+// This is meant to be both flexible for custom app requirements (metadata)
+// and extensible for standardization (example: functionId, more to come).
+export type TelemetrySettings = {
+	/**
+	 * Enable or disable telemetry. Disabled by default while experimental.
+	 */
+	enabled?: boolean;
+};