Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(sveltekit): Document new wrapServerRouteWithSentry wrapper #10990

Merged
merged 3 commits into from
Aug 9, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 69 additions & 35 deletions docs/platforms/javascript/guides/sveltekit/manual-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -328,7 +328,7 @@ export default {

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.

### Configure Auto-Instrumentation
### Auto-Instrumentation

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.

Expand Down Expand Up @@ -415,9 +415,59 @@ export default {
};
```

#### Instrument `load` Functions Manually
#### Configure Client-side `fetch` Instrumentation

<Note>

Available since version `7.91.0`

</Note>

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.
This script attempts to proxy all client-side `fetch` calls, so that `fetch` calls inside your `load` functions are captured by the SDK.
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).
To enable the script, you need to add an exception for the `sentryHandle` script:

First, specify your nonce in the `fetchProxyScriptNonce` option in your `sentryHandle` call:

```javascript {filename:hooks.server.ts}
// Add the nonce to the <script> tag:
export const handle = sentryHandle({ fetchProxyScriptNonce: "<your-nonce>" });
```

Then, adjust your [SvelteKit CSP configuration](https://kit.svelte.dev/docs/configuration#csp):

If you don't want to use auto-instrumentation, you can also manually instrument specific `load` functions with the SDK's `load` function wrappers.
```javascript {svelte.config.js} {5}
const config = {
kit: {
csp: {
directives: {
"script-src": ["nonce-<your-nonce>"],
},
},
},
};
```

##### Disable Client-side `fetch` Proxy Script

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

```javascript {filename:hooks.server.ts}
export const handle = sentryHandle({ injectFetchProxyScript: false });
```

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.
This also means that potential spans created on the server for these `fetch` calls will not be connected to the client-side trace.

### Manual Instrumentation

Instead or in addition to [Auto Instrumentation](#auto-instrumentation), you can manually instrument certain SvelteKit-specific features with the SDK:

#### Instrument `load` Functions

SvelteKit's universal and server `load` functions are instrumented automatically by default.
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.

##### Universal `load` Functions

Expand Down Expand Up @@ -467,47 +517,31 @@ export const load = wrapServerLoadWithSentry(({ event }) => {
});
```

#### Configure Client-side `fetch` Instrumentation
#### Instrument Server Routes

<Note>

Available since version `7.91.0`
Available since `8.25.0`

</Note>

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.
This script attempts to proxy all client-side `fetch` calls, so that `fetch` calls inside your `load` functions are captured by the SDK.
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).
To enable the script, you need to add an exception for the `sentryHandle` script:

First, specify your nonce in the `fetchProxyScriptNonce` option in your `sentryHandle` call:

```javascript {filename:hooks.server.ts}
// Add the nonce to the <script> tag:
export const handle = sentryHandle({ fetchProxyScriptNonce: "<your-nonce>" });
```
You can also manually instrument [server (API) routes ](https://kit.svelte.dev/docs/routing#server) with the SDK.
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:

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

```javascript {svelte.config.js} {5}
const config = {
kit: {
csp: {
directives: {
"script-src": ["nonce-<your-nonce>"],
},
},
},
};
export const GET = wrapServerRouteWithSentry(async () => {
// your endpoint logic
return new Response("Hello World");
});
```

##### Disable Client-side `fetch` Proxy Script

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`:
```typescript {filename:+server.ts} {1,3}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this duplicated for ts and js?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

because you can use JS and TS simultaneously in SvelteKit. But most of these snippets have no TS-specific syntax, so it might be better to switch to a shared filename.(js|ts) snippet

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm realizing, we're a bit inconsistent with the languages and even diverge a bit. I'll dedupe the snippets.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Opened an additional PR because I streamlined some other things while removing the TS stuff: #11038

import { wrapServerRouteWithSentry } from "@sentry/sveltekit";

```javascript {filename:hooks.server.ts}
export const handle = sentryHandle({ injectFetchProxyScript: false });
export const GET = wrapServerRouteWithSentry(async () => {
// your endpoint logic
return new Response("Hello World");
});
```

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.
This also means that potential spans created on the server for these `fetch` calls will not be connected to the client-side trace.
Loading