feat: OpenTelemetry Tracing

.changeset/early-taxis-make.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: OpenTelemetry tracing for `handle`, `sequence`, form actions, remote functions, and `load` functions running on the server

.changeset/whole-bananas-sort.md

@@ -0,0 +1,9 @@
+---
+'@sveltejs/adapter-cloudflare': minor
+'@sveltejs/adapter-netlify': minor
+'@sveltejs/adapter-vercel': minor
+'@sveltejs/adapter-node': minor
+'@sveltejs/kit': minor
+---
+
+feat: add `tracing.server.ts` for tracing instrumentation and setup

documentation/docs/10-getting-started/30-project-structure.md

@@ -19,7 +19,8 @@ my-project/
 │ ├ error.html
 │ ├ hooks.client.js
 │ ├ hooks.server.js
-│ └ service-worker.js
+| ├ service-worker.js
+│ └ tracing.server.js
 ├ static/
 │ └ [your static assets]
 ├ tests/
@@ -54,6 +55,7 @@ The `src` directory contains the meat of your project. Everything except `src/ro
 - `hooks.client.js` contains your client [hooks](hooks)
 - `hooks.server.js` contains your server [hooks](hooks)
 - `service-worker.js` contains your [service worker](service-workers)
+- `tracing.server.js` contains your [tracing](observability) setup and instrumentation code
 
 (Whether the project contains `.js` or `.ts` files depends on whether you opt to use TypeScript when you create your project.)
 

documentation/docs/25-build-and-deploy/99-writing-adapters.md

@@ -34,6 +34,10 @@ export default function (options) {
 				// Return `true` if the route with the given `config` can use `read`
 				// from `$app/server` in production, return `false` if it can't.
 				// Or throw a descriptive error describing how to configure the deployment
+			},
+			tracing: () => {
+				// Return `true` if this adapter supports loading `tracing.server.js`.
+				// Return `false if it can't, or throw a descriptive error.
 			}
 		}
 	};

documentation/docs/30-advanced/68-observability.md

@@ -0,0 +1,68 @@
+---
+title: Observability
+---
+
+<blockquote class="since note">
+	<p>Available since 2.29</p>
+</blockquote>
+
+> [!NOTE] This feature is experimental. Expect bugs and breaking changes in minor versions (though we'll do our best to keep those to an absolute minimum). Please provide feedback!
+
+Sometimes, you may need to observe how your application is behaving in order to improve performance or find the root cause of a pesky bug. To help with this, SvelteKit can emit server-side [OpenTelemetry](https://opentelemetry.io) spans for the following:
+
+- [`handle`](hooks#Server-hooks-handle) hook (`handle` functions running in a [`sequence`](@sveltejs-kit-hooks#sequence) will show up as children of each other and the root handle hook) 
+- [`load`](load) functions (includes universal `load` functions when they're run on the server)
+- [Form actions](form-actions)
+- [Remote functions](remote-functions)
+
+Just telling SvelteKit to emit spans won't get you far, though -- you need to actually collect them somewhere to be able to view them. SvelteKit provides `src/tracing.server.ts` as a place to write your tracing setup and instrumentation code. It's guaranteed to be run prior to your application code being imported, providing your deployment platform supports it and your adapter is aware of it.
+
+To enable both of these features, add the following to your `svelte.config.js`:
+
+```js  
+/// file: svelte.config.js  
+export default {  
+    kit: {  
+        +++experimental: {  
+            tracing: {  
+              server: true,  
+              serverFile: true  
+            } 
+        }+++
+    }  
+};  
+```
+
+> [!NOTE] Tracing -- and more significantly, tracing instrumentation -- can have a nontrivial overhead. Before you go all-in on tracing, consider whether or not you really need it, or if it might be more appropriate to turn it on in development and preview environments only.
+
+## Development quickstart
+
+To view your first trace, you'll need to set up a local collector. We'll use [Jaeger](https://www.jaegertracing.io/docs/getting-started/) in this example, as they provide an easy-to-use quickstart command. Once your collector is running locally:
+
+- Turn on the experimental flag mentioned above in your `svelte.config.js` file
+- Use your package manager to install `@opentelemetry/sdk-node`, `@opentelemetry/auto-instrumentations-node`, `@opentelemetry/exporter-trace-otlp-proto`, and `import-in-the-middle`
+  ```sh
+  npm i @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-oltp-proto import-in-the-middle
+  ```
+- Create `src/tracing.server.ts` with the following:
+
+```ts
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
+import { createAddHookMessageChannel } from 'import-in-the-middle';
+import { register } from 'module';
+
+const { registerOptions } = createAddHookMessageChannel();
+register('import-in-the-middle/hook.mjs', import.meta.url, registerOptions);
+
+const sdk = new NodeSDK({
+	serviceName: 'test-sveltekit-tracing',
+	traceExporter: new OTLPTraceExporter(),
+	instrumentations: [getNodeAutoInstrumentations()]
+});
+
+sdk.start();
+```
+
+Any server-side requests will now begin generating traces, which you can view in Jaeger's web console at [localhost:16686](http://localhost:16686).

package.json

@@ -40,6 +40,7 @@
 			"@parcel/watcher",
 			"esbuild",
 			"netlify-cli",
+			"protobufjs",
 			"rolldown",
 			"sharp",
 			"svelte-preprocess",

packages/adapter-auto/index.js

@@ -152,6 +152,9 @@ export default () => ({
 			supports_error(
 				'The read function imported from $app/server only works in certain environments'
 			);
+		},
+		tracing: () => {
+			supports_error('`tracing.server.js` only works in certain environments');
 		}
 	}
 });

packages/adapter-auto/package.json

@@ -42,7 +42,7 @@
 	"devDependencies": {
 		"@sveltejs/kit": "workspace:^",
 		"@sveltejs/vite-plugin-svelte": "catalog:",
-		"@types/node": "^18.19.119",
+		"@types/node": "catalog:",
 		"typescript": "^5.3.3",
 		"vitest": "catalog:"
 	},

packages/adapter-cloudflare/index.js

@@ -113,6 +113,12 @@ export default function (options = {}) {
 					ASSETS: assets_binding
 				}
 			});
+			if (builder.hasServerTracingFile()) {
+				builder.trace({
+					entrypoint: worker_dest,
+					tracing: `${builder.getServerDirectory()}/tracing.server.js`
+				});
+			}
 
 			// _headers
 			if (existsSync('_headers')) {
@@ -184,7 +190,8 @@ export default function (options = {}) {
 				}
 
 				return true;
-			}
+			},
+			tracing: () => true
 		}
 	};
 }

packages/adapter-cloudflare/package.json

@@ -50,7 +50,7 @@
 	"devDependencies": {
 		"@playwright/test": "catalog:",
 		"@sveltejs/kit": "workspace:^",
-		"@types/node": "^18.19.119",
+		"@types/node": "catalog:",
 		"esbuild": "^0.25.4",
 		"typescript": "^5.3.3",
 		"vitest": "catalog:"

packages/adapter-netlify/index.js

@@ -1,3 +1,4 @@
+/** @import { BuildOptions } from 'esbuild' */
 import { appendFileSync, existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve, posix } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -106,7 +107,8 @@ export default function ({ split = false, edge = edge_set_in_env_var } = {}) {
 				}
 
 				return true;
-			}
+			},
+			tracing: () => true
 		}
 	};
 }
@@ -174,9 +176,8 @@ async function generate_edge_functions({ builder }) {
 		version: 1
 	};
 
-	await esbuild.build({
-		entryPoints: [`${tmp}/entry.js`],
-		outfile: '.netlify/edge-functions/render.js',
+	/** @type {BuildOptions} */
+	const esbuild_config = {
 		bundle: true,
 		format: 'esm',
 		platform: 'browser',
@@ -194,7 +195,28 @@ async function generate_edge_functions({ builder }) {
 		// https://docs.netlify.com/edge-functions/api/#runtime-environment
 		external: builtinModules.map((id) => `node:${id}`),
 		alias: Object.fromEntries(builtinModules.map((id) => [id, `node:${id}`]))
-	});
+	};
+	await Promise.all([
+		esbuild.build({
+			entryPoints: [`${tmp}/entry.js`],
+			outfile: '.netlify/edge-functions/render.js',
+			...esbuild_config
+		}),
+		builder.hasServerTracingFile() &&
+			esbuild.build({
+				entryPoints: [`${builder.getServerDirectory()}/tracing.server.js`],
+				outfile: '.netlify/edge/tracing.server.js',
+				...esbuild_config
+			})
+	]);
+
+	if (builder.hasServerTracingFile()) {
+		builder.trace({
+			entrypoint: '.netlify/edge-functions/render.js',
+			tracing: '.netlify/edge/tracing.server.js',
+			start: '.netlify/edge/start.js'
+		});
+	}
 
 	writeFileSync('.netlify/edge-functions/manifest.json', JSON.stringify(edge_manifest));
 }
@@ -272,6 +294,16 @@ function generate_lambda_functions({ builder, publish, split }) {
 
 			writeFileSync(`.netlify/functions-internal/${name}.mjs`, fn);
 			writeFileSync(`.netlify/functions-internal/${name}.json`, fn_config);
+			if (builder.hasServerTracingFile()) {
+				builder.trace({
+					entrypoint: `.netlify/functions-internal/${name}.mjs`,
+					tracing: '.netlify/server/tracing.server.js',
+					start: `.netlify/functions-start/${name}.start.mjs`,
+					module: {
+						exports: ['handler']
+					}
+				});
+			}
 
 			const redirect = `/.netlify/functions/${name} 200`;
 			redirects.push(`${pattern} ${redirect}`);
@@ -286,6 +318,17 @@ function generate_lambda_functions({ builder, publish, split }) {
 
 		writeFileSync(`.netlify/functions-internal/${FUNCTION_PREFIX}render.json`, fn_config);
 		writeFileSync(`.netlify/functions-internal/${FUNCTION_PREFIX}render.mjs`, fn);
+		if (builder.hasServerTracingFile()) {
+			builder.trace({
+				entrypoint: `.netlify/functions-internal/${FUNCTION_PREFIX}render.mjs`,
+				tracing: '.netlify/server/tracing.server.js',
+				start: `.netlify/functions-start/${FUNCTION_PREFIX}render.start.mjs`,
+				module: {
+					exports: ['handler']
+				}
+			});
+		}
+
 		redirects.push(`* /.netlify/functions/${FUNCTION_PREFIX}render 200`);
 	}
 

packages/adapter-netlify/package.json

@@ -55,7 +55,7 @@
 		"@rollup/plugin-node-resolve": "^16.0.0",
 		"@sveltejs/kit": "workspace:^",
 		"@sveltejs/vite-plugin-svelte": "catalog:",
-		"@types/node": "^18.19.119",
+		"@types/node": "catalog:",
 		"@types/set-cookie-parser": "^2.4.7",
 		"rollup": "^4.14.2",
 		"typescript": "^5.3.3",

packages/adapter-netlify/test/apps/basic/src/tracing.server.js

@@ -0,0 +1 @@
+// this is just here to make sure the changes resulting from it work

packages/adapter-netlify/test/apps/basic/svelte.config.js

@@ -3,7 +3,12 @@ import adapter from '../../../index.js';
 /** @type {import('@sveltejs/kit').Config} */
 const config = {
 	kit: {
-		adapter: adapter()
+		adapter: adapter(),
+		experimental: {
+			tracing: {
+				serverFile: true
+			}
+		}
 	}
 };
 

packages/adapter-node/index.js

@@ -48,14 +48,21 @@ export default function (opts = {}) {
 
 			const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
 
+			/** @type {Record<string, string>} */
+			const input = {
+				index: `${tmp}/index.js`,
+				manifest: `${tmp}/manifest.js`
+			};
+
+			if (builder.hasServerTracingFile()) {
+				input['tracing.server'] = `${tmp}/tracing.server.js`;
+			}
+
 			// we bundle the Vite output so that deployments only need
 			// their production dependencies. Anything in devDependencies
 			// will get included in the bundled code
 			const bundle = await rollup({
-				input: {
-					index: `${tmp}/index.js`,
-					manifest: `${tmp}/manifest.js`
-				},
+				input,
 				external: [
 					// dependencies could have deep exports, so we need a regex
 					...Object.keys(pkg.dependencies || {}).map((d) => new RegExp(`^${d}(\\/.*)?$`))
@@ -89,10 +96,21 @@ export default function (opts = {}) {
 					ENV_PREFIX: JSON.stringify(envPrefix)
 				}
 			});
+
+			if (builder.hasServerTracingFile()) {
+				builder.trace({
+					entrypoint: `${out}/index.js`,
+					tracing: `${out}/server/tracing.server.js`,
+					module: {
+						exports: ['path', 'host', 'port', 'server']
+					}
+				});
+			}
 		},
 
 		supports: {
-			read: () => true
+			read: () => true,
+			tracing: () => true
 		}
 	};
 }

packages/adapter-node/package.json

@@ -45,7 +45,7 @@
 		"@polka/url": "^1.0.0-next.28",
 		"@sveltejs/kit": "workspace:^",
 		"@sveltejs/vite-plugin-svelte": "catalog:",
-		"@types/node": "^18.19.119",
+		"@types/node": "catalog:",
 		"polka": "^1.0.0-next.28",
 		"sirv": "^3.0.0",
 		"typescript": "^5.3.3",

packages/adapter-static/package.json

@@ -42,7 +42,7 @@
 		"@playwright/test": "catalog:",
 		"@sveltejs/kit": "workspace:^",
 		"@sveltejs/vite-plugin-svelte": "catalog:",
-		"@types/node": "^18.19.119",
+		"@types/node": "catalog:",
 		"sirv": "^3.0.0",
 		"svelte": "^5.35.5",
 		"typescript": "^5.3.3",