unified-network-status-app

An internal uptime/error monitoring system for tracking named functions and endpoints across different networks and products. Built with TypeScript, Bun, Prisma, and PostgreSQL.

Features

• Track function/endpoint uptime and errors
• Historical metrics storage with efficient querying
• Network and product-based organization
• Response time tracking
• Scalable architecture with connection pooling
• Clean user function tracing with OpenTelemetry
• Focus on your business logic, not infrastructure noise
• Distributed tracing with Jaeger showing only what matters
• Metrics dashboards with Grafana for performance trends
• Real-time monitoring and alerting

Prerequisites

• Bun runtime
• PostgreSQL database
• Node.js (for Prisma CLI)

Installation

# Install dependencies
bun install

# Set up environment variables
cp .env.sample .env
# Edit .env and update DATABASE_URL with your PostgreSQL connection string

DB Init

First-time Database Setup

1. initialise Prisma (if not already done):

   bunx prisma init

2. Generate Prisma Client:

   bunx prisma generate

3. Create Database Tables:

   # Development environment
   bunx prisma migrate dev --name init
   
   # Production environment
   bunx prisma migrate deploy

Adding New Fields/Columns

When you need to add new fields to existing models:

1. Update the Prisma Schema (prisma/schema.prisma):

   model FunctionLog {
     // ... existing fields ...
     statusCode    Int?      // New field
     requestMethod String?   // New field
   }

2. Create a Migration:

   bunx prisma migrate dev --name add_status_fields

3. Update Your Code:

   • The Prisma Client will automatically include the new fields
   • Update any TypeScript interfaces or DBManager methods as needed

Database Migration Commands

# Check migration status
bunx prisma migrate status

# Create a new migration (development)
bunx prisma migrate dev --name descriptive_name

# Apply migrations (production)
bunx prisma migrate deploy

# Reset database (CAUTION: This will delete all data!)
bunx prisma migrate reset

# Generate Prisma Client after schema changes
bunx prisma generate

Schema Management Best Practices

1. Always backup your database before running migrations in production
2. Test migrations in a development environment first
3. Use descriptive migration names that explain what changed
4. Review generated SQL before applying migrations
5. Keep migrations small and focused on a single change

Troubleshooting

Connection Issues:

• Verify DATABASE_URL in .env is correct
• Ensure PostgreSQL is running and accessible
• Check network connectivity to remote databases

Migration Failures:

• Check for data that might violate new constraints
• Review the error message for specific SQL issues
• Use bunx prisma migrate status to see pending migrations

Permission Errors:

• Ensure database user has CREATE/ALTER table permissions
• For managed databases (like Render), migrations might need to be run locally

Environment Variables

Create a .env file with:

# Database Configuration (Prisma format)
DATABASE_URL="postgresql://username:password@host:port/database"

# Environment
NODE_ENV=development

Database Schema

The app uses two main models:

MonitoredFunction:

• Represents a function or endpoint to monitor
• Tracks network, product, and active status
• Has one-to-many relationship with logs

FunctionLog:

• Records each execution of a monitored function
• Tracks success/failure, response time, and error messages
• Indexed by functionId and createdAt for performance

Observability Stack

The app includes a complete observability solution with:

Quick Start

# Start the full observability stack
./scripts/start-observability-stack.sh

Manual Setup

# Install OpenTelemetry packages (focused on user function tracing)
bun add @opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-prometheus @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node

# Start Jaeger (distributed tracing)
docker run -d --name jaeger -p 16686:16686 -p 4317:4317 -p 4318:4318 jaegertracing/all-in-one:latest

# Start Grafana (metrics dashboards)  
docker run -d --name grafana -p 3001:3000 grafana/grafana

# Start instrumented server
bun run src/server/instrumented-server.ts

Access Points

• Jaeger UI: http://localhost:16686 (traces)
• Grafana: http://localhost:3001 (dashboards)
• Metrics: http://localhost:9090/metrics (raw data)

Documentation

• OpenTelemetry Setup Guide
• Complete Observability Guide