Debugging Demo Application

Issue 1: Frontend and Backend Traces Not Connecting

Symptoms

• You see frontend traces in Sentry
• You see backend traces in Sentry
• But they’re separate - not in the same trace

Diagnosis Steps

1. Check for trace headers in browser

   Open DevTools > Network tab > Click an API request > Request Headers

   You should see:

   traceparent: 00-...
   sentry-trace: ...
   baggage: ...

   If headers are missing:

   • Check propagateTraceparent: true in frontend/instrument-sentry.js
   • Verify backend URL is in tracePropagationTargets

2. Verify tracePropagationTargets

   In frontend/instrument-sentry.js:

   tracePropagationTargets: [
     /^\//,                          // Same-origin requests
     /^http:\/\/localhost:3000/,     // Your backend URL
   ],

   The regex must match your backend URL exactly!

3. Check CORS configuration

   The backend must allow trace headers. In api/src/index.js, CORS should be configured:

   app.use(cors({
     origin: ['http://localhost:5173', 'http://localhost:5174'],
     credentials: true,
   }));

4. Verify both services send to same Sentry org

   • Frontend and backend can use different projects
   • But they must be in the same Sentry organization - otherwise, Sentry can’t link the traces

Issue 2: Traces Missing Database Queries

Symptoms

• Traces appear in Sentry
• But database query spans are missing
• Should see spans with db.system: postgresql

Solutions

1. Check that Neon database is accessible

   This workshop uses Neon - a serverless PostgreSQL database. Neon free tier databases may expire after a period of inactivity.

   Check for database connection errors:

   Look for errors in the backend logs when starting the server:

   # In the api directory
   npm run demo:direct

   If you see errors like:

   • ECONNREFUSED
   • database does not exist
   • authentication failed

   Your Neon database may have expired or the connection string is incorrect.

2. Set up a new Neon database

   If your database has expired, the easiest way to create a new one is using the Neon CLI:

   # In the api directory
   npx neondb -y

   This will automatically:

   • Create a new Neon database
   • Configure your DATABASE_URL in the .env file
   • Set up authentication

   Alternative: Manual setup

   If you prefer to set it up manually:

   1. Go to console.neon.tech
   2. Create a new project (or use an existing one)
   3. Copy the connection string from the dashboard
   4. Update api/.env:

   DATABASE_URL=postgresql://user:password@ep-xyz.us-east-2.aws.neon.tech/dbname?sslmode=require

3. Generate database tables

   After setting up a new database, you need to create the tables:

   npm run db:setup

   This will run the schema creation and seed the database with sample products and orders.

4. Verify auto-instrumentation is enabled

   The database instrumentation should be automatically included via getNodeAutoInstrumentations() in api/instrument-otel.js.

5. Generate database traffic

   # This endpoint triggers database queries
   curl http://localhost:3000/api/products

6. Look for the spans in trace details

   Database spans appear as children of the HTTP request span, with tags like:

   • db.system: postgresql
   • db.statement: SELECT ...
   • db.name: neondb (or your database name)

Issue 3: Too Many or Too Few Spans

Too Many Spans

If you see hundreds of spans making traces hard to read:

// In api/instrument-otel.js, you can disable noisy instrumentation:
getNodeAutoInstrumentations({
  '@opentelemetry/instrumentation-fs': {
    enabled: false,  // Disable filesystem tracing (very noisy)
  },
})

Too Few Spans

If you’re not seeing enough detail:

• Check that auto-instrumentations are enabled
• Add manual instrumentation for custom business logic
• Verify sampling rate is 100% for development: tracesSampleRate: 1.0