Monitoring Overview

The monitoring layer in this repo is extensible, but no third-party provider ships by default. Out of the box the kit uses a console/null fallback; bring your own provider to enable real reporting.

Current State

• @kit/monitoring-core provides the base service types and console fallback
• @kit/monitoring provides provider selection, hooks, server helpers, and the instrumentation entrypoints
• No concrete provider is registered in the repo by default
• If VITE_MONITORING_PROVIDER is unset, the app falls back to console logging

Note: The monitoring packages expose a server onRequestError contract. The env vars, provider selection, hooks, and server helpers below are wired for TanStack Start.

Architecture

Errors enter monitoring through three paths, each provider-agnostic:

• Server instrumentation — registerMonitoringInstrumentation() from @kit/monitoring/instrumentation initializes the provider on boot. It also exports onRequestError, which forwards request-lifecycle errors to the configured provider. Call these from your server entrypoint (apps/web/src/start.ts / nitro startup).
• Client instrumentation — registerClientMonitoringInstrumentation() from @kit/monitoring/instrumentation-client installs the kit's own window.onerror and unhandledrejection handlers, lazily loads the provider chunk in parallel with hydration, and buffers any errors that fire before init resolves. Call it from your client entry/root.
• useCaptureException / useMonitoring / getServerMonitoringService — manual capture from your code (see Capturing Errors).

Dedup invariant

Errors that originated server-side are recorded once by the provider's onRequestError instrumentation. When you also surface such an error in a route errorComponent, pass null to useCaptureException for already-reported errors so you don't double-report. Custom providers must keep honoring this contract.

Capturing outside the provider tree

A root-level error boundary may render outside the React MonitoringContext (no useMonitoring available). Use captureClientException from @kit/monitoring/instrumentation-client in that shell.

Supported Provider Values

Current runtime support:

• empty / unset value for the console/null fallback

No third-party provider names are registered by default in this repository. To enable one, register it yourself (see Custom Monitoring Provider).

Quick Start

By default no provider is configured and the console fallback is used. Leave the env var empty:

VITE_MONITORING_PROVIDER=

Manual Capture

Client-side:

import { useMonitoring } from '@kit/monitoring/hooks';
function MyComponent() {
  const monitoring = useMonitoring();
  async function onSubmit() {
    try {
      await submitForm();
    } catch (error) {
      monitoring.captureException(error as Error, {
        context: 'form_submission',
      });
    }
  }
}

Server-side:

import { getServerMonitoringService } from '@kit/monitoring/server';
export async function processPayment() {
  const monitoring = await getServerMonitoringService();
  try {
    // ...
  } catch (error) {
    await monitoring.captureException(error as Error);
    throw error;
  }
}

Extending Monitoring

You can add more providers, but they are not prewired in this repo. A new provider requires registration in the client provider component, the server service, and both instrumentation registries (client + server). See Custom Monitoring Provider for the full pattern.

Topics

1. Custom Monitoring Provider
2. Capturing Errors