sentry-install-auth

Sentry Install & Auth

Overview

Install the Sentry SDK, configure DSN-based authentication, and verify error tracking is operational. Covers Node.js (@sentry/node), browser (@sentry/browser), and Python (sentry-sdk) with environment-based configuration and auth token setup for CLI/CI workflows.

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>. Never hardcode it — use environment variables.

# .env (add this file to .gitignore)
SENTRY_DSN=https://[email protected]/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 at project root:

This file MUST be imported before any other modules. The --import flag ensures Sentry instruments HTTP, database, and framework integrations via monkey-patching at load time.

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

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 as a secret environment variable.

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

Error	Cause	Solution
Invalid Sentry Dsn	Malformed DSN string	Copy DSN exactly from Project Settings > Client Keys (DSN). Format: https://<key>@<org>.ingest.sentry.io/<project-id>
Events not appearing in dashboard	DSN env var not loaded	Verify with console.log(process.env.SENTRY_DSN) before Sentry.init(). Check .env is loaded (use dotenv or framework equivalent)
HTTP 401 Unauthorized	Invalid or revoked auth token	Regenerate token at https://sentry.io/settings/auth-tokens/. Verify with sentry-cli info
HTTP 429 Too Many Requests	Rate-limited by Sentry	Lower tracesSampleRate. Check quota at Settings > Subscription. Events are dropped, not queued
Express is not instrumented	SDK initialized after Express import	Move import './instrument.mjs' to first line or use --import flag. SDK must load before any framework imports
HTTP 403 Forbidden	Auth token missing required scopes	Regenerate token with project:releases and org:read scopes
ECONNREFUSED / network errors	Sentry ingest endpoint unreachable	Check https://status.sentry.io for outages. Verify firewall allows *.ingest.sentry.io on port 443
ESM compatibility error	Node.js < 18.19 or < 20.6	Upgrade Node.js. SDK v8 requires these minimum versions for ESM --import support

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.