<blockquote class="since note">
	<p>Disponible depuis la version 2.31</p>
</blockquote>

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](https://opentelemetry.io) côté serveur dans les fonctions
suivantes :

- Le hook [`handle`](hooks#Server-hooks-handle) et les fonctions `handle` s'exécutant dans la
fonction [`sequence`](@sveltejs-kit-hooks#sequence) (celles-ci sont des enfant l'une de l'autre et
du hook racine `handle`)
- Les fonctions [`load`](load) de serveur et les fonctions `load` universelles lorsqu'elles sont
exécutées sur le serveur
- Les [actions de formulaire](form-actions)
- Les [fonctions distantes](remote-functions)

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` :

```js
/// file: svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const config = {
	kit: {
		experimental: {
			+++tracing: {
				server: true
			},
			instrumentation: {
				server: true
			}+++
		}
	}
};

export default config;
```

> [!NOTE] 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é [!VO]Augmenting the built-in tracing

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
:

```js
/// file: $lib/authenticate.ts

// @filename: ambient.d.ts
declare module '$lib/auth-core' {
	export function getAuthenticatedUser(): Promise<{ id: string }>
}

// @filename: index.js
// ---cut---
import { getRequestEvent } from '$app/server';
import { getAuthenticatedUser } from '$lib/auth-core';

async function authenticate() {
	const user = await getAuthenticatedUser();
	const event = getRequestEvent();
	event.tracing.root.setAttribute('userId', user.id);
}
```

## Démarrage rapide pour le développement [!VO]Development quickstart

Pour afficher votre première trace, vous devez mettre en place un collecteur local. Nous allons
utiliser [Jaeger](https://www.jaegertracing.io/docs/getting-started/) 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 :
  ```sh
  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 :

```js
/// file: src/instrumentation.server.js
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 'node: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();
```

À 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](http://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.