Error Tracking

Browser errors are reported by the web SDK. Server errors in Nitro routes are reported by @faststats/nitro.

Browser Errors

Turn on errorTracking.enabled to capture uncaught errors and unhandled promise rejections. The tracker batches them and drops noise from browser extensions automatically.

<Analytics siteKey="your_site_key" errorTracking={{ enabled: true }} />

nuxt.config.ts

faststats: {
	siteKey: "your_site_key",
	errorTracking: { enabled: true },
}

new WebAnalytics({
	siteKey: "your_site_key",
	errorTracking: { enabled: true },
});

Errors are grouped by their type and message so the same error from many visitors does not flood your dashboard. Identical errors within a batch are counted instead of repeated.

Report Errors by Hand

When you catch an error yourself you can still send it with reportError. This only works when errorTracking.enabled is true.

import { reportError } from "@faststats/web";

try {
	doRiskyThing();
} catch (error) {
	reportError(error as Error);
}

In Nuxt the module already hooks into the Vue error handler, so component errors are reported without extra code.

Server Errors with Nitro

If you run Nitro, either standalone or through Nuxt, you can report errors thrown in server routes with @faststats/nitro. The package ships a plugin for Nitro v2 and one for Nitro v3.

npm npm install @faststats/nitro

nuxt.config.ts

import { createRequire } from "node:module";

const require = createRequire(import.meta.url);
const errorTrackingPlugin = require.resolve("@faststats/nitro/v2");

export default defineNuxtConfig({
	nitro: {
		plugins: [errorTrackingPlugin],
	},
});

nitro.config.ts

export default defineNitroConfig({
	plugins: ["@faststats/nitro/v2"],
});

Use the /v3 import instead when you are on Nitro v3.

Server Configuration

The server plugin reads its settings from environment variables. The token is a project token, not the browser site key, so keep it on the server only.

Variable	Default	Description
`FASTSTATS_TOKEN`	required	Project token used to authorize reports
`FASTSTATS_ERROR_ENDPOINT`	`https://metrics.faststats.dev/v1/error`	Where server errors are sent
`FASTSTATS_BUILD_ID`	none	Tags errors with a build for source maps
`FASTSTATS_DEBUG`	`0`	Set to `1` to log reporter activity

.env

FASTSTATS_TOKEN=your_project_token

If FASTSTATS_TOKEN is not set the plugin stays silent and skips reporting, so it is safe to leave installed in environments without a token.

Custom Configuration

You can also create a plugin with explicit options instead of environment variables. This lets you attach extra context to every error.

server/plugins/faststats.ts

import { createFaststatsNitroPluginV2 } from "@faststats/nitro/v2";

export default createFaststatsNitroPluginV2({
	token: process.env.FASTSTATS_TOKEN,
	getContext: ({ path }) => ({ route: path }),
});

The reporter batches errors, retries failed sends and opens a short circuit breaker after repeated failures so a broken endpoint never slows your server down.