SvelteKitAdvanced

Observabilité

Disponible depuis la version 2.31

Parfois, vous pouvez avoir besoin d’observer comment se comporte votre application pour en améliorer les performances ou trouver la source d’un bug vicieux. Pour vous aider dans cette tâche, SvelteKit peut émettre des spans OpenTelemetry côté serveur dans les fonctions suivantes :

Le hook handle et les fonctions handle s’exécutant dans la fonction sequence (celles-ci sont des enfant l’une de l’autre et du hook racine handle)
Les fonctions load de serveur et les fonctions load universelles lorsqu’elles sont exécutées sur le serveur
Les actions de formulaire
Les fonctions distantes

Toutefois, vous ne serez pas très avancé•e•s en vous contentant de dire à SvelteKit d’émettre des spans — vous devez également les collecter quelque part pour être capables de les analyser. SvelteKit fournit le fichier src/instrumentation.server.ts comme emplacement pour écrire votre configuration de suivi ainsi que votre code d’instrumentation. Le code de ce fichier est garanti d’être exécuté avant que votre code applicatif ne soit importé, à condition que votre plateforme de déploiement le supporte et que votre adapteur soit conscient de son existence.

Ces deux fonctionnalités sont actuellement expérimentales, ce qui signifie qu’elles peuvent contenir des bugs et sont sujettes à des changements impromptus. Vous devez les activer en ajoutant les options kit.experimental.tracing.server et kit.experimental.instrumentation.server dans votre fichier svelte.config.js :

svelte.config

/** @type {import('@sveltejs/kit').Config} */
const const config: {
    kit: {
        experimental: {
 tracing: {
   server: boolean;
 };
 instrumentation: {
   server: boolean;
 };
        };
    };
}@type{import('@sveltejs/kit').Config}config = {
	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
			}
		}
	}
};

export default const config: {
    kit: {
        experimental: {
 tracing: {
   server: boolean;
 };
 instrumentation: {
   server: boolean;
 };
        };
    };
}@type{import('@sveltejs/kit').Config}config;

Le suivi — et de manière plus significative, l’instrumentation de l’observabilité — peuvent avoir un surcoût non négligeable. Avant de vous lancer tête baissée dans ce sujet, envisagez si vous en avez réellement besoin, ou s’il serait plus approprié de l’activer uniquement pour les environnements de développement et de prévisualisation.

Améliorer le suivi intégré

SvelteKit fournit un accès au span root et au span current dans l’évènement de requête. Le span racine est celui associé à votre fonction handle racine, et le span courant peut être associé à une fonction handle, load, une action de formulaire, ou une fonction distante, selon le contexte. Vous pouvez annoter ces spans avec n’importe quel attribut que vous souhaitez enregistrer :

$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);
}

Démarrage rapide pour le développement

Pour afficher votre première trace, vous devez mettre en place un collecteur local. Nous allons utiliser Jaeger dans cet exemple, puisqu’il fournit une commande de démarrage rapide simple à utiliser. Une fois que votre collecteur est en cours d’exécution localement :

Activez les flags expérimentaux mentionnés plus haut dans votre fichier svelte.config.js

Utilisez votre gestionnaire de paquet pour installer les dépendances dont vous aurez besoin :

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

Créez le fichier src/instrumentation.server.js avec le code suivant :

src/instrumentation.server

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 'node: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();

À partir de maintenant, les requêtes côté serveur vont générer des traces, que vous pouvez afficher dans la console web de Jaeger sur localhost:16686.

@opentelemetry/api

SvelteKit utilise @opentelemetry/api pour générer ses spans. Ce paquet est déclaré en tant que peerDependency optionnelle afin que les utilisateurs et utilisatrices ne nécessitant pas de suivi ne voient pas d’impact sur les tailles de bundle ou sur les performances d’exécution. Dans la plupart des cas, si vous configurez votre application pour collecter les spans de SvelteKit, vous finirez par installer une librairie comme @opentelemetry/sdk-node ou @vercel/otel, qui elles-mêmes dépendent de @opentelemetry/api, ce qui sera donc compatible avec les dépendances de SvelteKit. Si vous voyez une erreur venant de SvelteKit vous disant qu’il n’arrive pas à trouver @opentelemetry/api, il est possible que vous n’ayez pas encore mis en place votre suivi. Si vous l’avez fait et avez toujours l’erreur, vous pouvez installer le paquet @opentelemetry/api vous-même.

Modifier cette page sur Github llms.txt

précédent suivant

Shallow routing Packaging