# How to Configure Sentry for Error Tracking and Performance Monitoring in Kaneo

> Learn how to configure Sentry for error tracking and performance monitoring in Kaneo. Enable automatic error capture and distributed tracing with simple environment variables.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-06

---

**Kaneo provides optional Sentry integration out of the box—simply set a `SENTRY_DSN` environment variable to enable automatic error capture, then add a few settings to enable full performance monitoring with distributed tracing.**

Kaneo's API layer ships with built-in Sentry support that activates when environment variables are detected. This guide walks through configuring **Sentry error tracking and performance monitoring in Kaneo**, from basic setup to advanced tracing options, based on the actual implementation in the [`apps/api/src/instrument.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/instrument.ts) file.

## Prerequisites: Create a Sentry Project

Before configuring Kaneo, you need a Sentry project and DSN.

1. Log into Sentry and create a new project—select **Node.js** as the platform.
2. Copy the DSN (looks like `https://<public_key>@sentry.io/<project_id>`).
3. Keep this DSN handy for the next step.

## Basic Error Tracking Configuration

Kaneo requires only one environment variable to start capturing errors.

### Step 1: Add the Sentry DSN to Your Environment

Update your `.env` file or deployment environment:

```dotenv
SENTRY_DSN=https://<public_key>@sentry.io/<project_id>

```

With this variable present, Kaneo automatically initializes Sentry on API startup. The initialization code in [`apps/api/src/instrument.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/instrument.ts) checks for `SENTRY_DSN` and skips Sentry entirely if it's absent—making the integration truly optional.

### Step 2: Verify Error Capture

Test the integration by triggering an unhandled exception. Kaneo's `app.onError` handler in [`apps/api/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts) automatically forwards any uncaught errors to `Sentry.captureException`. Check your Sentry dashboard to confirm the error appears with full stack trace and context.

## Enabling Performance Monitoring and Tracing

Error tracking alone captures failures. To monitor request latency and trace performance bottlenecks, you need to extend the Sentry initialization with tracing options.

### Required Environment Variables

Add these variables to enable transaction tracing:

```dotenv
SENTRY_DSN=https://<public_key>@sentry.io/<project_id>
SENTRY_ENVIRONMENT=staging              # defaults to NODE_ENV or "production"

SENTRY_TRACES_SAMPLE_RATE=0.2          # 0-1 fraction of requests to trace

```

### Extended Initialization in [`apps/api/src/instrument.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/instrument.ts)

Replace or extend the default Sentry initialization with performance monitoring enabled:

```typescript
import * as Sentry from "@sentry/node";
import { Integrations } from "@sentry/node";

if (process.env.SENTRY_DSN) {
  Sentry.init({
    dsn: process.env.SENTRY_DSN,
    environment:
      process.env.SENTRY_ENVIRONMENT ?? process.env.NODE_ENV ?? "production",
    // Performance monitoring: trace a fraction of requests
    tracesSampleRate: Number(process.env.SENTRY_TRACES_SAMPLE_RATE) ?? 0,
    // Enable HTTP tracing to capture outgoing API calls
    integrations: [
      new Integrations.Http({ tracing: true }),
    ],
    sendDefaultPii: false,
  });
}

```

**Key parameters explained:**

- **`tracesSampleRate`** — Controls the percentage of requests that generate performance transactions. Start with `0.1` (10%) in production to balance insight with overhead.
- **`Http({ tracing: true })`** — Automatically wraps outgoing HTTP requests with spans, showing external API latency in your traces.
- **`sendDefaultPii: false`** — Keeps user data out of Sentry events by default; adjust based on your compliance requirements.

## How Kaneo Routes Errors to Sentry

The error capture pipeline works through two coordinated files:

- **[`apps/api/src/instrument.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/instrument.ts)** — Boots Sentry and configures global behavior.
- **[`apps/api/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts)** — Registers `app.onError` to capture uncaught exceptions and pass them to `Sentry.captureException`.

This separation keeps instrumentation concerns isolated from routing logic while ensuring no error goes unreported.

## Custom Transactions for Background Tasks

For long-running operations outside HTTP requests, manually create transactions:

```typescript
import * as Sentry from "@sentry/node";

export async function runReportGeneration() {
  const transaction = Sentry.startTransaction({
    op: "report.generate",
    name: "Monthly Analytics Report",
  });
  
  try {
    const data = await fetchRawData();
    const report = await compileReport(data);
    await sendReport(report);
  } catch (error) {
    Sentry.captureException(error);
    throw error;
  } finally {
    transaction.finish();
  }
}

```

This pattern surfaces performance of cron jobs, queue workers, or batch processing in the same Sentry dashboard as your API traces.

## Configuration Reference

| Variable | Required | Default | Purpose |
|----------|----------|---------|---------|
| `SENTRY_DSN` | Yes | — | Project identifier and ingest endpoint |
| `SENTRY_ENVIRONMENT` | No | `NODE_ENV` or `"production"` | Environment tag in Sentry UI |
| `SENTRY_TRACES_SAMPLE_RATE` | No | `0` | Fraction of requests traced (0.0–1.0) |

## Production Deployment Checklist

- [ ] Rotate DSN after initial testing (Sentry allows regenerating keys).
- [ ] Set `SENTRY_TRACES_SAMPLE_RATE` to `0.05` or lower for high-traffic APIs.
- [ ] Monitor Sentry quotas—transaction tracing consumes separate quota from errors.
- [ ] Verify `sendDefaultPii` matches your data privacy policy.

## Summary

- **Kaneo's Sentry integration** activates automatically when `SENTRY_DSN` is present in [`apps/api/src/instrument.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/instrument.ts).
- **Error tracking** requires one environment variable and captures all unhandled exceptions.
- **Performance monitoring** adds `SENTRY_TRACES_SAMPLE_RATE` and the HTTP integration for request-level tracing.
- **Custom transactions** extend visibility to background jobs using `Sentry.startTransaction`.

## Frequently Asked Questions

### What happens if I don't set `SENTRY_DSN`?

Kaneo skips Sentry initialization entirely. The API runs normally with no error reporting or performance overhead. Check [`apps/api/src/instrument.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/instrument.ts) for the conditional `if (process.env.SENTRY_DSN)` guard clause.

### Can I use a different error tracking service instead of Sentry?

Yes. The Sentry integration is optional and self-contained in [`instrument.ts`](https://github.com/usekaneo/kaneo/blob/main/instrument.ts). Replace the file's contents with your preferred SDK's initialization, or remove it and implement custom error handling in [`apps/api/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts).

### Why aren't my performance transactions appearing in Sentry?

Verify three things: `SENTRY_TRACES_SAMPLE_RATE` is set above `0`, the HTTP integration is included in the `integrations` array, and your Sentry project has Performance Monitoring enabled in plan settings. Also confirm you're using a compatible `@sentry/node` version.

### Does Sentry tracing impact API response times?

Minimal impact for most workloads. Sentry uses asynchronous span recording, and the sample rate lets you tune overhead. Start with 10% sampling (`0.1`) and monitor your p99 latency; increase or decrease based on observed behavior and Sentry quota usage.