Skip to content

Commit 96d0b78

Browse files
Lms24nicohrubec
andauthored
feat(sveltekit): Document new wrapServerRouteWithSentry wrapper (#10990)
adds documentation for the new `wrapServerRouteWithSentry` function we added in getsentry/sentry-javascript#13247. --------- Co-authored-by: Nicolas Hrubec <nicolas.hrubec@outlook.com>
1 parent 708eeac commit 96d0b78

File tree

1 file changed

+69
-35
lines changed

1 file changed

+69
-35
lines changed

docs/platforms/javascript/guides/sveltekit/manual-setup.mdx

Lines changed: 69 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -328,7 +328,7 @@ export default {
328328

329329
If you disable automatic source maps upload, you must explicitly set a `release` value in your `Sentry.init()` configs. You can also skip the `sentry-cli` configuration step below.
330330

331-
### Configure Auto-Instrumentation
331+
### Auto-Instrumentation
332332

333333
The SDK primarily uses [SvelteKit's hooks](https://kit.svelte.dev/docs/hooks) to collect error and performance data. However, SvelteKit doesn't yet offer a hook for universal or server-only `load` function calls. Therefore, the SDK uses a Vite plugin to auto-instrument `load` functions so that you don't have to add a Sentry wrapper to each function manually.
334334

@@ -415,9 +415,59 @@ export default {
415415
};
416416
```
417417

418-
#### Instrument `load` Functions Manually
418+
#### Configure Client-side `fetch` Instrumentation
419+
420+
<Note>
421+
422+
Available since version `7.91.0`
423+
424+
</Note>
425+
426+
The `sentryHandle` function you added to your `handle` hook in `hooks.server.ts` during [server-side setup](#server-side-setup) injects an inline `<script>` tag into the HTML response of the server.
427+
This script attempts to proxy all client-side `fetch` calls, so that `fetch` calls inside your `load` functions are captured by the SDK.
428+
However, if you configured CSP rules to block inline fetch scripts by default, this script will be [blocked by the browser](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src#unsafe_inline_script).
429+
To enable the script, you need to add an exception for the `sentryHandle` script:
430+
431+
First, specify your nonce in the `fetchProxyScriptNonce` option in your `sentryHandle` call:
432+
433+
```javascript {filename:hooks.server.ts}
434+
// Add the nonce to the <script> tag:
435+
export const handle = sentryHandle({ fetchProxyScriptNonce: "<your-nonce>" });
436+
```
437+
438+
Then, adjust your [SvelteKit CSP configuration](https://kit.svelte.dev/docs/configuration#csp):
419439

420-
If you don't want to use auto-instrumentation, you can also manually instrument specific `load` functions with the SDK's `load` function wrappers.
440+
```javascript {svelte.config.js} {5}
441+
const config = {
442+
kit: {
443+
csp: {
444+
directives: {
445+
"script-src": ["nonce-<your-nonce>"],
446+
},
447+
},
448+
},
449+
};
450+
```
451+
452+
##### Disable Client-side `fetch` Proxy Script
453+
454+
If you do not want to inject the script responsible for instrumenting client-side `load` calls, you can disable injection by passing `injectFetchProxyScript: false` to `sentryHandle`:
455+
456+
```javascript {filename:hooks.server.ts}
457+
export const handle = sentryHandle({ injectFetchProxyScript: false });
458+
```
459+
460+
Note that if you disable the `fetch` proxy script, the SDK will not be able to capture spans for `fetch` calls made in your `load` functions on the client.
461+
This also means that potential spans created on the server for these `fetch` calls will not be connected to the client-side trace.
462+
463+
### Manual Instrumentation
464+
465+
Instead or in addition to [Auto Instrumentation](#auto-instrumentation), you can manually instrument certain SvelteKit-specific features with the SDK:
466+
467+
#### Instrument `load` Functions
468+
469+
SvelteKit's universal and server `load` functions are instrumented automatically by default.
470+
If you don't want to use `load` auto-instrumentation, you can [disable it](#disable-auto-instrumentation), and manually instrument specific `load` functions with the SDK's `load` function wrappers.
421471

422472
##### Universal `load` Functions
423473

@@ -467,47 +517,31 @@ export const load = wrapServerLoadWithSentry(({ event }) => {
467517
});
468518
```
469519

470-
#### Configure Client-side `fetch` Instrumentation
520+
#### Instrument Server Routes
471521

472522
<Note>
473523

474-
Available since version `7.91.0`
524+
Available since `8.25.0`
475525

476526
</Note>
477527

478-
The `sentryHandle` function you added to your `handle` hook in `hooks.server.ts` during [server-side setup](#server-side-setup) injects a small inline `<script>` tag into the HTML response of the server.
479-
This script attempts to proxy all client-side `fetch` calls, so that `fetch` calls inside your `load` functions are captured by the SDK.
480-
However, if you configured CSP rules to block inline fetch scripts by default, this script will be [blocked by the browser](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src#unsafe_inline_script).
481-
To enable the script, you need to add an exception for the `sentryHandle` script:
482-
483-
First, specify your nonce in the `fetchProxyScriptNonce` option in your `sentryHandle` call:
484-
485-
```javascript {filename:hooks.server.ts}
486-
// Add the nonce to the <script> tag:
487-
export const handle = sentryHandle({ fetchProxyScriptNonce: "<your-nonce>" });
488-
```
528+
You can also manually instrument [server (API) routes ](https://kit.svelte.dev/docs/routing#server) with the SDK.
529+
This is useful if you have custom server routes that you want to trace or if you want to capture `error()` calls within your server routes:
489530

490-
Then, adjust your [SvelteKit CSP configuration](https://kit.svelte.dev/docs/configuration#csp):
531+
```javascript {filename:+server.js} {1,3}
532+
import { wrapServerRouteWithSentry } from "@sentry/sveltekit";
491533

492-
```javascript {svelte.config.js} {5}
493-
const config = {
494-
kit: {
495-
csp: {
496-
directives: {
497-
"script-src": ["nonce-<your-nonce>"],
498-
},
499-
},
500-
},
501-
};
534+
export const GET = wrapServerRouteWithSentry(async () => {
535+
// your endpoint logic
536+
return new Response("Hello World");
537+
});
502538
```
503539

504-
##### Disable Client-side `fetch` Proxy Script
505-
506-
If you do not want to inject the script responsible for instrumenting client-side `load` calls, you can disable injection by passing `injectFetchProxyScript: false` to `sentryHandle`:
540+
```typescript {filename:+server.ts} {1,3}
541+
import { wrapServerRouteWithSentry } from "@sentry/sveltekit";
507542

508-
```javascript {filename:hooks.server.ts}
509-
export const handle = sentryHandle({ injectFetchProxyScript: false });
543+
export const GET = wrapServerRouteWithSentry(async () => {
544+
// your endpoint logic
545+
return new Response("Hello World");
546+
});
510547
```
511-
512-
Note that if you disable the `fetch` proxy script, the SDK will not be able to capture spans for `fetch` calls made in your `load` functions on the client.
513-
This also means that potential spans created on the server for these `fetch` calls will not be connected to the client-side trace.

0 commit comments

Comments
 (0)