SvelteKitAdvanced

Observability

Available since 2.29

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 spans for the following:

handle hook (handle functions running in a sequence will show up as children of each other and the root handle hook)
load functions (includes universal load functions when they’re run on the server)
Form actions
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/instrumentation.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:

svelte.config

export default {
	kit: {
    experimental: {
        tracing: {
 server: boolean;
        };
        instrumentation: {
 server: boolean;
        };
    };
}kit: {
		experimental: {
    tracing: {
        server: boolean;
    };
    instrumentation: {
        server: boolean;
    };
}experimental: {
			tracing: {
    server: boolean;
}tracing: {
				server: booleanserver: true
			},
			instrumentation: {
    server: boolean;
}instrumentation: {
				server: booleanserver: true
			}
		}
	}
};

Tracing — and more significantly, observability 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.

Agumenting SvelteKit’s builtin tracing

SvelteKit provides access to the root span and the current span on the request event. The root span is the one associated with your root handle function, and the current span could be associated with handle, load, a form action, or a remote function, depending on the context. You can annotate these spans with any attributes you wish to record:

$lib/authenticate

import { function getRequestEvent(): RequestEventReturns the current RequestEvent. Can be used inside server hooks, server load functions, actions, and endpoints (and functions called by them).
In environments without AsyncLocalStorage, this must be called synchronously (i.e. not after an await).
@since2.20.0getRequestEvent } from '$app/server';
import { function getAuthenticatedUser(): Promise<{
    id: string;
}>getAuthenticatedUser } from '$lib/auth-core';

async function function authenticate(): Promise<void>authenticate() {
	const const user: {
    id: string;
}user = await function getAuthenticatedUser(): Promise<{
    id: string;
}>getAuthenticatedUser();
	const const event: RequestEvent<Record<string, string>, string | null>event = function getRequestEvent(): RequestEventReturns the current RequestEvent. Can be used inside server hooks, server load functions, actions, and endpoints (and functions called by them).
In environments without AsyncLocalStorage, this must be called synchronously (i.e. not after an await).
@since2.20.0getRequestEvent();
	const event: RequestEvent<Record<string, string>, string | null>event.RequestEvent<Record<string, string>, string | null>.tracing: {
    enabled: boolean;
    root: Span;
    current: Span;
}Access to spans for tracing. If tracing is not enabled, these spans will do nothing.
@since2.31.0tracing.root: SpanThe root span for the request. This span is named sveltekit.handle.root.
root.setAttribute('userId', const user: {
    id: string;
}user.id: stringid);
}

Development quickstart

To view your first trace, you’ll need to set up a local collector. We’ll use Jaeger 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 the dependencies you’ll need

npm i @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-oltp-proto import-in-the-middle

Create src/instrumentation.server.ts with the following:

import { import NodeSDKNodeSDK } from '@opentelemetry/sdk-node';
import { import getNodeAutoInstrumentationsgetNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { import OTLPTraceExporterOTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { import createAddHookMessageChannelcreateAddHookMessageChannel } from 'import-in-the-middle';
import { function register<Data = any>(specifier: string | URL, parentURL?: string | URL, options?: Module.RegisterOptions<Data>): void (+1 overload)Register a module that exports hooks that customize Node.js module
resolution and loading behavior. See
Customization hooks.
@sincev20.6.0, v18.19.0
@paramspecifier Customization hooks to be registered; this should be
the same string that would be passed to import(), except that if it is
relative, it is resolved relative to parentURL.
@paramparentURL f you want to resolve specifier relative to a base
URL, such as import.meta.url, you can pass that URL here.register } from 'module';

const { const registerOptions: anyregisterOptions } = import createAddHookMessageChannelcreateAddHookMessageChannel();
register<any>(specifier: string | URL, parentURL?: string | URL, options?: Module.RegisterOptions<any> | undefined): void (+1 overload)Register a module that exports hooks that customize Node.js module
resolution and loading behavior. See
Customization hooks.
@sincev20.6.0, v18.19.0
@paramspecifier Customization hooks to be registered; this should be
the same string that would be passed to import(), except that if it is
relative, it is resolved relative to parentURL.
@paramparentURL f you want to resolve specifier relative to a base
URL, such as import.meta.url, you can pass that URL here.register('import-in-the-middle/hook.mjs', import.meta.ImportMeta.url: stringThe absolute file: URL of the module.
url, const registerOptions: anyregisterOptions);

const const sdk: anysdk = new import NodeSDKNodeSDK({
	serviceName: stringserviceName: 'test-sveltekit-tracing',
	traceExporter: anytraceExporter: new import OTLPTraceExporterOTLPTraceExporter(),
	instrumentations: any[]instrumentations: [import getNodeAutoInstrumentationsgetNodeAutoInstrumentations()]
});

const sdk: anysdk.start();

Any server-side requests will now begin generating traces, which you can view in Jaeger’s web console at localhost:16686.

Edit this page on GitHub llms.txt

previous next

Shallow routing Packaging