Sentry Install & Auth

Overview

Install the Sentry SDK, configure DSN-based authentication, and verify error tracking is operational. Covers Node.js (

@sentry/node

@sentry/browser

sentry-sdk

Prerequisites

• Node.js 18.19+ or 20.6+ (required for ESM support in Sentry SDK v8)
• Package manager: npm, pnpm, or pip
• Sentry account with a project created at https://sentry.io
• DSN from Project Settings > Client Keys (DSN)
• For CLI/CI: auth token from https://sentry.io/settings/auth-tokens/

Instructions

Step 1 — Install the SDK

Node.js / TypeScript:

npm install @sentry/node
# For profiling support (optional):
npm install @sentry/profiling-node

Browser / Framework-specific:

npm install @sentry/browser
# Or pick your framework:
npm install @sentry/react    # React
npm install @sentry/nextjs   # Next.js
npm install @sentry/vue      # Vue

Python:

pip install sentry-sdk

Step 2 — Store the DSN securely

The DSN (Data Source Name) tells the SDK where to send events. It looks like

https://<key>@<org>.ingest.sentry.io/<project-id>

# .env (add this file to .gitignore)
SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0
SENTRY_ENVIRONMENT=development
SENTRY_RELEASE=1.0.0

For production, store the DSN in your secret manager (AWS Secrets Manager, GCP Secret Manager, Vault, etc.) and inject it at deploy time.

Step 3 — Initialize the SDK

Node.js (ESM) — create

instrument.mjs

This file MUST be imported before any other modules. The

--import

// instrument.mjs — import BEFORE your app code
import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.SENTRY_ENVIRONMENT || 'development',
  release: process.env.SENTRY_RELEASE,

  // Performance: 100% in dev, 10-20% in production
  tracesSampleRate: process.env.NODE_ENV === 'production' ? 0.1 : 1.0,

  // Debug mode — disable in production
  debug: process.env.NODE_ENV !== 'production',

  // Never send PII by default
  sendDefaultPii: false,

  integrations: [
    // Built-in integrations (httpIntegration, expressIntegration)
    // are auto-detected — no manual registration needed
  ],
});

Start your app with the

--import

node --import ./instrument.mjs app.mjs

Or in

package.json

{
  "scripts": {
    "start": "node --import ./instrument.mjs app.mjs"
  }
}

Browser:

import * as Sentry from '@sentry/browser';

Sentry.init({
  dsn: process.env.SENTRY_DSN, // injected at build time
  environment: process.env.NODE_ENV,
  release: process.env.SENTRY_RELEASE,
  tracesSampleRate: 0.1,
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.replayIntegration(),
  ],
});

Python:

import os
import sentry_sdk

sentry_sdk.init(
    dsn=os.environ.get("SENTRY_DSN"),
    environment=os.environ.get("SENTRY_ENVIRONMENT", "development"),
    release=os.environ.get("SENTRY_RELEASE"),
    traces_sample_rate=0.1,
    send_default_pii=False,
)

Step 4 — Verify the installation

Send a test event and confirm it appears in the Sentry dashboard:

Node.js:

import * as Sentry from '@sentry/node';

Sentry.captureMessage('Sentry SDK installed successfully', 'info');

// Ensure the event is flushed before process exits
await Sentry.flush(2000);

Python:

import sentry_sdk

sentry_sdk.capture_message("Sentry SDK installed successfully")

# Ensure the event is flushed
sentry_sdk.flush(timeout=2)

Check the Issues tab in your Sentry project within 30 seconds. If the message appears, authentication is working.

Step 5 — Set up auth token for CLI and CI

The DSN authenticates the SDK for sending events. For the Sentry CLI (source maps, releases, deploys), you need a separate auth token.

Generate one at https://sentry.io/settings/auth-tokens/ with scopes:

• project:releases

  — create releases and upload source maps

• org:read

  — read organization data

# Install Sentry CLI
npm install -g @sentry/cli

# Set the token
export SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE

# Verify auth works
sentry-cli info

In CI, store

SENTRY_AUTH_TOKEN

Output

• SDK package installed (

  @sentry/node

  ,

  @sentry/browser

  , or

  sentry-sdk

  )
• DSN stored in environment variables (never committed to git)

• instrument.mjs

  created and loaded before app entry point (Node.js)
• Sentry initialized with environment, release, and sample rates configured
• Test event visible in Sentry dashboard confirming DSN auth works
• Auth token configured for CLI/CI workflows (optional)

Error Handling

Invalid Sentry Dsn

https://<key>@<org>.ingest.sentry.io/<project-id>

console.log(process.env.SENTRY_DSN)

Sentry.init()

.env

dotenv

sentry-cli info

tracesSampleRate

Express is not instrumented

import './instrument.mjs'

--import

project:releases

org:read

ECONNREFUSED

*.ingest.sentry.io

--import

Examples

Express.js with full error handler:

// instrument.mjs
import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.SENTRY_ENVIRONMENT || 'development',
  tracesSampleRate: 0.2,
});

// app.mjs — start with: node --import ./instrument.mjs app.mjs
import * as Sentry from '@sentry/node';
import express from 'express';

const app = express();

app.get('/api/health', (req, res) => {
  res.json({ status: 'ok' });
});

app.get('/api/debug-sentry', (req, res) => {
  throw new Error('Sentry test error');
});

// Sentry error handler must be registered after all routes
Sentry.setupExpressErrorHandler(app);

// Fallback error handler
app.use((err, req, res, next) => {
  res.status(500).json({ error: 'Internal server error' });
});

app.listen(3000, () => console.log('Server running on :3000'));

Python Flask:

import os
import sentry_sdk
from flask import Flask

sentry_sdk.init(
    dsn=os.environ.get("SENTRY_DSN"),
    environment=os.environ.get("SENTRY_ENVIRONMENT", "development"),
    traces_sample_rate=0.2,
    send_default_pii=False,
)

app = Flask(__name__)

@app.route("/api/health")
def health():
    return {"status": "ok"}

@app.route("/api/debug-sentry")
def debug_sentry():
    raise Exception("Sentry test error")  # Automatically captured

Graceful shutdown with flush:

import * as Sentry from '@sentry/node';

process.on('SIGTERM', async () => {
  console.log('Shutting down gracefully...');
  await Sentry.flush(5000); // wait up to 5s for pending events
  process.exit(0);
});

Resources

• Node.js Setup Guide
• Browser SDK Setup
• Python SDK Setup
• Configuration Options
• SDK Migration v7 to v8
• Auth Tokens
• Sentry Status Page

Next Steps

For configuring alerts and issue management, see

sentry-alerts-config