@sveltejs/kit 2.30.1 → 2.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sveltejs/kit",
-  "version": "2.30.1",
+  "version": "2.31.0",
   "description": "SvelteKit is the fastest way to build Svelte apps",
   "keywords": [
     "framework",
@@ -33,6 +33,7 @@
     "sirv": "^3.0.0"
   },
   "devDependencies": {
+    "@opentelemetry/api": "^1.0.0",
     "@playwright/test": "^1.51.1",
     "@sveltejs/vite-plugin-svelte": "^6.0.0-next.3",
     "@types/connect": "^3.4.38",
@@ -48,9 +49,15 @@
   },
   "peerDependencies": {
     "@sveltejs/vite-plugin-svelte": "^3.0.0 || ^4.0.0-next.1 || ^5.0.0 || ^6.0.0-next.0",
+    "@opentelemetry/api": "^1.0.0",
     "svelte": "^4.0.0 || ^5.0.0-next.0",
     "vite": "^5.0.3 || ^6.0.0 || ^7.0.0-beta.0"
   },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
   "bin": {
     "svelte-kit": "svelte-kit.js"
   },
@@ -72,6 +79,10 @@
       "types": "./types/index.d.ts",
       "import": "./src/exports/internal/index.js"
     },
+    "./internal/server": {
+      "types": "./types/index.d.ts",
+      "import": "./src/exports/internal/server.js"
+    },
     "./node": {
       "types": "./types/index.d.ts",
       "import": "./src/exports/node/index.js"

package/src/core/adapt/builder.js

@@ -1,6 +1,10 @@
+/** @import { Builder } from '@sveltejs/kit' */
+/** @import { ResolvedConfig } from 'vite' */
+/** @import { RouteDefinition } from '@sveltejs/kit' */
+/** @import { RouteData, ValidatedConfig, BuildData, ServerMetadata, ServerMetadataRoute, Prerendered, PrerenderMap, Logger } from 'types' */
 import colors from 'kleur';
 import { createReadStream, createWriteStream, existsSync, statSync } from 'node:fs';
-import { extname, resolve } from 'node:path';
+import { extname, resolve, join, dirname, relative } from 'node:path';
 import { pipeline } from 'node:stream';
 import { promisify } from 'node:util';
 import zlib from 'node:zlib';
@@ -12,6 +16,7 @@ import generate_fallback from '../postbuild/fallback.js';
 import { write } from '../sync/utils.js';
 import { list_files } from '../utils.js';
 import { find_server_assets } from '../generate_manifest/find_server_assets.js';
+import { reserved } from '../env.js';
 
 const pipe = promisify(pipeline);
 const extensions = ['.html', '.js', '.mjs', '.json', '.css', '.svg', '.xml', '.wasm'];
@@ -19,16 +24,16 @@ const extensions = ['.html', '.js', '.mjs', '.json', '.css', '.svg', '.xml', '.w
 /**
  * Creates the Builder which is passed to adapters for building the application.
  * @param {{
- *   config: import('types').ValidatedConfig;
- *   build_data: import('types').BuildData;
- *   server_metadata: import('types').ServerMetadata;
- *   route_data: import('types').RouteData[];
- *   prerendered: import('types').Prerendered;
- *   prerender_map: import('types').PrerenderMap;
- *   log: import('types').Logger;
- *   vite_config: import('vite').ResolvedConfig;
+ *   config: ValidatedConfig;
+ *   build_data: BuildData;
+ *   server_metadata: ServerMetadata;
+ *   route_data: RouteData[];
+ *   prerendered: Prerendered;
+ *   prerender_map: PrerenderMap;
+ *   log: Logger;
+ *   vite_config: ResolvedConfig;
  * }} opts
- * @returns {import('@sveltejs/kit').Builder}
+ * @returns {Builder}
  */
 export function create_builder({
 	config,
@@ -40,7 +45,7 @@ export function create_builder({
 	log,
 	vite_config
 }) {
-	/** @type {Map<import('@sveltejs/kit').RouteDefinition, import('types').RouteData>} */
+	/** @type {Map<RouteDefinition, RouteData>} */
 	const lookup = new Map();
 
 	/**
@@ -48,11 +53,11 @@ export function create_builder({
 	 * we expose a stable type that adapters can use to group/filter routes
 	 */
 	const routes = route_data.map((route) => {
-		const { config, methods, page, api } = /** @type {import('types').ServerMetadataRoute} */ (
+		const { config, methods, page, api } = /** @type {ServerMetadataRoute} */ (
 			server_metadata.routes.get(route.id)
 		);
 
-		/** @type {import('@sveltejs/kit').RouteDefinition} */
+		/** @type {RouteDefinition} */
 		const facade = {
 			id: route.id,
 			api,
@@ -229,6 +234,53 @@ export function create_builder({
 
 		writeServer(dest) {
 			return copy(`${config.kit.outDir}/output/server`, dest);
+		},
+
+		hasServerInstrumentationFile() {
+			return existsSync(`${config.kit.outDir}/output/server/instrumentation.server.js`);
+		},
+
+		instrument({
+			entrypoint,
+			instrumentation,
+			start = join(dirname(entrypoint), 'start.js'),
+			module = {
+				exports: ['default']
+			}
+		}) {
+			if (!existsSync(instrumentation)) {
+				throw new Error(
+					`Instrumentation file ${instrumentation} not found. This is probably a bug in your adapter.`
+				);
+			}
+			if (!existsSync(entrypoint)) {
+				throw new Error(
+					`Entrypoint file ${entrypoint} not found. This is probably a bug in your adapter.`
+				);
+			}
+
+			copy(entrypoint, start);
+			if (existsSync(`${entrypoint}.map`)) {
+				copy(`${entrypoint}.map`, `${start}.map`);
+			}
+
+			const relative_instrumentation = relative(dirname(entrypoint), instrumentation);
+			const relative_start = relative(dirname(entrypoint), start);
+
+			const facade =
+				'generateText' in module
+					? module.generateText({
+							instrumentation: relative_instrumentation,
+							start: relative_start
+						})
+					: create_instrumentation_facade({
+							instrumentation: relative_instrumentation,
+							start: relative_start,
+							exports: module.exports
+						});
+
+			rimraf(entrypoint);
+			write(entrypoint, facade);
 		}
 	};
 }
@@ -254,3 +306,60 @@ async function compress_file(file, format = 'gz') {
 
 	await pipe(source, compress, destination);
 }
+
+/**
+ * Given a list of exports, generate a facade that:
+ * - Imports the instrumentation file
+ * - Imports `exports` from the entrypoint (dynamically, if `tla` is true)
+ * - Re-exports `exports` from the entrypoint
+ *
+ * `default` receives special treatment: It will be imported as `default` and exported with `export default`.
+ *
+ * @param {{ instrumentation: string; start: string; exports: string[] }} opts
+ * @returns {string}
+ */
+function create_instrumentation_facade({ instrumentation, start, exports }) {
+	const import_instrumentation = `import './${instrumentation}';`;
+
+	let alias_index = 0;
+	const aliases = new Map();
+
+	for (const name of exports.filter((name) => reserved.has(name))) {
+		/*
+		 * you can do evil things like `export { c as class }`.
+		 * in order to import these, you need to alias them, and then un-alias them when re-exporting
+		 * this map will allow us to generate the following:
+		 * import { class as _1 } from 'entrypoint';
+		 * export { _1 as class };
+		 */
+		let alias = `_${alias_index++}`;
+		while (exports.includes(alias)) {
+			alias = `_${alias_index++}`;
+		}
+
+		aliases.set(name, alias);
+	}
+
+	const import_statements = [];
+	const export_statements = [];
+
+	for (const name of exports) {
+		const alias = aliases.get(name);
+		if (alias) {
+			import_statements.push(`${name}: ${alias}`);
+			export_statements.push(`${alias} as ${name}`);
+		} else {
+			import_statements.push(`${name}`);
+			export_statements.push(`${name}`);
+		}
+	}
+
+	const entrypoint_facade = [
+		`const { ${import_statements.join(', ')} } = await import('./${start}');`,
+		export_statements.length > 0 ? `export { ${export_statements.join(', ')} };` : ''
+	]
+		.filter(Boolean)
+		.join('\n');
+
+	return `${import_instrumentation}\n${entrypoint_facade}`;
+}

package/src/core/config/options.js

@@ -120,6 +120,12 @@ const options = object(
 			}),
 
 			experimental: object({
+				tracing: object({
+					server: boolean(false)
+				}),
+				instrumentation: object({
+					server: boolean(false)
+				}),
 				remoteFunctions: boolean(false)
 			}),
 

package/src/exports/hooks/sequence.js

@@ -1,3 +1,11 @@
+/** @import { Handle, RequestEvent, ResolveOptions } from '@sveltejs/kit' */
+/** @import { MaybePromise } from 'types' */
+import {
+	merge_tracing,
+	get_request_store,
+	with_request_store
+} from '@sveltejs/kit/internal/server';
+
 /**
  * A helper function for sequencing multiple `handle` calls in a middleware-like manner.
  * The behavior for the `handle` options is as follows:
@@ -66,56 +74,70 @@
  * first post-processing
  * ```
  *
- * @param {...import('@sveltejs/kit').Handle} handlers The chain of `handle` functions
- * @returns {import('@sveltejs/kit').Handle}
+ * @param {...Handle} handlers The chain of `handle` functions
+ * @returns {Handle}
  */
 export function sequence(...handlers) {
 	const length = handlers.length;
 	if (!length) return ({ event, resolve }) => resolve(event);
 
 	return ({ event, resolve }) => {
+		const { state } = get_request_store();
 		return apply_handle(0, event, {});
 
 		/**
 		 * @param {number} i
-		 * @param {import('@sveltejs/kit').RequestEvent} event
-		 * @param {import('@sveltejs/kit').ResolveOptions | undefined} parent_options
-		 * @returns {import('types').MaybePromise<Response>}
+		 * @param {RequestEvent} event
+		 * @param {ResolveOptions | undefined} parent_options
+		 * @returns {MaybePromise<Response>}
 		 */
 		function apply_handle(i, event, parent_options) {
 			const handle = handlers[i];
 
-			return handle({
-				event,
-				resolve: (event, options) => {
-					/** @type {import('@sveltejs/kit').ResolveOptions['transformPageChunk']} */
-					const transformPageChunk = async ({ html, done }) => {
-						if (options?.transformPageChunk) {
-							html = (await options.transformPageChunk({ html, done })) ?? '';
-						}
+			return state.tracing.record_span({
+				name: `sveltekit.handle.sequenced.${handle.name ? handle.name : i}`,
+				attributes: {},
+				fn: async (current) => {
+					const traced_event = merge_tracing(event, current);
+					return await with_request_store({ event: traced_event, state }, () =>
+						handle({
+							event: traced_event,
+							resolve: (event, options) => {
+								/** @type {ResolveOptions['transformPageChunk']} */
+								const transformPageChunk = async ({ html, done }) => {
+									if (options?.transformPageChunk) {
+										html = (await options.transformPageChunk({ html, done })) ?? '';
+									}
 
-						if (parent_options?.transformPageChunk) {
-							html = (await parent_options.transformPageChunk({ html, done })) ?? '';
-						}
+									if (parent_options?.transformPageChunk) {
+										html = (await parent_options.transformPageChunk({ html, done })) ?? '';
+									}
 
-						return html;
-					};
+									return html;
+								};
 
-					/** @type {import('@sveltejs/kit').ResolveOptions['filterSerializedResponseHeaders']} */
-					const filterSerializedResponseHeaders =
-						parent_options?.filterSerializedResponseHeaders ??
-						options?.filterSerializedResponseHeaders;
+								/** @type {ResolveOptions['filterSerializedResponseHeaders']} */
+								const filterSerializedResponseHeaders =
+									parent_options?.filterSerializedResponseHeaders ??
+									options?.filterSerializedResponseHeaders;
 
-					/** @type {import('@sveltejs/kit').ResolveOptions['preload']} */
-					const preload = parent_options?.preload ?? options?.preload;
+								/** @type {ResolveOptions['preload']} */
+								const preload = parent_options?.preload ?? options?.preload;
 
-					return i < length - 1
-						? apply_handle(i + 1, event, {
-								transformPageChunk,
-								filterSerializedResponseHeaders,
-								preload
-							})
-						: resolve(event, { transformPageChunk, filterSerializedResponseHeaders, preload });
+								return i < length - 1
+									? apply_handle(i + 1, event, {
+											transformPageChunk,
+											filterSerializedResponseHeaders,
+											preload
+										})
+									: resolve(event, {
+											transformPageChunk,
+											filterSerializedResponseHeaders,
+											preload
+										});
+							}
+						})
+					);
 				}
 			});
 		}

package/src/{runtime/app/server → exports/internal}/event.js

@@ -1,9 +1,11 @@
 /** @import { RequestEvent } from '@sveltejs/kit' */
+/** @import { RequestStore } from 'types' */
+/** @import { AsyncLocalStorage } from 'node:async_hooks' */
 
-/** @type {RequestEvent | null} */
-let request_event = null;
+/** @type {RequestStore | null} */
+let sync_store = null;
 
-/** @type {import('node:async_hooks').AsyncLocalStorage<RequestEvent | null>} */
+/** @type {AsyncLocalStorage<RequestStore | null> | null} */
 let als;
 
 import('node:async_hooks')
@@ -19,10 +21,11 @@ import('node:async_hooks')
  *
  * In environments without [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage), this must be called synchronously (i.e. not after an `await`).
  * @since 2.20.0
+ *
  * @returns {RequestEvent}
  */
 export function getRequestEvent() {
-	const event = request_event ?? als?.getStore();
+	const event = try_get_request_store()?.event;
 
 	if (!event) {
 		let message =
@@ -39,16 +42,28 @@ export function getRequestEvent() {
 	return event;
 }
 
+export function get_request_store() {
+	const result = try_get_request_store();
+	if (!result) {
+		throw new Error('Could not get the request store. This is an internal error.');
+	}
+	return result;
+}
+
+export function try_get_request_store() {
+	return sync_store ?? als?.getStore() ?? null;
+}
+
 /**
  * @template T
- * @param {RequestEvent | null} event
+ * @param {RequestStore | null} store
  * @param {() => T} fn
  */
-export function with_event(event, fn) {
+export function with_request_store(store, fn) {
 	try {
-		request_event = event;
-		return als ? als.run(event, fn) : fn();
+		sync_store = store;
+		return als ? als.run(store, fn) : fn();
 	} finally {
-		request_event = null;
+		sync_store = null;
 	}
 }

package/src/exports/internal/server.js

@@ -0,0 +1,22 @@
+/**
+ * @template {{ tracing: { enabled: boolean, root: import('@opentelemetry/api').Span, current: import('@opentelemetry/api').Span } }} T
+ * @param {T} event_like
+ * @param {import('@opentelemetry/api').Span} current
+ * @returns {T}
+ */
+export function merge_tracing(event_like, current) {
+	return {
+		...event_like,
+		tracing: {
+			...event_like.tracing,
+			current
+		}
+	};
+}
+
+export {
+	with_request_store,
+	getRequestEvent,
+	get_request_store,
+	try_get_request_store
+} from './event.js';

package/src/exports/public.d.ts

@@ -17,13 +17,14 @@ import {
 	RouteSegment
 } from '../types/private.js';
 import { BuildData, SSRNodeLoader, SSRRoute, ValidatedConfig } from 'types';
-import type { SvelteConfig } from '@sveltejs/vite-plugin-svelte';
-import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { SvelteConfig } from '@sveltejs/vite-plugin-svelte';
+import { StandardSchemaV1 } from '@standard-schema/spec';
 import {
 	RouteId as AppRouteId,
 	LayoutParams as AppLayoutParams,
 	ResolvedPathname
 } from '$app/types';
+import { Span } from '@opentelemetry/api';
 
 export { PrerenderOption } from '../types/private.js';
 
@@ -49,6 +50,12 @@ export interface Adapter {
 		 * @param details.config The merged route config
 		 */
 		read?: (details: { config: any; route: { id: string } }) => boolean;
+
+		/**
+		 * Test support for `instrumentation.server.js`. To pass, the adapter must support running `instrumentation.server.js` prior to the application code.
+		 * @since 2.31.0
+		 */
+		instrumentation?: () => boolean;
 	};
 	/**
 	 * Creates an `Emulator`, which allows the adapter to influence the environment
@@ -186,6 +193,47 @@ export interface Builder {
 		}
 	) => string[];
 
+	/**
+	 * Check if the server instrumentation file exists.
+	 * @returns true if the server instrumentation file exists, false otherwise
+	 * @since 2.31.0
+	 */
+	hasServerInstrumentationFile: () => boolean;
+
+	/**
+	 * Instrument `entrypoint` with `instrumentation`.
+	 *
+	 * Renames `entrypoint` to `start` and creates a new module at
+	 * `entrypoint` which imports `instrumentation` and then dynamically imports `start`. This allows
+	 * the module hooks necessary for instrumentation libraries to be loaded prior to any application code.
+	 *
+	 * Caveats:
+	 * - "Live exports" will not work. If your adapter uses live exports, your users will need to manually import the server instrumentation on startup.
+	 * - If `tla` is `false`, OTEL auto-instrumentation may not work properly. Use it if your environment supports it.
+	 * - Use `hasServerInstrumentationFile` to check if the user has a server instrumentation file; if they don't, you shouldn't do this.
+	 *
+	 * @param options an object containing the following properties:
+	 * @param options.entrypoint the path to the entrypoint to trace.
+	 * @param options.instrumentation the path to the instrumentation file.
+	 * @param options.start the name of the start file. This is what `entrypoint` will be renamed to.
+	 * @param options.module configuration for the resulting entrypoint module.
+	 * @param options.module.exports
+	 * @param options.module.generateText a function that receives the relative paths to the instrumentation and start files, and generates the text of the module to be traced. If not provided, the default implementation will be used, which uses top-level await.
+	 * @since 2.31.0
+	 */
+	instrument: (args: {
+		entrypoint: string;
+		instrumentation: string;
+		start?: string;
+		module?:
+			| {
+					exports: string[];
+			  }
+			| {
+					generateText: (args: { instrumentation: string; start: string }) => string;
+			  };
+	}) => void;
+
 	/**
 	 * Compress files in `directory` with gzip and brotli, where appropriate. Generates `.gz` and `.br` files alongside the originals.
 	 * @param {string} directory The directory containing the files to be compressed
@@ -407,10 +455,34 @@ export interface KitConfig {
 		 */
 		privatePrefix?: string;
 	};
-	/**
-	 * Experimental features which are exempt from semantic versioning. These features may be changed or removed at any time.
-	 */
+	/** Experimental features. Here be dragons. These are not subject to semantic versioning, so breaking changes or removal can happen in any release. */
 	experimental?: {
+		/**
+		 * Options for enabling server-side [OpenTelemetry](https://opentelemetry.io/) tracing for SvelteKit operations including the [`handle` hook](https://svelte.dev/docs/kit/hooks#Server-hooks-handle), [`load` functions](https://svelte.dev/docs/kit/load), [form actions](https://svelte.dev/docs/kit/form-actions), and [remote functions](https://svelte.dev/docs/kit/remote-functions).
+		 * @default { server: false, serverFile: false }
+		 * @since 2.31.0
+		 */
+		tracing?: {
+			/**
+			 * Enables server-side [OpenTelemetry](https://opentelemetry.io/) span emission for SvelteKit operations including the [`handle` hook](https://svelte.dev/docs/kit/hooks#Server-hooks-handle), [`load` functions](https://svelte.dev/docs/kit/load), [form actions](https://svelte.dev/docs/kit/form-actions), and [remote functions](https://svelte.dev/docs/kit/remote-functions).
+			 * @default false
+			 * @since 2.31.0
+			 */
+			server?: boolean;
+		};
+
+		/**
+		 * @since 2.31.0
+		 */
+		instrumentation?: {
+			/**
+			 * Enables `instrumentation.server.js` for tracing and observability instrumentation.
+			 * @default false
+			 * @since 2.31.0
+			 */
+			server?: boolean;
+		};
+
 		/**
 		 * Whether to enable the experimental remote functions feature. This feature is not yet stable and may be changed or removed at any time.
 		 * @default false
@@ -1026,6 +1098,19 @@ export interface LoadEvent<
 	 * ```
 	 */
 	untrack: <T>(fn: () => T) => T;
+
+	/**
+	 * Access to spans for tracing. If tracing is not enabled or the function is being run in the browser, these spans will do nothing.
+	 * @since 2.31.0
+	 */
+	tracing: {
+		/** Whether tracing is enabled. */
+		enabled: boolean;
+		/** The root span for the request. This span is named `sveltekit.handle.root`. */
+		root: Span;
+		/** The span associated with the current `load` function. */
+		current: Span;
+	};
 }
 
 export interface NavigationEvent<
@@ -1304,6 +1389,20 @@ export interface RequestEvent<
 	 * `true` for `+server.js` calls coming from SvelteKit without the overhead of actually making an HTTP request. This happens when you make same-origin `fetch` requests on the server.
 	 */
 	isSubRequest: boolean;
+
+	/**
+	 * Access to spans for tracing. If tracing is not enabled, these spans will do nothing.
+	 * @since 2.31.0
+	 */
+	tracing: {
+		/** Whether tracing is enabled. */
+		enabled: boolean;
+		/** The root span for the request. This span is named `sveltekit.handle.root`. */
+		root: Span;
+		/** The span associated with the current `handle` hook, `load` function, or form action. */
+		current: Span;
+	};
+
 	/**
 	 * `true` if the request comes from the client via a remote function. The `url` property will be stripped of the internal information
 	 * related to the data request in this case. Use this property instead if the distinction is important to you.
@@ -1467,6 +1566,19 @@ export interface ServerLoadEvent<
 	 * ```
 	 */
 	untrack: <T>(fn: () => T) => T;
+
+	/**
+	 * Access to spans for tracing. If tracing is not enabled, these spans will do nothing.
+	 * @since 2.31.0
+	 */
+	tracing: {
+		/** Whether tracing is enabled. */
+		enabled: boolean;
+		/** The root span for the request. This span is named `sveltekit.handle.root`. */
+		root: Span;
+		/** The span associated with the current server `load` function. */
+		current: Span;
+	};
 }
 
 /**

package/src/exports/vite/dev/index.js

@@ -501,6 +501,14 @@ export async function dev(vite, vite_config, svelte_config) {
 					return;
 				}
 
+				const resolved_instrumentation = resolve_entry(
+					path.join(svelte_config.kit.files.src, 'instrumentation.server')
+				);
+
+				if (resolved_instrumentation) {
+					await vite.ssrLoadModule(resolved_instrumentation);
+				}
+
 				// we have to import `Server` before calling `set_assets`
 				const { Server } = /** @type {import('types').ServerModule} */ (
 					await vite.ssrLoadModule(`${runtime_base}/server/index.js`, { fixStacktrace: true })