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/telemetry/get_tracer.js

@@ -0,0 +1,27 @@
+/** @import { Tracer } from '@opentelemetry/api' */
+import { DEV } from 'esm-env';
+import { noop_tracer } from './noop.js';
+import { load_tracer } from './load_otel.js';
+
+/**
+ * @param {Object} [options={}] - Configuration options
+ * @param {boolean} [options.is_enabled=false] - Whether tracing is enabled
+ * @returns {Promise<Tracer>} The tracer instance
+ */
+export async function get_tracer({ is_enabled = false } = {}) {
+	if (!is_enabled) {
+		return noop_tracer;
+	}
+
+	const otel_tracer = await load_tracer();
+	if (otel_tracer === null) {
+		if (DEV) {
+			console.warn(
+				'Tracing is enabled, but `@opentelemetry/api` is not available. Have you installed it?'
+			);
+		}
+		return noop_tracer;
+	}
+
+	return otel_tracer;
+}

packages/kit/src/runtime/telemetry/get_tracer.spec.js

@@ -0,0 +1,31 @@
+import { describe, test, expect, beforeEach, vi } from 'vitest';
+import { get_tracer } from './get_tracer.js';
+import { noop_tracer } from './noop.js';
+import * as load_otel from './load_otel.js';
+
+describe('validateHeaders', () => {
+	beforeEach(() => {
+		vi.resetAllMocks();
+	});
+
+	test('returns noop tracer if tracing is disabled', async () => {
+		const tracer = await get_tracer({ is_enabled: false });
+		expect(tracer).toBe(noop_tracer);
+	});
+
+	test('returns noop tracer if @opentelemetry/api is not installed, warning', async () => {
+		vi.spyOn(load_otel, 'load_tracer').mockResolvedValue(null);
+		const console_warn_spy = vi.spyOn(console, 'warn');
+
+		const tracer = await get_tracer({ is_enabled: true });
+		expect(tracer).toBe(noop_tracer);
+		expect(console_warn_spy).toHaveBeenCalledWith(
+			'Tracing is enabled, but `@opentelemetry/api` is not available. Have you installed it?'
+		);
+	});
+
+	test('returns otel tracer if @opentelemetry/api is installed', async () => {
+		const tracer = await get_tracer({ is_enabled: true });
+		expect(tracer).not.toBe(noop_tracer);
+	});
+});

packages/kit/src/runtime/telemetry/load_otel.js

@@ -0,0 +1,23 @@
+/**
+ * @returns {Promise<import('@opentelemetry/api').Tracer | null>}
+ */
+export async function load_tracer() {
+	try {
+		const { trace } = await import('@opentelemetry/api');
+		return trace.getTracer('sveltekit');
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * @returns {Promise<typeof import('@opentelemetry/api').SpanStatusCode | null>}
+ */
+export async function load_status_code() {
+	try {
+		const { SpanStatusCode } = await import('@opentelemetry/api');
+		return SpanStatusCode;
+	} catch {
+		return null;
+	}
+}

packages/kit/src/runtime/telemetry/noop.js

@@ -0,0 +1,81 @@
+/** @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}
+ */
+export 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;
+	},
+	addLink() {
+		return this;
+	},
+	addLinks() {
+		return this;
+	}
+};
+
+/**
+ * @type {SpanContext}
+ */
+const noop_span_context = {
+	traceId: '',
+	spanId: '',
+	traceFlags: 0
+};

packages/kit/src/runtime/telemetry/record_span.js

@@ -0,0 +1,71 @@
+/** @import { Attributes, Span, Tracer } from '@opentelemetry/api' */
+import { HttpError, Redirect } from '../control.js';
+import { load_status_code } from './load_otel.js';
+import { noop_span } from './noop.js';
+
+/**
+ * @template T
+ * @param {Object} options
+ * @param {string} options.name
+ * @param {Tracer} options.tracer
+ * @param {Attributes} options.attributes
+ * @param {function(Span): Promise<T>} options.fn
+ * @returns {Promise<T>}
+ */
+export async function record_span({ name, tracer, attributes, fn }) {
+	const SpanStatusCode = await load_status_code();
+	if (SpanStatusCode === null) {
+		return fn(noop_span);
+	}
+
+	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;
+		}
+	});
+}