Skip to content

MONITORING_API_EXAMPLES.md

Latest commit

 

History

History
849 lines (725 loc) · 16.4 KB

MONITORING_API_EXAMPLES.md

File metadata and controls

849 lines (725 loc) · 16.4 KB
Raw

Monitoring API Examples

Complete API documentation with request/response examples for the monitoring system.

Table of Contents

  1. Monitors
  2. Monitor Runs
  3. Alerts
  4. Notification Channels
  5. Scheduler Health

Monitors

1. Create Monitor

Endpoint: POST /api/v1/monitors

Request:

{
  "workspace_id": "507f1f77bcf86cd799439011",
  "name": "Production API Health Check",
  "description": "Monitor the main API endpoint every 5 minutes",
  "type": "http",
  "schedule": {
    "enabled": true,
    "cron": "*/5 * * * *",
    "timezone": "America/New_York"
  },
  "config": {
    "region": "us-east-1",
    "runner": "cloud",
    "retry": {
      "enabled": true,
      "max_attempts": 3,
      "delay_ms": 1000
    },
    "timeout": {
      "total_ms": 30000,
      "step_ms": 10000
    },
    "delays": {
      "between_steps_ms": 500
    },
    "http": {
      "follow_redirects": true,
      "validate_ssl": true,
      "max_redirects": 5
    }
  },
  "steps": [
    {
      "id": "step-1",
      "name": "Check API Health",
      "protocol": "http",
      "operation": {
        "method": "GET",
        "url": "https://api.example.com/health",
        "headers": [
          { "key": "Accept", "value": "application/json", "enabled": true }
        ],
        "auth": {
          "type": "bearer",
          "bearer": { "token": "your-api-token" }
        }
      },
      "assertions": [
        {
          "type": "status",
          "condition": "equals 200"
        },
        {
          "type": "latency",
          "condition": "< 1000"
        },
        {
          "type": "body",
          "condition": "contains \"status\": \"healthy\""
        }
      ]
    }
  ],
  "alerts": [
    {
      "id": "alert-1",
      "name": "Critical Failure Alert",
      "enabled": true,
      "threshold": {
        "consecutive_failures": 3
      },
      "channels": ["channel-id-1", "channel-id-2"],
      "dedupe_window_minutes": 30
    }
  ]
}

Response (201):

{
  "success": true,
  "message": "Monitor created successfully",
  "monitor": {
    "_id": "507f1f77bcf86cd799439012",
    "workspace_id": "507f1f77bcf86cd799439011",
    "name": "Production API Health Check",
    "type": "http",
    "status": "active",
    "schedule": { ... },
    "config": { ... },
    "steps": [ ... ],
    "alerts": [ ... ],
    "created_by": "507f1f77bcf86cd799439010",
    "created_at": "2026-04-25T10:00:00.000Z",
    "updated_at": "2026-04-25T10:00:00.000Z",
    "next_run_at": "2026-04-25T10:05:00.000Z"
  }
}

2. List Monitors

Endpoint: GET /api/v1/monitors?workspace_id={id}

Response (200):

{
  "success": true,
  "monitors": [
    {
      "_id": "507f1f77bcf86cd799439012",
      "workspace_id": "507f1f77bcf86cd799439011",
      "name": "Production API Health Check",
      "type": "http",
      "status": "active",
      "schedule": {
        "enabled": true,
        "cron": "*/5 * * * *",
        "timezone": "America/New_York"
      },
      "last_run_at": "2026-04-25T10:00:00.000Z",
      "next_run_at": "2026-04-25T10:05:00.000Z",
      "tags": ["production", "critical"]
    }
  ],
  "total": 1
}

3. Get Monitor by ID

Endpoint: GET /api/v1/monitors/{id}

Response (200):

{
  "success": true,
  "monitor": {
    "_id": "507f1f77bcf86cd799439012",
    "workspace_id": "507f1f77bcf86cd799439011",
    "name": "Production API Health Check",
    "description": "Monitor the main API endpoint every 5 minutes",
    "type": "http",
    "status": "active",
    "schedule": { ... },
    "config": { ... },
    "steps": [ ... ],
    "alerts": [ ... ],
    "created_by": "507f1f77bcf86cd799439010",
    "created_at": "2026-04-25T10:00:00.000Z",
    "updated_at": "2026-04-25T10:00:00.000Z"
  }
}

4. Update Monitor

Endpoint: PATCH /api/v1/monitors/{id}

Request:

{
  "name": "Production API Health Check - Updated",
  "schedule": {
    "enabled": true,
    "cron": "*/10 * * * *",
    "timezone": "America/New_York"
  }
}

Response (200):

{
  "success": true,
  "message": "Monitor updated successfully",
  "monitor": { ... }
}

5. Delete Monitor

Endpoint: DELETE /api/v1/monitors/{id}

Response (200):

{
  "success": true,
  "message": "Monitor deleted successfully"
}

6. Trigger Monitor Manually

Endpoint: POST /api/v1/monitors/{id}/trigger

Response (200):

{
  "success": true,
  "message": "Monitor triggered successfully",
  "run_id": "507f1f77bcf86cd799439020"
}

7. Pause Monitor

Endpoint: POST /api/v1/monitors/{id}/pause

Response (200):

{
  "success": true,
  "message": "Monitor paused successfully",
  "monitor": { ... }
}

8. Resume Monitor

Endpoint: POST /api/v1/monitors/{id}/resume

Response (200):

{
  "success": true,
  "message": "Monitor resumed successfully",
  "monitor": { ... }
}

Monitor Runs

1. List All Runs (Across All Monitors)

Endpoint: GET /api/v1/monitor-runs?workspace_id={id}&status={status}&sort_by={field}&sort_order={order}

Query Parameters:

  • workspace_id (required): Workspace ID
  • status (optional): Filter by status (success, failure, error, running)
  • sort_by (optional): Sort field (started_at, duration_ms) - default: started_at
  • sort_order (optional): Sort order (asc, desc) - default: desc

Response (200):

{
  "success": true,
  "runs": [
    {
      "_id": "507f1f77bcf86cd799439020",
      "monitor_id": "507f1f77bcf86cd799439012",
      "monitor_name": "Production API Health Check",
      "run_number": 42,
      "triggered_by": "schedule",
      "region": "us-east-1",
      "runner_id": "cloud-runner-1",
      "started_at": "2026-04-25T10:00:00.000Z",
      "finished_at": "2026-04-25T10:00:02.234Z",
      "duration_ms": 234,
      "status": "success",
      "steps": [
        {
          "step_id": "step-1",
          "name": "Check API Health",
          "protocol": "http",
          "started_at": "2026-04-25T10:00:00.000Z",
          "finished_at": "2026-04-25T10:00:00.234Z",
          "duration_ms": 234,
          "status": "success",
          "http": {
            "request": {
              "method": "GET",
              "url": "https://api.example.com/health",
              "headers": {
                "Accept": "application/json",
                "Authorization": "Bearer ***"
              }
            },
            "response": {
              "status": 200,
              "statusText": "OK",
              "headers": {
                "content-type": "application/json"
              },
              "body": {
                "status": "healthy",
                "uptime": 123456
              },
              "size": 45
            }
          },
          "metrics": {
            "latency_ms": 120,
            "dns_lookup_ms": 10,
            "tcp_connection_ms": 15,
            "tls_handshake_ms": 20,
            "ttfb_ms": 50
          },
          "assertions": [
            {
              "type": "status",
              "condition": "equals 200",
              "passed": true,
              "actual": 200,
              "expected": 200
            },
            {
              "type": "latency",
              "condition": "< 1000",
              "passed": true,
              "actual": 120,
              "expected": 1000
            }
          ]
        }
      ],
      "metrics": {
        "total_requests": 1,
        "successful_requests": 1,
        "failed_requests": 0,
        "average_latency_ms": 120,
        "p95_latency_ms": 120,
        "p99_latency_ms": 120,
        "total_payload_size": 45
      },
      "alerts_sent": [],
      "assertion_results": [
        {
          "type": "status",
          "condition": "equals 200",
          "passed": true,
          "actual": 200,
          "expected": 200
        }
      ]
    }
  ],
  "total": 1
}

2. Get Run by ID

Endpoint: GET /api/v1/monitor-runs/{run_id}

Response (200):

{
  "success": true,
  "run": {
    "_id": "507f1f77bcf86cd799439020",
    "monitor_id": "507f1f77bcf86cd799439012",
    "run_number": 42,
    "status": "success",
    "steps": [ ... ],
    "metrics": { ... }
  },
  "monitor": {
    "_id": "507f1f77bcf86cd799439012",
    "name": "Production API Health Check",
    "type": "http"
  }
}

3. List Runs for Specific Monitor

Endpoint: GET /api/v1/monitors/{id}/runs

Response (200):

{
  "success": true,
  "runs": [ ... ],
  "total": 10
}

Alerts

1. List Alerts

Endpoint: GET /api/v1/alerts?workspace_id={id}&status={status}&severity={severity}

Query Parameters:

  • workspace_id (required): Workspace ID
  • status (optional): Filter by status (active, acknowledged, resolved, all)
  • severity (optional): Filter by severity (critical, high, medium, low, all)

Response (200):

{
  "success": true,
  "alerts": [
    {
      "_id": "507f1f77bcf86cd799439030",
      "monitor_id": "507f1f77bcf86cd799439012",
      "monitor_name": "Production API Health Check",
      "run_id": "507f1f77bcf86cd799439020",
      "alert_id": "alert-1",
      "rule_name": "Critical Failure Alert",
      "type": "failure",
      "message": "3 consecutive failures detected",
      "severity": "critical",
      "channels": ["Slack", "Email"],
      "notification_channels": ["Slack", "Email"],
      "threshold_details": {
        "consecutive_failures": 3,
        "current_failures": 3
      },
      "triggered_at": "2026-04-25T10:15:00.000Z",
      "sent_at": "2026-04-25T10:15:01.000Z",
      "status": "active"
    }
  ],
  "total": 1
}

2. Acknowledge Alert

Endpoint: POST /api/v1/alerts/{id}/acknowledge

Response (200):

{
  "success": true,
  "message": "Alert acknowledged successfully",
  "alert": {
    "_id": "507f1f77bcf86cd799439030",
    "status": "acknowledged",
    "acknowledged_at": "2026-04-25T10:20:00.000Z",
    "acknowledged_by": "507f1f77bcf86cd799439010"
  }
}

3. Resolve Alert

Endpoint: POST /api/v1/alerts/{id}/resolve

Response (200):

{
  "success": true,
  "message": "Alert resolved successfully",
  "alert": {
    "_id": "507f1f77bcf86cd799439030",
    "status": "resolved",
    "resolved_at": "2026-04-25T10:25:00.000Z",
    "resolved_by": "507f1f77bcf86cd799439010"
  }
}

Notification Channels

1. List Notification Channels

Endpoint: GET /api/v1/notification-channels?workspace_id={id}

Response (200):

{
  "success": true,
  "channels": [
    {
      "_id": "507f1f77bcf86cd799439040",
      "workspace_id": "507f1f77bcf86cd799439011",
      "name": "Slack - Production Alerts",
      "type": "slack",
      "description": "Main Slack channel for production alerts",
      "config": {
        "webhook_url": "https://hooks.slack.com/services/...",
        "channel": "#alerts"
      },
      "enabled": true,
      "created_by": "507f1f77bcf86cd799439010",
      "created_at": "2026-04-25T09:00:00.000Z",
      "updated_at": "2026-04-25T09:00:00.000Z",
      "last_used": "2026-04-25T10:15:01.000Z"
    }
  ],
  "total": 1
}

2. Create Notification Channel

Endpoint: POST /api/v1/notification-channels

Request (Email - SMTP):

{
  "workspace_id": "507f1f77bcf86cd799439011",
  "name": "Email - DevOps Team",
  "type": "email",
  "description": "Email notifications to DevOps team",
  "enabled": true,
  "config": {
    "recipients": ["devops@example.com", "oncall@example.com"],
    "sender": "alerts@example.com",
    "provider": "smtp",
    "smtp_host": "smtp.gmail.com",
    "smtp_port": 587,
    "smtp_username": "alerts@example.com",
    "smtp_password": "your-password"
  }
}

Request (Email - SendGrid):

{
  "workspace_id": "507f1f77bcf86cd799439011",
  "name": "Email - SendGrid",
  "type": "email",
  "config": {
    "recipients": ["team@example.com"],
    "sender": "alerts@example.com",
    "provider": "sendgrid",
    "api_key": "SG.xxxxxxxxxxxx"
  },
  "enabled": true
}

Request (Slack):

{
  "workspace_id": "507f1f77bcf86cd799439011",
  "name": "Slack - Production Alerts",
  "type": "slack",
  "config": {
    "webhook_url": "https://hooks.slack.com/services/...",
    "channel": "#alerts"
  },
  "enabled": true
}

Request (Microsoft Teams):

{
  "workspace_id": "507f1f77bcf86cd799439011",
  "name": "Teams - DevOps Channel",
  "type": "teams",
  "config": {
    "webhook_url": "https://outlook.office.com/webhook/..."
  },
  "enabled": true
}

Request (PagerDuty):

{
  "workspace_id": "507f1f77bcf86cd799439011",
  "name": "PagerDuty - Critical Incidents",
  "type": "pagerduty",
  "config": {
    "integration_key": "your-pagerduty-integration-key"
  },
  "enabled": true
}

Request (Custom Webhook):

{
  "workspace_id": "507f1f77bcf86cd799439011",
  "name": "Custom Webhook",
  "type": "webhook",
  "config": {
    "url": "https://api.example.com/webhooks/alerts",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer your-token",
      "Content-Type": "application/json"
    }
  },
  "enabled": true
}

Response (201):

{
  "success": true,
  "message": "Notification channel created successfully",
  "channel": {
    "_id": "507f1f77bcf86cd799439040",
    "workspace_id": "507f1f77bcf86cd799439011",
    "name": "Slack - Production Alerts",
    "type": "slack",
    "config": { ... },
    "enabled": true,
    "created_by": "507f1f77bcf86cd799439010",
    "created_at": "2026-04-25T09:00:00.000Z",
    "updated_at": "2026-04-25T09:00:00.000Z"
  }
}

3. Get Notification Channel by ID

Endpoint: GET /api/v1/notification-channels/{id}

Response (200):

{
  "success": true,
  "channel": { ... }
}

4. Update Notification Channel

Endpoint: PATCH /api/v1/notification-channels/{id}

Request:

{
  "name": "Slack - Production Alerts (Updated)",
  "enabled": true,
  "config": {
    "webhook_url": "https://hooks.slack.com/services/new-webhook",
    "channel": "#production-alerts"
  }
}

Response (200):

{
  "success": true,
  "message": "Notification channel updated successfully",
  "channel": { ... }
}

5. Delete Notification Channel

Endpoint: DELETE /api/v1/notification-channels/{id}

Response (200):

{
  "success": true,
  "message": "Notification channel deleted successfully"
}

6. Test Notification Channel

Endpoint: POST /api/v1/notification-channels/{id}/test

Response (200):

{
  "success": true,
  "message": "Test notification sent successfully via slack",
  "testMessage": {
    "title": "Test Alert from DevTools Hub",
    "message": "This is a test notification to verify your channel configuration.",
    "severity": "info",
    "timestamp": "2026-04-25T10:30:00.000Z"
  }
}

Scheduler Health

Get Scheduler Health

Endpoint: GET /api/v1/monitoring/scheduler/health

Response (200):

{
  "status": "healthy",
  "scheduler": {
    "running": true,
    "redis_connected": true
  },
  "redis": {
    "configured": true,
    "healthy": true
  },
  "queue": {
    "active": 2,
    "waiting": 5,
    "delayed": 10,
    "completed": 1234,
    "failed": 5
  },
  "timestamp": "2026-04-25T10:35:00.000Z"
}

Error Responses

All endpoints may return the following error responses:

400 Bad Request:

{
  "error": "Missing required fields",
  "success": false
}

401 Unauthorized:

{
  "error": "Authentication required",
  "success": false
}

404 Not Found:

{
  "error": "Resource not found",
  "success": false
}

500 Internal Server Error:

{
  "error": "Internal server error",
  "success": false
}

Rate Limiting

All API endpoints are subject to rate limiting:

  • Free tier: 100 requests/minute
  • Pro tier: 1000 requests/minute
  • Enterprise: Custom limits

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1714041600

Pagination

List endpoints support pagination via query parameters:

  • limit (default: 50, max: 100)
  • offset (default: 0)

Response includes pagination metadata:

{
  "data": [ ... ],
  "total": 150,
  "limit": 50,
  "offset": 0,
  "hasMore": true
}

Authentication

All endpoints require Bearer token authentication:

Authorization: Bearer <your-access-token>

Tokens can be obtained via the authentication endpoints (see AUTH_API.md).