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

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

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

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

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

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 — Boots Sentry and configures global behavior.
• 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:

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.
• 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 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. 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}