The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
# Context Setup
Understanding Traceway's Svelte context integration.
## How It Works
Traceway uses Svelte's context API to provide error capture functions to your component tree:
1. `setupTraceway()` initializes the SDK and sets context
2. `getTraceway()` retrieves the context in child components
## setupTraceway
Must be called during component initialization (not in an event handler):
```svelte
<script>
import { setupTraceway } from "@tracewayapp/svelte";
// Correct: called at component initialization
setupTraceway({
connectionString: "your-token@https://traceway.example.com/api/report",
});
</script>
```
**Initialization is synchronous:** `setupTraceway` calls the SDK's `init()` immediately, during component setup, not in `onMount`. Everything captured after that point is recorded, including captures in a child component's setup code that runs before `onMount`. There is no pre-init buffer, so a capture made before `setupTraceway` runs is dropped.
### Options
| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `connectionString` | `string` | Yes | Your Traceway connection string |
| `options` | `object` | No | SDK configuration |
### SDK Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `debug` | `boolean` | `false` | Log filtered-out exceptions and failed uploads to the console |
| `debounceMs` | `number` | `1500` | Batch delay in milliseconds |
| `retryDelayMs` | `number` | `10000` | Retry delay for failed uploads |
| `version` | `string` | `undefined` | Your application version |
| `ignoreErrors` | `Array<string \| RegExp>` | `DEFAULT_IGNORE_PATTERNS` | Error patterns to ignore. Pass `[]` to capture all errors. See [Error Filtering](/client/js-sdk/initialization#error-filtering) |
| `beforeCapture` | `(exception) => boolean` | `undefined` | Return `false` to suppress an error. See [Error Filtering](/client/js-sdk/initialization#error-filtering) |
| `sessionRecording` | `boolean` | `true` | Enable the rrweb session recorder |
| `sessionRecordingSegmentDuration` | `number` | `30000` | rrweb segment length in ms |
| `recordAllSessions` | `boolean` | `false` | Always-on session recording. See [Sessions](/learn/sessions) |
| `captureLogs` | `boolean` | `true` | Mirror `console.*` calls into the rolling log buffer |
| `captureNetwork` | `boolean` | `true` | Record `fetch` / `XHR` calls as network actions |
| `captureNavigation` | `boolean` | `true` | Record History API push / replace / pop transitions |
## getTraceway
Retrieve capture functions in any child component:
```svelte
<script>
import { getTraceway } from "@tracewayapp/svelte";
const { captureException, captureExceptionWithAttributes, captureMessage } = getTraceway();
</script>
```
### Return Value
| Function | Description |
|----------|-------------|
| `captureException(error)` | Capture an error with stack trace |
| `captureExceptionWithAttributes(error, attributes)` | Capture error with metadata |
| `captureMessage(message)` | Send a custom message |
| `recordAction(category, name, data)` | Record an action into the rolling buffer that ships with the next exception |
## Complete Example
Root layout:
```svelte
<!-- src/routes/+layout.svelte -->
<script>
import { setupTraceway } from "@tracewayapp/svelte";
import { PUBLIC_TRACEWAY_CONNECTION } from "$env/static/public";
setupTraceway({
connectionString: PUBLIC_TRACEWAY_CONNECTION,
options: {
debug: import.meta.env.DEV,
},
});
</script>
<slot />
```
Child component:
```svelte
<!-- src/lib/components/Form.svelte -->
<script>
import { getTraceway } from "@tracewayapp/svelte";
const { captureException, captureExceptionWithAttributes } = getTraceway();
let formData = { email: "", name: "" };
async function handleSubmit() {
try {
const response = await fetch("/api/submit", {
method: "POST",
body: JSON.stringify(formData),
});
if (!response.ok) throw new Error("Submission failed");
} catch (error) {
captureExceptionWithAttributes(error, {
email: formData.email,
action: "form_submit",
});
}
}
</script>
<form on:submit|preventDefault={handleSubmit}>
<input bind:value={formData.name} placeholder="Name" />
<input bind:value={formData.email} placeholder="Email" />
<button type="submit">Submit</button>
</form>
```
## Custom Attributes
Use `useTracewayAttributes` to bind a reactive map of attributes (`userId`, `tenant`, feature flags, etc.) to the SDK's global scope. It's a factory: call it once during component setup, then invoke the returned setter from `$effect` (Svelte 5) or `$:` (Svelte 4). The setter diffs against the last map and pushes only the deltas; `onDestroy` removes every key it currently owns.
```svelte
<!-- Svelte 5 -->
<script>
import { useTracewayAttributes } from "@tracewayapp/svelte";
let { user, org } = $props();
const sync = useTracewayAttributes();
$effect(() => sync({ userId: user.id, tenant: org.id }));
</script>
```
```svelte
<!-- Svelte 4 -->
<script>
import { useTracewayAttributes } from "@tracewayapp/svelte";
export let user; export let org;
const sync = useTracewayAttributes();
$: sync({ userId: user.id, tenant: org.id });
</script>
```
The setter accepts `null` / `undefined` as "empty map", which is useful while user data loads or after logout.
For imperative use (load functions, hooks), the same primitives are exported as plain functions:
```javascript
import { setAttribute, setAttributes, removeAttribute, clearAttributes } from "@tracewayapp/svelte";
setAttribute("build_channel", "canary");
setAttributes({ tenant: "acme", plan: "pro" });
clearAttributes(); // on logout
```
Layering on each event: **defaults < global scope < per-call**. See [Sessions](/learn/sessions) for the full attribute model.
## TRACEWAY_KEY
For advanced use cases, you can access the context key directly:
```svelte
<script>
import { getContext } from "svelte";
import { TRACEWAY_KEY } from "@tracewayapp/svelte";
const traceway = getContext(TRACEWAY_KEY);
</script>
```
## SvelteKit Error Handling
`handleError` in `src/hooks.client.js` is where SvelteKit hands you the real error from a failed `load` or a render crash during client-side navigation. Svelte context is not available in a hook, so import the capture function directly. It is the same function `getTraceway()` returns.
```javascript
// src/hooks.client.js
import { captureExceptionWithAttributes } from "@tracewayapp/svelte";
export function handleError({ error, event }) {
captureExceptionWithAttributes(error, {
route: event.route?.id ?? event.url.pathname,
});
return { message: "Something went wrong" };
}
```
Do not capture from `+error.svelte`. That page only receives `$page.error`, which SvelteKit has already reduced to a plain `{ message }` object. Passing it to `captureException` produces an issue titled `Object: Internal Error` with no stack trace and no original message. Use the page for display and let `handleError` do the reporting.
```svelte
<!-- src/routes/+error.svelte -->
<script>
import { page } from "$app/stores";
</script>
<h1>Error: {$page.status}</h1>
<p>{$page.error?.message}</p>
```
### Render Errors (Svelte 5)
Svelte 5's `<svelte:boundary>` catches errors thrown while its children render. Pass `captureSvelteError` as `onerror` to report them:
```svelte
<script>
import { captureSvelteError } from "@tracewayapp/svelte";
import Widget from "$lib/components/Widget.svelte";
</script>
<svelte:boundary onerror={captureSvelteError}>
<Widget />
{#snippet failed(error)}
<p>Something went wrong: {error.message}</p>
{/snippet}
</svelte:boundary>
```
## Environment Variables
For SvelteKit, use public environment variables:
```
# .env
PUBLIC_TRACEWAY_CONNECTION=your-token@https://traceway.example.com/api/report
```
```svelte
<script>
import { PUBLIC_TRACEWAY_CONNECTION } from "$env/static/public";
setupTraceway({
connectionString: PUBLIC_TRACEWAY_CONNECTION,
});
</script>
```
## Best Practices
1. **Initialize early**: Call `setupTraceway` in your root layout
2. **Skip the browser guard**: `setupTraceway` must also run during SSR, or `getTraceway()` throws in child components
3. **Use attributes**: Add context with `captureExceptionWithAttributes`
4. **Handle gracefully**: Show user-friendly errors while capturing details
```svelte
<script>
import { getTraceway } from "@tracewayapp/svelte";
const { captureException } = getTraceway();
let error = null;
async function loadData() {
try {
const data = await fetchData();
// use data
} catch (e) {
captureException(e);
error = "Failed to load data. Please try again.";
}
}
</script>
{#if error}
<p class="error">{error}</p>
{/if}
```