Unclassified

IntegrateWise Observability & Reliability Documentation

Monitoring, SLAs, and Operational Excellence

Version: 1.0
Classification: Internal + IT Teams
Last Updated: January 2026

Monitoring Strategy
Health Checks
Error Reporting
Retry Logic
Status Page & Incident Process
SLAs
Performance Benchmarks
Alerting

1. Monitoring Strategy

1.1 Monitoring Stack

Component	Tool	Purpose
Uptime Monitoring	Better Stack	External availability checks
Application Metrics	Cloudflare Analytics	Request metrics, errors
Database Metrics	Supabase Dashboard	Query performance, connections
Error Tracking	Sentry (planned)	Error aggregation, stack traces
Log Aggregation	Cloudflare Logs	Request/response logs
Synthetic Monitoring	Better Stack	API endpoint checks

1.2 Key Metrics

System Metrics

Metric	Target	Alert Threshold
Uptime	99.9%	< 99.5%
Response Time (p50)	< 100ms	> 200ms
Response Time (p95)	< 500ms	> 1000ms
Error Rate	< 0.1%	> 1%
CPU Utilization	< 70%	> 85%
Memory Usage	< 80%	> 90%

Business Metrics

Metric	Purpose	Alert
Sync Success Rate	Integration health	< 95%
Webhook Delivery Rate	Integration health	< 99%
API Request Volume	Capacity planning	> 80% of limit
Active Connections	Database health	> 80% of pool

1.3 Monitoring Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                      MONITORING ARCHITECTURE                                 │
└─────────────────────────────────────────────────────────────────────────────┘

                              EXTERNAL
     ┌─────────────────────────────────────────────────────────────────┐
     │                     Better Stack                                │
     │  • Uptime monitoring (every 30s)                               │
     │  • SSL certificate checks                                       │
     │  • API endpoint health                                          │
     └─────────────────────────────────────────────────────────────────┘
                                   │
                                   │ Alerts
                                   ▼
     ┌─────────────────────────────────────────────────────────────────┐
     │                     NOTIFICATION CHANNELS                        │
     │  • Slack (#alerts)                                              │
     │  • Email (on-call)                                              │
     │  • PagerDuty (P1 only)                                          │
     └─────────────────────────────────────────────────────────────────┘
                                   ▲
                                   │ Alerts
                                   │
     ┌─────────────────────────────────────────────────────────────────┐
     │                     INTERNAL MONITORING                          │
     │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
     │  │  Cloudflare  │  │   Supabase   │  │   n8n        │          │
     │  │  Analytics   │  │   Dashboard  │  │  Monitoring  │          │
     │  │              │  │              │  │              │          │
     │  │ • Requests   │  │ • DB metrics │  │ • Workflow   │          │
     │  │ • Errors     │  │ • Query time │  │   success    │          │
     │  │ • Bandwidth  │  │ • Pool usage │  │ • Execution  │          │
     │  └──────────────┘  └──────────────┘  └──────────────┘          │
     └─────────────────────────────────────────────────────────────────┘

2. Health Checks

2.1 Health Check Endpoints

Endpoint	Purpose	Frequency
`GET /health`	Basic liveness	Every 30s
`GET /health/ready`	Full readiness	Every 60s
`GET /health/db`	Database connectivity	Every 60s
`GET /health/integrations`	External service status	Every 5m

2.2 Health Check Responses

Basic Health (`/health`)

{
  "status": "healthy",
  "timestamp": "2026-01-07T10:30:00Z",
  "version": "1.0.0"
}

Full Readiness (`/health/ready`)

{
  "status": "healthy",
  "timestamp": "2026-01-07T10:30:00Z",
  "version": "1.0.0",
  "checks": {
    "database": {
      "status": "healthy",
      "latency_ms": 12
    },
    "cache": {
      "status": "healthy",
      "latency_ms": 2
    },
    "queue": {
      "status": "healthy",
      "pending_jobs": 5
    }
  }
}

Degraded State

{
  "status": "degraded",
  "timestamp": "2026-01-07T10:30:00Z",
  "version": "1.0.0",
  "checks": {
    "database": {
      "status": "healthy",
      "latency_ms": 12
    },
    "cache": {
      "status": "degraded",
      "latency_ms": 150,
      "message": "Elevated latency"
    }
  }
}

2.3 Health Check Logic

// Health check implementation
async function healthCheck(): Promise<HealthStatus> {
  const checks = await Promise.allSettled([checkDatabase(), checkCache(), checkQueue()]);

  const results = {
    database: checks[0],
    cache: checks[1],
    queue: checks[2],
  };

  const hasUnhealthy = Object.values(results).some(
    (r) => r.status === "rejected" || r.value?.status === "unhealthy"
  );

  const hasDegraded = Object.values(results).some((r) => r.value?.status === "degraded");

  return {
    status: hasUnhealthy ? "unhealthy" : hasDegraded ? "degraded" : "healthy",
    checks: results,
    timestamp: new Date().toISOString(),
  };
}

3. Error Reporting

3.1 Error Classification

Level	Description	Action
Fatal	Application crash	Immediate alert, restart
Error	Operation failed	Log, alert if frequent
Warning	Degraded operation	Log, monitor
Info	Operational info	Log only

3.2 Error Format

{
  "error_id": "err_a1b2c3d4",
  "level": "error",
  "timestamp": "2026-01-07T10:30:00Z",
  "request_id": "req_xyz789",
  "message": "Database connection timeout",
  "code": "DB_TIMEOUT",
  "context": {
    "organization_id": "org_abc123",
    "user_id": "usr_def456",
    "endpoint": "/v1/accounts",
    "method": "GET"
  },
  "stack": "Error: Database connection timeout\n    at queryDatabase...",
  "metadata": {
    "query_duration_ms": 30000,
    "retry_count": 3
  }
}

3.3 Error Aggregation

Errors are aggregated by:

Error code
Endpoint
Organization
Time window

Alert thresholds:

Condition	Alert
Same error 5x in 5 minutes	Warning
Same error 20x in 5 minutes	Error
Error rate > 1%	Critical

4. Retry Logic

4.1 Retry Configuration

Operation	Max Retries	Strategy	Backoff
Database queries	3	Exponential	100ms, 500ms, 2s
External API calls	5	Exponential + Jitter	1s → 32s
Webhook delivery	10	Exponential	1m → 24h
File operations	3	Linear	1s, 2s, 3s

4.2 Retry Implementation

async function withRetry<T>(operation: () => Promise<T>, options: RetryOptions): Promise<T> {
  const { maxRetries, initialDelay, maxDelay, factor } = options;

  let lastError: Error;
  let delay = initialDelay;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error) {
      lastError = error;

      // Don't retry on non-retriable errors
      if (!isRetriable(error)) {
        throw error;
      }

      // Check if we've exhausted retries
      if (attempt === maxRetries) {
        break;
      }

      // Add jitter (±25%)
      const jitter = delay * (0.75 + Math.random() * 0.5);
      await sleep(jitter);

      // Exponential backoff
      delay = Math.min(delay * factor, maxDelay);
    }
  }

  throw new RetryExhaustedError(lastError, maxRetries);
}

4.3 Circuit Breaker

class CircuitBreaker {
  private failures = 0;
  private lastFailure: Date | null = null;
  private state: "closed" | "open" | "half-open" = "closed";

  async execute<T>(operation: () => Promise<T>): Promise<T> {
    if (this.state === "open") {
      if (this.shouldReset()) {
        this.state = "half-open";
      } else {
        throw new CircuitOpenError();
      }
    }

    try {
      const result = await operation();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  private onSuccess() {
    this.failures = 0;
    this.state = "closed";
  }

  private onFailure() {
    this.failures++;
    this.lastFailure = new Date();

    if (this.failures >= FAILURE_THRESHOLD) {
      this.state = "open";
    }
  }

  private shouldReset(): boolean {
    return Date.now() - this.lastFailure!.getTime() > RESET_TIMEOUT;
  }
}

5. Status Page & Incident Process

5.1 Status Page

URL: https://status.integratewise.com

Components Monitored

Component	Description
Web Application	Dashboard, user interface
API	REST API endpoints
Integrations	Third-party connections
Automations	Workflow engine
Document Generation	Render service

Status Levels

Status	Description	Color
Operational	All systems normal	🟢 Green
Degraded Performance	Slower than normal	🟡 Yellow
Partial Outage	Some features unavailable	🟠 Orange
Major Outage	Service unavailable	🔴 Red

5.2 Incident Process

┌─────────────────────────────────────────────────────────────────────────────┐
│                      INCIDENT MANAGEMENT PROCESS                             │
└─────────────────────────────────────────────────────────────────────────────┘

     DETECT                    RESPOND                    RESOLVE
     ───────                   ───────                    ───────

     ┌───────────────┐        ┌───────────────┐        ┌───────────────┐
     │ Monitoring    │        │ Acknowledge   │        │ Implement     │
     │ Alert Fires   │───────▶│ & Triage      │───────▶│ Fix           │
     └───────────────┘        └───────────────┘        └───────────────┘
            │                        │                        │
            │                        │                        │
            ▼                        ▼                        ▼
     ┌───────────────┐        ┌───────────────┐        ┌───────────────┐
     │ Auto-create   │        │ Update Status │        │ Update Status │
     │ Incident      │        │ Page          │        │ Page          │
     └───────────────┘        └───────────────┘        └───────────────┘
            │                        │                        │
            │                        │                        │
            ▼                        ▼                        ▼
     ┌───────────────┐        ┌───────────────┐        ┌───────────────┐
     │ Notify        │        │ Communicate   │        │ Post-mortem   │
     │ On-call       │        │ to Users      │        │ (within 48h)  │
     └───────────────┘        └───────────────┘        └───────────────┘

5.3 Communication Templates

Investigating

[Investigating] Elevated API Error Rates

We are currently investigating elevated error rates on our API.
Some requests may fail or time out.

We will provide an update within 30 minutes.

Posted: 10:30 AM UTC

Identified

[Identified] Elevated API Error Rates

We have identified the cause as a database connection issue.
Our team is actively working on a fix.

Impact: ~5% of API requests failing
Workaround: Retry failed requests

Next update in 15 minutes.

Posted: 10:45 AM UTC

Resolved

[Resolved] Elevated API Error Rates

This incident has been resolved. Database connections have been
restored and all systems are operating normally.

Duration: 45 minutes
Impact: ~5% of API requests failed during the incident

We will publish a full post-mortem within 48 hours.

Posted: 11:15 AM UTC

6. SLAs

6.1 Service Level Objectives

Metric	Target	Measurement
Availability	99.9%	Monthly
API Response Time (p95)	< 500ms	Monthly
Sync Reliability	99.5%	Monthly
Webhook Delivery	99.9%	Monthly

6.2 SLA by Plan

Plan	Availability SLA	Support Response	Credits
Free	Best effort	Community	None
Pro	99.9%	24h business	Up to 10%
Enterprise	99.95%	4h (24/7)	Up to 25%

6.3 SLA Exclusions

SLA does not apply to:

Scheduled maintenance (with 72h notice)
Customer-caused issues
Third-party service outages beyond our control
Beta/preview features
API abuse or exceeding rate limits

6.4 Credit Calculation

Monthly Uptime	Credit (% of monthly fee)
99.9% - 99.0%	10%
99.0% - 95.0%	25%
< 95.0%	50%

7. Performance Benchmarks

7.1 API Performance

Endpoint	p50	p95	p99
`GET /accounts` (list)	45ms	120ms	250ms
`GET /accounts/:id`	25ms	80ms	150ms
`POST /accounts`	50ms	150ms	300ms
`PATCH /accounts/:id`	40ms	120ms	250ms
`GET /health`	15ms	40ms	100ms
`GET /health/:id`	30ms	90ms	180ms
`POST /render`	2s	5s	10s

7.2 Sync Performance

Integration	Initial Sync	Incremental Sync
HubSpot	2-10 min	1-2 min
Slack	1-5 min	Real-time
Gmail	5-15 min	2-3 min
Notion	2-8 min	1-2 min
Google Sheets	30s-2 min	On-demand

7.3 Database Performance

Query Type	Target	Alert
Simple read	< 10ms	> 50ms
Complex join	< 100ms	> 500ms
Write	< 50ms	> 200ms
Full-text search	< 200ms	> 1s
Vector search	< 300ms	> 1s

8. Alerting

8.1 Alert Channels

Severity	Slack	Email	PagerDuty
P1 Critical	✅	✅	✅
P2 High	✅	✅	❌
P3 Medium	✅	❌	❌
P4 Low	✅	❌	❌

8.2 Alert Conditions

Alert	Condition	Severity
Service Down	Health check fails 3x	P1
High Error Rate	Error rate > 5%	P1
Elevated Error Rate	Error rate > 1%	P2
High Latency	p95 > 2s	P2
Elevated Latency	p95 > 1s	P3
Database Connection Issues	Pool > 80%	P2
Sync Failures	Success rate < 90%	P3
Webhook Failures	Delivery rate < 95%	P3
Certificate Expiry	< 14 days	P3

8.3 On-Call Rotation

Role	Responsibility	Escalation
Primary	First response	15 min
Secondary	Backup	After 15 min
Engineering Lead	Escalation	After 30 min
CTO	Executive	P1 > 1 hour

IntegrateWise Observability & Reliability Documentation
Version 1.0 — January 2026

For questions: engineering@integratewise.com