# Monitoring Overview

> Current monitoring behavior in the TanStack Start Drizzle SaaS Kit.

*Canonical: https://makerkit.dev/docs/tanstack-drizzle/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](./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](./custom-monitoring-provider)).

## Quick Start

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

```bash {% title="apps/web/.env.local" %}
VITE_MONITORING_PROVIDER=
```

## Manual Capture

Client-side:

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

```typescript
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](./custom-monitoring-provider) for the full pattern.

## Topics

1. [Custom Monitoring Provider](./custom-monitoring-provider)
2. [Capturing Errors](./capturing-errors)