Configure Sentry

/configure:sentry

Check and configure Sentry error tracking integration against project standards.

When to Use This Skill

Context

• Package.json: !find . -maxdepth 1 -name \'package.json\'
• Pyproject.toml: !find . -maxdepth 1 -name \'pyproject.toml\'
• Requirements.txt: !find . -maxdepth 1 -name \'requirements.txt\'
• Project standards: !find . -maxdepth 1 -name '.project-standards.yaml' -type f
• Sentry in package.json: !find . -maxdepth 1 -name 'package.json' -exec grep -o '"@sentry/[^"]*"' {} +
• Sentry in pyproject.toml: !find . -maxdepth 1 -name 'pyproject.toml' -exec grep 'sentry' {} +
• Sentry init files: !find . -maxdepth 3 -name "*sentry*" -type f
• Next.js config: !find . -maxdepth 1 -name 'next.config.*'
• Instrumentation files: !find . -path '*/src/*' -maxdepth 2 -name 'instrumentation*' -type f
• Env files referencing DSN: !find . \( -name '.env*' -o -path '*/.github/workflows/*' \) -type f -exec grep -l 'SENTRY_DSN' {} +
• CI workflows: !find . -path '*/.github/workflows/*' -maxdepth 3 -name '*.yml'

Skills referenced: sentry (MCP server for Sentry API)

Parameters

Parse these from $ARGUMENTS:

Version Checking

CRITICAL: Before configuring Sentry SDKs, verify latest versions:

1. @sentry/vue / @sentry/react: Check npm 2. @sentry/nextjs: Check npm 3. @sentry/node: Check npm 4. sentry-sdk (Python): Check PyPI 5. @sentry/vite-plugin: Check npm

Use WebSearch or WebFetch to verify current SDK versions before configuring Sentry.

Execution

Execute this Sentry compliance check:

Step 1: Detect project type

Determine the project type to select the appropriate SDK and configuration:

1. Read .project-standards.yaml for project_type field 2. If not found, auto-detect:

• nextjs: Has package.json with next dependency (check for @sentry/nextjs)
• frontend: Has package.json with vue/react dependencies (without Next.js)
• node: Has package.json with Node.js backend (express, fastify, etc.)
• python: Has pyproject.toml or requirements.txt

3. If --type flag is provided, use that value instead

Step 2: Check SDK installation

Check for Sentry SDK based on detected project type:

Next.js:

• @sentry/nextjs in package.json dependencies
• @sentry/profiling-node (recommended for server profiling)

Frontend (Vue/React):

• @sentry/vue or @sentry/react in package.json dependencies
• @sentry/vite-plugin for source maps

Node.js Backend:

• @sentry/node in package.json dependencies
• @sentry/profiling-node (recommended)

Python:

• sentry-sdk in pyproject.toml or requirements.txt
• Framework integrations (django, flask, fastapi)

Step 3: Analyze configuration

Read the Sentry initialization files and check against the compliance tables in REFERENCE.md. Validate:

1. DSN comes from environment variables (not hardcoded) 2. Tracing sample rate is configured (different for prod vs dev) 3. Source maps are enabled (frontend/Next.js) 4. Init location is correct (Node.js: before other imports) 5. Framework integration is enabled (Python)

Additional checks for Next.js projects:

6. src/instrumentation.ts exists with register() and onRequestError exports 7. src/instrumentation-client.ts exists with client-side Sentry init 8. sentry.server.config.ts and sentry.edge.config.ts exist at project root 9. next.config.mjs wraps config with withSentryConfig() 10. Tunnel route configured (tunnelRoute: "/monitoring") 11. Source maps hidden and deleted after upload (hideSourceMaps, deleteSourcemapsAfterUpload) 12. @sentry/profiling-node listed in serverExternalPackages 13. Error boundaries exist (src/app/error.tsx, src/app/global-error.tsx) 14. Structured logging enabled (enableLogs: true) 15. Sensitive header stripping in beforeSend 16. Transaction filtering in beforeSendTransaction (drop health checks, static assets)

Step 4: Run security checks

1. Verify no hardcoded DSN in any source files 2. Check that DSN is not committed in git-tracked files 3. Verify no auth tokens in frontend code 4. Check production sample rates are reasonable (not 1.0)

Step 5: Report results

Print a compliance report with:

• Project type (detected or overridden)
• SDK version and installation status
• Configuration check results (PASS/WARN/FAIL)
• Security check results
• Missing configuration items
• Recommendations

If --check-only, stop here.

Step 6: Apply fixes (if --fix or user confirms)

1. Missing SDK: Add appropriate Sentry SDK to dependencies 2. Missing Vite plugin: Add @sentry/vite-plugin for source maps 3. Missing config file: Create Sentry initialization file using templates from REFERENCE.md 4. Hardcoded DSN: Replace with environment variable reference 5. Missing sample rates: Add recommended sample rates

Step 7: Check CI/CD integration

Verify Sentry integration in CI/CD:

• SENTRY_AUTH_TOKEN secret configured
• Source map upload step in build workflow
• Release creation on deploy

If missing, offer to add the recommended workflow steps from REFERENCE.md.

Step 8: Update standards tracking

Update or create .project-standards.yaml:

standards_version: "2025.1"
project_type: "<detected>"
last_configured: "<timestamp>"
components:
  sentry: "2025.1"

Environment Variables

Never commit DSN or auth tokens. Use environment variables or secrets management.

For detailed configuration check tables, initialization templates, and CI/CD workflow examples, see REFERENCE.md.

Agentic Optimizations

Error Handling

• No Sentry SDK: Offer to install appropriate SDK for project type
• Hardcoded DSN: Report as FAIL, offer to fix with env var reference
• Invalid DSN format: Report error, provide DSN format guidance
• Missing Sentry project: Report warning, provide setup instructions

See Also

• /configure:all - Run all compliance checks
• /configure:status - Quick compliance overview
• /configure:workflows - GitHub Actions integration
• sentry MCP server - Sentry API access for project verification

Sentry Configuration Reference

Configuration Check Tables

Next.js Configuration Checks

Frontend Configuration Checks

Node.js Configuration Checks

Python Configuration Checks

Report Template

Sentry Compliance Report
============================
Project Type: <type> (detected)
SDK: <sdk-name> <version>

Installation Status:
  <sdk-package>          <version>       PASS/FAIL
  <plugin-package>       <version>       PASS/FAIL

Configuration Checks:
  DSN from environment     PASS/FAIL
  Source maps enabled      PASS/WARN
  Tracing configured       PASS/WARN
  Session replay           PASS/SKIP
  Release auto-injection   PASS/WARN
  Profiling configured     PASS/SKIP
  Structured logging       PASS/SKIP
  Error boundaries         PASS/WARN
  Header stripping         PASS/WARN
  Transaction filtering    PASS/SKIP

Security Checks:
  No hardcoded DSN         PASS/FAIL
  No DSN in git history    PASS/FAIL
  Sample rates reasonable  PASS/WARN
  No auth tokens in client PASS/FAIL

Missing Configuration:
  - <item>

Recommendations:
  - <recommendation>

Overall: <N> warnings, <N> failures

Initialization Templates

Next.js — Server Config

// sentry.server.config.ts (project root)
import * as Sentry from "@sentry/nextjs"
import { nodeProfilingIntegration } from "@sentry/profiling-node"

const isProduction = process.env.NODE_ENV === "production"

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  release: process.env.NEXT_PUBLIC_APP_VERSION,
  environment: process.env.SENTRY_ENVIRONMENT || process.env.NODE_ENV,

  tracesSampleRate: isProduction ? 0.1 : 1.0,

  // Profiling
  profileSessionSampleRate: 1.0,
  profileLifecycle: "trace",

  // Structured logging
  enableLogs: true,
  beforeSendLog(log) {
    if (isProduction && (log.level === "trace" || log.level === "debug")) {
      return null // Drop verbose logs in production
    }
    return log
  },

  integrations: [
    Sentry.httpIntegration(),
    Sentry.onUnhandledRejectionIntegration(),
    nodeProfilingIntegration(),
  ],

  // Strip sensitive headers
  beforeSend(event) {
    const headers = event.request?.headers
    if (headers) {
      delete headers.authorization
      delete headers.cookie
      delete headers["x-api-key"]
    }
    return event
  },

  // Drop low-value transactions
  beforeSendTransaction(event) {
    const name = event.transaction
    if (
      name?.startsWith("GET /api/health") ||
      name?.startsWith("GET /monitoring") ||
      name?.startsWith("GET /_next/")
    ) {
      return null
    }
    return event
  },

  initialScope: {
    tags: {
      runtime: "nodejs",
      ...(process.env.HOSTNAME && { "k8s.pod": process.env.HOSTNAME }),
    },
  },
})

Next.js — Edge Config

// sentry.edge.config.ts (project root)
import * as Sentry from "@sentry/nextjs"

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  release: process.env.NEXT_PUBLIC_APP_VERSION,
  environment: process.env.SENTRY_ENVIRONMENT || process.env.NODE_ENV,
  tracesSampleRate: process.env.NODE_ENV === "production" ? 0.1 : 1.0,
  enableLogs: true,
  initialScope: {
    tags: { runtime: "edge" },
  },
})

Next.js — Client Instrumentation

// src/instrumentation-client.ts
import * as Sentry from "@sentry/nextjs"

const isProduction = process.env.NODE_ENV === "production"

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  environment:
    process.env.NEXT_PUBLIC_SENTRY_ENVIRONMENT || process.env.NODE_ENV,

  tracesSampleRate: isProduction ? 0.1 : 1.0,

  // Session replay
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,

  // Profiling
  profileSessionSampleRate: 1.0,
  profileLifecycle: "trace",

  // Structured logging
  enableLogs: true,

  integrations: [
    Sentry.replayIntegration({ maskAllText: true, blockAllMedia: true }),
    Sentry.browserTracingIntegration(),
    Sentry.feedbackIntegration({
      colorScheme: "system",
      autoInject: true,
      enableScreenshot: true,
      showBranding: false,
    }),
    Sentry.browserProfilingIntegration(),
  ],

  ignoreErrors: [
    /chrome-extension:\/\//,
    /moz-extension:\/\//,
    "Network request failed",
    "Failed to fetch",
    "AbortError",
  ],
})

// Export for Next.js router transition instrumentation
export const onRouterTransitionStart = Sentry.captureRouterTransitionStart

Next.js — Server Instrumentation Hook

// src/instrumentation.ts
import * as Sentry from "@sentry/nextjs"

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("../sentry.server.config")
  }
  if (process.env.NEXT_RUNTIME === "edge") {
    await import("../sentry.edge.config")
  }
}

export const onRequestError = Sentry.captureRequestError

Next.js — next.config.mjs Integration

// next.config.mjs
import { withSentryConfig } from "@sentry/nextjs"

const nextConfig = {
  // Keep @sentry/profiling-node unbundled (native bindings)
  serverExternalPackages: ["@sentry/profiling-node"],

  async headers() {
    return [
      {
        source: "/monitoring",
        headers: [{ key: "Cache-Control", value: "no-store" }],
      },
    ]
  },
}

const sentryOptions = {
  org: process.env.SENTRY_ORG,
  project: process.env.SENTRY_PROJECT,
  authToken: process.env.SENTRY_AUTH_TOKEN,
  silent: !process.env.CI,
  disableServerWebpackPlugin: process.env.NODE_ENV !== "production",
  disableClientWebpackPlugin: process.env.NODE_ENV !== "production",
  disableLogger: true,
  hideSourceMaps: true,
  release: {
    name: version,
    setCommits: { auto: true, ignoreMissing: true },
  },
  tunnelRoute: "/monitoring",
  sourcemaps: { deleteSourcemapsAfterUpload: true },
}

// Skip Sentry plugin during container builds (saves ~1GB memory)
const skipSentry = process.env.NEXT_PUBLIC_SENTRY_SKIP_BUILD === "1"
export default skipSentry ? nextConfig : withSentryConfig(nextConfig, sentryOptions)

Next.js — Error Boundaries

// src/app/error.tsx
"use client"
import * as Sentry from "@sentry/nextjs"
import { useEffect } from "react"

export default function Error({
  error,
  reset,
}: { error: Error & { digest?: string }; reset: () => void }) {
  useEffect(() => {
    Sentry.captureException(error, {
      tags: { errorBoundary: "route" },
      extra: { digest: error.digest },
    })
  }, [error])

  return (
    <div>
      <h2>Something went wrong</h2>
      <button onClick={reset}>Try again</button>
    </div>
  )
}

// src/app/global-error.tsx
"use client"
import * as Sentry from "@sentry/nextjs"
import { useEffect } from "react"

export default function GlobalError({
  error,
  reset,
}: { error: Error & { digest?: string }; reset: () => void }) {
  useEffect(() => {
    Sentry.captureException(error, {
      tags: { errorBoundary: "global" },
      extra: { digest: error.digest },
    })
  }, [error])

  return (
    <html>
      <body>
        <h2>Something went wrong</h2>
        <button onClick={reset}>Try again</button>
      </body>
    </html>
  )
}

Next.js — User Identity Sync

// src/lib/sentry/sentry-user-identity.tsx
"use client"
import * as Sentry from "@sentry/nextjs"
import { useSession } from "next-auth/react"
import { useEffect } from "react"

export function SentryUserIdentity() {
  const { data: session } = useSession()

  useEffect(() => {
    if (session?.user) {
      Sentry.setUser({
        id: session.user.id,
        email: session.user.email ?? undefined,
        username: session.user.name ?? undefined,
      })
    } else {
      Sentry.setUser(null)
    }
  }, [session])

  return null // Invisible component
}

// Include in root layout: <SentryUserIdentity />

Next.js — Enrichment Helpers

// src/lib/sentry/enrichment.ts
import * as Sentry from "@sentry/nextjs"

// --- User identity ---
export function setSentryUser(user: { id: string; email?: string; username?: string }) {
  Sentry.setUser(user)
}

export function clearSentryUser() {
  Sentry.setUser(null)
}

// --- Custom contexts ---
export function setSentryAIContext(data: {
  operation: string
  model: string
  entityType?: string
  entityId?: string
}) {
  Sentry.setContext("ai_operation", data)
}

export function setSentrySyncContext(data: {
  source: string
  operation: string
  entityCount?: number
  userId?: string
}) {
  Sentry.setContext("sync_operation", data)
}

// --- Breadcrumb categories ---
export const BREADCRUMB_CATEGORIES = {
  EXTERNAL_API: "external-api",
  AI_OPERATION: "ai-operation",
  SYNC_OPERATION: "sync-operation",
  AUTH: "auth",
} as const

export function addExternalApiBreadcrumb(data: {
  service: string
  method: string
  url: string
  status?: number
}) {
  Sentry.addBreadcrumb({
    category: BREADCRUMB_CATEGORIES.EXTERNAL_API,
    message: `${data.method} ${data.url}`,
    level: data.status && data.status >= 400 ? "error" : "info",
    data,
  })
}

// --- Custom fingerprinting for upstream errors ---
export function captureUpstreamError(
  error: Error,
  service: string,
  extra?: Record<string, unknown>,
) {
  Sentry.captureException(error, {
    fingerprint: ["upstream-service", service],
    tags: { errorType: "upstream", service },
    extra,
  })
}

Frontend (Vue)

// src/sentry.ts
import * as Sentry from '@sentry/vue'
import type { App } from 'vue'

export function initSentry(app: App) {
  Sentry.init({
    app,
    dsn: import.meta.env.VITE_SENTRY_DSN,
    environment: import.meta.env.MODE,
    release: import.meta.env.VITE_SENTRY_RELEASE,
    integrations: [
      Sentry.browserTracingIntegration(),
    ],
    tracesSampleRate: import.meta.env.PROD ? 0.1 : 1.0,
  })
}

Python

# sentry_init.py
import os
import sentry_sdk

def init_sentry():
    sentry_sdk.init(
        dsn=os.getenv('SENTRY_DSN'),
        environment=os.getenv('SENTRY_ENVIRONMENT', 'development'),
        release=os.getenv('SENTRY_RELEASE'),
        traces_sample_rate=0.1 if os.getenv('SENTRY_ENVIRONMENT') == 'production' else 1.0,
    )

Node.js

// instrument.js (must be first import)
import * as Sentry from '@sentry/node'

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  release: process.env.SENTRY_RELEASE,
  tracesSampleRate: process.env.NODE_ENV === 'production' ? 0.1 : 1.0,
})

CI/CD Integration

Recommended GitHub Actions Workflow Addition

- name: Create Sentry Release
  uses: getsentry/action-release@v3
  env:
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
    SENTRY_ORG: your-org
    SENTRY_PROJECT: your-project
  with:
    environment: production
    sourcemaps: './dist'

Next.js Container Build Optimization

For Docker builds where source map upload happens in CI (not during build):

# Skip Sentry webpack plugin during container build
ARG NEXT_PUBLIC_SENTRY_SKIP_BUILD=1

This saves ~1GB memory and significant build time. Source maps are uploaded separately via CI/CD.

Recommended Sample Rates