The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
# Plugin Setup
Configure the Traceway Vue plugin with `createTracewayPlugin`.
## Basic Setup
```javascript
import { createApp } from "vue";
import { createTracewayPlugin } from "@tracewayapp/vue";
import App from "./App.vue";
const app = createApp(App);
app.use(createTracewayPlugin({
connectionString: "your-token@https://traceway.example.com/api/report",
}));
app.mount("#app");
```
## Plugin Options
| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `connectionString` | `string` | Yes | Your Traceway connection string |
| `options` | `object` | No | SDK configuration options |
## SDK Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `debug` | `boolean` | `false` | Log events to 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 |
## Full Example
```javascript
import { createApp } from "vue";
import { createTracewayPlugin } from "@tracewayapp/vue";
import App from "./App.vue";
const app = createApp(App);
app.use(createTracewayPlugin({
connectionString: "your-token@https://traceway.example.com/api/report",
options: {
debug: import.meta.env.DEV,
version: import.meta.env.VITE_APP_VERSION,
debounceMs: 1000,
},
}));
app.mount("#app");
```
## Capture All Errors
By default, 4xx HTTP errors, network errors, and timeouts are ignored. To capture everything:
```javascript
app.use(createTracewayPlugin({
connectionString: "your-token@https://traceway.example.com/api/report",
options: {
ignoreErrors: [],
},
}));
```
## Automatic Error Handling
The plugin automatically installs `app.config.errorHandler` to capture:
- Component rendering errors
- Watcher errors
- Lifecycle hook errors
```javascript
// This is handled automatically by the plugin:
app.config.errorHandler = (err, instance, info) => {
// Error is captured and sent to Traceway
};
```
Vue has a single `app.config.errorHandler` slot, and the plugin assigns it. If your app assigns its own handler after `app.use(createTracewayPlugin(...))`, it replaces Traceway's and component errors stop reaching the dashboard. To keep both, capture the error yourself inside your handler:
```javascript
import { captureException, captureMessage } from "@tracewayapp/vue";
app.use(createTracewayPlugin({
connectionString: "your-token@https://traceway.example.com/api/report",
}));
app.config.errorHandler = (err, instance, info) => {
if (err instanceof Error) {
captureException(err);
} else {
captureMessage(String(err));
}
myOwnErrorReporter(err, info);
};
```
## Environment-Specific Configuration
```javascript
const connectionString = import.meta.env.PROD
? import.meta.env.VITE_TRACEWAY_PROD
: import.meta.env.VITE_TRACEWAY_DEV;
app.use(createTracewayPlugin({
connectionString,
options: {
debug: import.meta.env.DEV,
},
}));
```
## Custom Attributes
Attach app-level identifiers (`userId`, `tenant`, feature flags, etc.) to every session and exception. The `useTracewayAttributes` composable is the Vue way to do it. Pass a getter and it tracks reactive state, pushes only the keys that changed, and removes the keys it owns when the component unmounts:
```vue
<script setup>
import { useTracewayAttributes } from "@tracewayapp/vue";
import { useUser } from "./auth";
const { user, org } = useUser();
useTracewayAttributes(() =>
user.value && org.value
? { userId: user.value.id, tenant: org.value.id }
: null
);
</script>
```
Return `null` when there is nothing to attach. The composable then removes the keys it had set.
There is a declarative wrapper for the same thing. It renders nothing and removes its keys on unmount:
```vue
<script setup>
import { TracewayAttributes } from "@tracewayapp/vue";
import { useUser } from "./auth";
const { user, org } = useUser();
</script>
<template>
<TracewayAttributes
v-if="user && org"
:attributes="{ userId: user.id, tenant: org.id }"
/>
</template>
```
Treat every key you pass to the composable or the component as owned by it. Do not set the same key with `setAttribute` elsewhere, because the unmount cleanup will remove it.
You can also drive the scope imperatively from `watchEffect`:
```vue
<script setup>
import { watchEffect } from "vue";
import { setAttributes, removeAttribute } from "@tracewayapp/vue";
import { useUser } from "./auth";
const { user, org } = useUser();
watchEffect(() => {
if (user.value && org.value) {
setAttributes({ userId: user.value.id, tenant: org.value.id });
} else {
removeAttribute("userId");
removeAttribute("tenant");
}
});
</script>
```
Use `removeAttribute` per key here rather than `clearAttributes()`. `clearAttributes()` empties the whole global scope, so it also drops keys set by other parts of the app.
The full API (`setAttribute`, `setAttributes`, `removeAttribute`, `clearAttributes`) is re-exported from `@tracewayapp/vue`. Layering on each event: **defaults < global scope < per-call**. See [Sessions](/learn/sessions) for the full attribute model.
## Manual Injection
For advanced use cases, you can use the injection key directly:
```vue
<script setup>
import { inject } from "vue";
import { TracewayKey } from "@tracewayapp/vue";
const traceway = inject(TracewayKey);
traceway.captureException(new Error("Manual capture"));
</script>
```
However, the `useTraceway` composable is preferred for most use cases.
## Vite Configuration
Add your connection string to `.env`:
```
VITE_TRACEWAY_CONNECTION=your-token@https://traceway.example.com/api/report
```
Use in your app:
```javascript
app.use(createTracewayPlugin({
connectionString: import.meta.env.VITE_TRACEWAY_CONNECTION,
}));
```
## Nuxt Integration
For Nuxt 3, create a plugin:
```javascript
// plugins/traceway.ts
import { createTracewayPlugin } from "@tracewayapp/vue";
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.use(createTracewayPlugin({
connectionString: useRuntimeConfig().public.tracewayConnection,
}));
});
```
Name the file `traceway.ts`, not `traceway.client.ts`. A `.client` plugin never runs during SSR, so the injection key is missing on the server and the first component calling `useTraceway()` fails the render with `useTraceway must be used within a Vue app that has installed the Traceway plugin` (HTTP 500). The plugin is safe to run universally: it only installs the browser handlers and the recorder when `window` exists, so the server pass just provides the injection key.
Add to `nuxt.config.ts`:
```typescript
export default defineNuxtConfig({
runtimeConfig: {
public: {
tracewayConnection: process.env.TRACEWAY_CONNECTION,
},
},
});
```