npm package: @lit-protocol/lit-status-sdk
Description: SDK for interacting with Lit Status monitoring server
Latest version: 0.1.8

# 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

```bash
# 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):
   ```bash
   bunx prisma init
   ```

2. **Generate Prisma Client**:
   ```bash
   bunx prisma generate
   ```

3. **Create Database Tables**:
   ```bash
   # 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`):
   ```prisma
   model FunctionLog {
     // ... existing fields ...
     statusCode    Int?      // New field
     requestMethod String?   // New field
   }
   ```

2. **Create a Migration**:
   ```bash
   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

```bash
# 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:
```env
# 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
```bash
# Start the full observability stack
./scripts/start-observability-stack.sh
```

### Manual Setup
```bash
# 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](docs/opentelemetry-setup.md)
- [Complete Observability Guide](docs/observability-guide.md)