Application Monitoring | Bootspring Docs

Patterns for monitoring, logging, and observability in production.

Overview#

Monitoring helps you understand application health and debug issues. This pattern covers:

OpenTelemetry setup
Custom metrics with Prometheus
Error tracking with Sentry
Health check endpoints
Performance monitoring

Prerequisites#

npm install @opentelemetry/api @opentelemetry/sdk-node @sentry/nextjs prom-client

Code Example#

OpenTelemetry Setup#

// instrumentation.ts (Next.js)
import { NodeSDK } from '@opentelemetry/sdk-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
import { Resource } from '@opentelemetry/resources'
import {
  SEMRESATTRS_SERVICE_NAME,
  SEMRESATTRS_SERVICE_VERSION
} from '@opentelemetry/semantic-conventions'

export function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const sdk = new NodeSDK({
      resource: new Resource({
        [SEMRESATTRS_SERVICE_NAME]: 'my-nextjs-app',
        [SEMRESATTRS_SERVICE_VERSION]: process.env.npm_package_version ?? '1.0.0'
      }),
      traceExporter: new OTLPTraceExporter({
        url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT
      }),
      instrumentations: [getNodeAutoInstrumentations()]
    })

    sdk.start()
  }
}

Custom Metrics with Prometheus#

// lib/metrics.ts
import { Counter, Histogram, Registry, collectDefaultMetrics } from 'prom-client'

const register = new Registry()

// Collect default Node.js metrics
collectDefaultMetrics({ register })

// HTTP request metrics
export const httpRequestsTotal = new Counter({
  name: 'http_requests_total',
  help: 'Total number of HTTP requests',
  labelNames: ['method', 'path', 'status'],
  registers: [register]
})

export const httpRequestDuration = new Histogram({
  name: 'http_request_duration_seconds',
  help: 'HTTP request duration in seconds',
  labelNames: ['method', 'path'],
  buckets: [0.01, 0.05, 0.1, 0.5, 1, 2, 5],
  registers: [register]
})

// Business metrics
export const userSignups = new Counter({
  name: 'user_signups_total',
  help: 'Total number of user signups',
  labelNames: ['plan'],
  registers: [register]
})

export const apiCalls = new Counter({
  name: 'api_calls_total',
  help: 'Total API calls',
  labelNames: ['endpoint', 'status'],
  registers: [register]
})

export { register }

// API endpoint for Prometheus scraping
// app/api/metrics/route.ts
import { NextResponse } from 'next/server'
import { register } from '@/lib/metrics'

export async function GET() {
  const metrics = await register.metrics()
  return new NextResponse(metrics, {
    headers: {
      'Content-Type': register.contentType
    }
  })
}

Error Tracking with Sentry#

// sentry.client.config.ts
import * as Sentry from '@sentry/nextjs'

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: 1.0,
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  integrations: [
    Sentry.replayIntegration({
      maskAllText: true,
      blockAllMedia: true
    })
  ]
})

// sentry.server.config.ts
import * as Sentry from '@sentry/nextjs'

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: 1.0
})

// lib/error-tracking.ts
import * as Sentry from '@sentry/nextjs'

export function captureError(error: Error, context?: Record<string, any>) {
  Sentry.withScope(scope => {
    if (context) {
      scope.setExtras(context)
    }
    Sentry.captureException(error)
  })
}

export function setUserContext(user: { id: string; email: string }) {
  Sentry.setUser({ id: user.id, email: user.email })
}

export function addBreadcrumb(message: string, data?: Record<string, any>) {
  Sentry.addBreadcrumb({
    message,
    data,
    level: 'info'
  })
}

Health Check Endpoints#

// app/api/health/route.ts
import { NextResponse } from 'next/server'
import { prisma } from '@/lib/db'
import { redis } from '@/lib/redis'

interface HealthCheck {
  status: 'healthy' | 'unhealthy'
  checks: {
    [key: string]: {
      status: 'pass' | 'fail'
      responseTime?: number
      error?: string
    }
  }
  timestamp: string
  version: string
}

export async function GET() {
  const checks: HealthCheck['checks'] = {}

  // Database check
  const dbStart = Date.now()
  try {
    await prisma.$queryRaw`SELECT 1`
    checks.database = {
      status: 'pass',
      responseTime: Date.now() - dbStart
    }
  } catch (error) {
    checks.database = {
      status: 'fail',
      error: error instanceof Error ? error.message : 'Unknown error'
    }
  }

  // Redis check
  const redisStart = Date.now()
  try {
    await redis.ping()
    checks.redis = {
      status: 'pass',
      responseTime: Date.now() - redisStart
    }
  } catch (error) {
    checks.redis = {
      status: 'fail',
      error: error instanceof Error ? error.message : 'Unknown error'
    }
  }

  const allHealthy = Object.values(checks).every(c => c.status === 'pass')

  const response: HealthCheck = {
    status: allHealthy ? 'healthy' : 'unhealthy',
    checks,
    timestamp: new Date().toISOString(),
    version: process.env.npm_package_version ?? '1.0.0'
  }

  return NextResponse.json(response, {
    status: allHealthy ? 200 : 503
  })
}

// Kubernetes probes
// app/api/health/ready/route.ts
export async function GET() {
  // Check if app is ready to receive traffic
  return NextResponse.json({ ready: true })
}

// app/api/health/live/route.ts
export async function GET() {
  // Check if app is alive (not deadlocked)
  return NextResponse.json({ alive: true })
}

Request Tracing Middleware#

// middleware.ts
import { NextRequest, NextResponse } from 'next/server'
import { v4 as uuidv4 } from 'uuid'

export function middleware(request: NextRequest) {
  const requestId = uuidv4()
  const start = Date.now()

  // Add request ID header
  const response = NextResponse.next()
  response.headers.set('X-Request-ID', requestId)

  // Log request
  console.log(JSON.stringify({
    type: 'request',
    requestId,
    method: request.method,
    path: request.nextUrl.pathname,
    timestamp: new Date().toISOString()
  }))

  return response
}

Performance Monitoring#

// lib/performance.ts
import { trace, SpanStatusCode } from '@opentelemetry/api'

const tracer = trace.getTracer('my-app')

export async function withSpan<T>(
  name: string,
  fn: () => Promise<T>,
  attributes?: Record<string, string | number>
): Promise<T> {
  return tracer.startActiveSpan(name, async span => {
    if (attributes) {
      span.setAttributes(attributes)
    }

    try {
      const result = await fn()
      span.setStatus({ code: SpanStatusCode.OK })
      return result
    } catch (error) {
      span.setStatus({
        code: SpanStatusCode.ERROR,
        message: error instanceof Error ? error.message : 'Unknown error'
      })
      span.recordException(error as Error)
      throw error
    } finally {
      span.end()
    }
  })
}

// Usage
const users = await withSpan(
  'fetch-users',
  () => prisma.user.findMany(),
  { 'db.operation': 'findMany', 'db.table': 'users' }
)

Structured Logging#

// lib/logger.ts
type LogLevel = 'debug' | 'info' | 'warn' | 'error'

interface LogEntry {
  level: LogLevel
  message: string
  timestamp: string
  [key: string]: any
}

function log(level: LogLevel, message: string, data?: Record<string, any>) {
  const entry: LogEntry = {
    level,
    message,
    timestamp: new Date().toISOString(),
    ...data
  }

  // In production, send to log aggregator
  if (process.env.NODE_ENV === 'production') {
    console.log(JSON.stringify(entry))
  } else {
    console[level](message, data)
  }
}

export const logger = {
  debug: (msg: string, data?: Record<string, any>) => log('debug', msg, data),
  info: (msg: string, data?: Record<string, any>) => log('info', msg, data),
  warn: (msg: string, data?: Record<string, any>) => log('warn', msg, data),
  error: (msg: string, data?: Record<string, any>) => log('error', msg, data)
}

// Usage
logger.info('User signed up', { userId: user.id, plan: 'pro' })
logger.error('Payment failed', { userId: user.id, error: err.message })

Dashboard Configuration#

# docker-compose.monitoring.yml
version: '3.8'
services:
  prometheus:
    image: prom/prometheus:latest
    ports:
      - '9090:9090'
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus

  grafana:
    image: grafana/grafana:latest
    ports:
      - '3001:3000'
    volumes:
      - grafana_data:/var/lib/grafana
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - '16686:16686'
      - '4317:4317'
      - '4318:4318'

volumes:
  prometheus_data:
  grafana_data:

# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'nextjs-app'
    static_configs:
      - targets: ['host.docker.internal:3000']
    metrics_path: '/api/metrics'

Usage Instructions#

Set up OpenTelemetry for distributed tracing
Add Prometheus metrics for custom monitoring
Configure Sentry for error tracking
Create health check endpoints
Implement structured logging

Best Practices#

Correlation IDs - Track requests across services
Structured logs - Use JSON for easy parsing
Meaningful metrics - Focus on business-relevant data
Alert thresholds - Set alerts before users notice
Sampling - Sample high-volume traces in production
Retention - Define log retention policies
Dashboards - Create actionable dashboards

Audit Logging - Track user actions
CI/CD - Deployment automation
Profiling - Performance analysis
Error Handling - Error responses