|
| 1 | +--- |
| 2 | +title: 'Introducing integrated observability in SvelteKit' |
| 3 | +description: 'SvelteKit apps can now emit OpenTelemetry traces and reliably set up observability instrumentation using instrumentation.server.ts' |
| 4 | +author: Elliott Johnson |
| 5 | +authorURL: https://bsky.app/profile/gruntled.bsky.social |
| 6 | +--- |
| 7 | + |
| 8 | +Understanding how your SvelteKit application behaves in production — from request flows to performance bottlenecks — is crucial for building reliable user experiences. SvelteKit now has first-class support for observability: built-in [OpenTelemetry](https://opentelemetry.io/) tracing, and a dedicated instrumentation setup file that ensures your monitoring tools work seamlessly. |
| 9 | + |
| 10 | +To opt in, upgrade SvelteKit and your adapter and add the following to your `svelte.config.js`: |
| 11 | + |
| 12 | +```js |
| 13 | +/// file: svelte.config.js |
| 14 | +export default { |
| 15 | + kit: { |
| 16 | + experimental: { |
| 17 | + tracing: { |
| 18 | + server: true |
| 19 | + }, |
| 20 | + instrumentation: { |
| 21 | + server: true |
| 22 | + } |
| 23 | + } |
| 24 | + } |
| 25 | +}; |
| 26 | +``` |
| 27 | + |
| 28 | +## First-party OpenTelemetry traces |
| 29 | + |
| 30 | +SvelteKit can now emit [OpenTelemetry](https://opentelemetry.io) traces for the following: |
| 31 | + |
| 32 | +- [`handle`](/docs/kit/hooks#Server-hooks-handle) hook (`handle` functions running in a [`sequence`](/docs/kit/@sveltejs-kit-hooks#sequence) will show up as children of each other and the root handle hook) |
| 33 | +- [`load`](/docs/kit/load) functions (includes universal `load` functions when they run on the server) |
| 34 | +- [Form actions](/docs/kit/form-actions) |
| 35 | +- [Remote functions](/docs/kit/remote-functions) |
| 36 | + |
| 37 | +The emitted spans include attributes describing the current request, such as `http.route`, and surrounding context, such as the `+page` or `+layout` file associated with a `load` function. If there are additional attributes you think might be useful, please file an issue on the [SvelteKit GitHub issue tracker](https://github.com/sveltejs/kit/issues). |
| 38 | + |
| 39 | +## A convenient home for all of your instrumentation |
| 40 | + |
| 41 | +Emitting traces alone is not enough: You also need to collect them and send them somewhere. Under normal circumstances, this can be a bit challenging. Because of the nature of observability instrumentation, it needs to be loaded prior to loading any of the code from your app. To aid in this, SvelteKit now supports a `src/instrumentation.server.ts` file which, assuming your adapter supports it, is guaranteed to be loaded prior to your application code. |
| 42 | + |
| 43 | +In Node, your instrumentation might look something like this: |
| 44 | + |
| 45 | +```ts |
| 46 | +import { NodeSDK } from '@opentelemetry/sdk-node'; |
| 47 | +import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'; |
| 48 | +import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'; |
| 49 | +import { createAddHookMessageChannel } from 'import-in-the-middle'; |
| 50 | +import { register } from 'module'; |
| 51 | + |
| 52 | +const { registerOptions } = createAddHookMessageChannel(); |
| 53 | +register('import-in-the-middle/hook.mjs', import.meta.url, registerOptions); |
| 54 | + |
| 55 | +const sdk = new NodeSDK({ |
| 56 | + serviceName: 'my-sveltekit-app', |
| 57 | + traceExporter: new OTLPTraceExporter(), |
| 58 | + instrumentations: [getNodeAutoInstrumentations()] |
| 59 | +}); |
| 60 | + |
| 61 | +sdk.start(); |
| 62 | +``` |
| 63 | + |
| 64 | +If you're deploying to Vercel, it would look something like this: |
| 65 | + |
| 66 | +```ts |
| 67 | +import { registerOTel } from '@vercel/otel'; |
| 68 | + |
| 69 | +registerOTel({ |
| 70 | + serviceName: 'my-sveltekit-app' |
| 71 | +}); |
| 72 | +``` |
| 73 | + |
| 74 | +Consult your platform's documentation for specific instrumentation instructions. As of now, all of the official SvelteKit adapters with a server component (sorry, `adapter-static`) support `instrumentation.server.ts`. |
| 75 | + |
| 76 | +## Acknowledgements |
| 77 | + |
| 78 | +A huge thank-you to Lukas Stracke, who kicked us off on this adventure with his excellent [talk at Svelte Summit 2025](https://www.youtube.com/watch?v=hFVmFAyB_YA) and his initial draft PR for `instrumentation.server.ts`. Another thank-you to [Sentry](https://sentry.io/welcome/) for allowing him to spend his working hours reviewing and testing our work. |
0 commit comments