Sprint 1: Create Metrics Query API with Time-Range Support

[CLoaKY233]

Epic: PingSpider MVP - Distributed Uptime & Latency Monitor

Sprint: 1

Story Points: 5

Description

Implement API endpoints to query historical metrics and calculate uptime percentages for monitored endpoints.

Acceptance Criteria

• GET /api/endpoints/{id}/metrics - Get time-series metrics with filtering
• GET /api/endpoints/{id}/uptime - Get uptime percentage for time range
• GET /api/endpoints/{id}/incidents - List incidents with pagination
• Support query parameters:
  • from (ISO 8601 timestamp)
  • to (ISO 8601 timestamp)
  • limit (default: 100, max: 1000)
  • offset (for pagination)
• Calculate uptime percentage accurately
• Return response time statistics (min, max, avg, p95, p99)
• Optimize queries for performance (use indexes)

API Response Examples

Metrics Endpoint

{
  "endpoint_id": "endpoint:xyz",
  "time_range": {
    "from": "2025-12-06T12:00:00Z",
    "to": "2025-12-07T12:00:00Z"
  },
  "metrics": [
    {
      "timestamp": "2025-12-07T12:00:00Z",
      "status": "up",
      "response_time_ms": 145,
      "status_code": 200
    }
  ],
  "total_count": 1440
}

Uptime Endpoint

{
  "endpoint_id": "endpoint:xyz",
  "time_range": {
    "from": "2025-12-06T12:00:00Z",
    "to": "2025-12-07T12:00:00Z"
  },
  "uptime_percentage": 99.89,
  "total_checks": 1440,
  "successful_checks": 1438,
  "failed_checks": 2,
  "response_time_stats": {
    "min_ms": 45,
    "max_ms": 892,
    "avg_ms": 156,
    "p95_ms": 245,
    "p99_ms": 412
  }
}

Technical Notes

• Use SurrealDB's time-series query capabilities
• Default time range: last 24 hours if not specified
• Calculate percentiles using efficient algorithms
• Add database indexes on timestamp and endpoint_id
• Consider caching uptime calculations for frequently queried ranges

Uptime Calculation Formula

uptime_percentage = (successful_checks / total_checks) * 100

Performance Requirements

• Queries should complete in < 500ms for 24h range
• Support up to 10,000 data points per query
• Efficient pagination for large result sets

Dependencies

• None (uses existing SurrealDB connection)

Files to Create/Modify

• src/rts/metrics.rs (new handlers)
• src/monitoring/queries.rs (database query logic)
• src/monitoring/stats.rs (statistics calculations)
• src/lib.rs (register routes)

Definition of Done

• All query endpoints implemented
• Uptime calculations accurate
• Response time statistics correct
• Performance requirements met
• API documentation complete
• Integration tests pass
• Code reviewed and merged to main