System Diagnostics

Field	Value
Document ID	ASCEND-ENT-008
Version	1.0.0
Last Updated	December 19, 2025
Author	Ascend Engineering Team
Publisher	OW-KAI Technologies Inc.
Classification	Enterprise Client Documentation
Compliance	SOC 2 CC6.1/CC6.2, PCI-DSS 7.1/8.3, HIPAA 164.312, NIST 800-53 AC-2/SI-4

Reading Time: 8 minutes | Skill Level: Advanced

Overview

ASCEND provides enterprise-grade diagnostic endpoints for health monitoring, integration testing, and SIEM export. All diagnostics include correlation IDs for traceability and comply with SOC 2 CC7.2, PCI-DSS 10.2, and HIPAA 164.312.

Diagnostic Architecture

+---------------------------------------------------------------------------------+
|                          DIAGNOSTIC SYSTEM                                       |
+---------------------------------------------------------------------------------+
|                                                                                  |
|   HEALTH COMPONENTS                                                             |
|   +-------------------------------------------------------------------------+   |
|   |                                                                          |   |
|   |   API (30%)           Database (40%)        Integrations (20%)          |   |
|   |   +-------------+     +-------------+       +-------------+             |   |
|   |   | Latency     |     | Connection  |       | Cognito     |             |   |
|   |   | Endpoints   |     | Pool        |       | Webhooks    |             |   |
|   |   | Response    |     | Query Perf  |       | SIEM        |             |   |
|   |   +-------------+     +-------------+       +-------------+             |   |
|   |                                                                          |   |
|   |   Security (10%)                                                        |   |
|   |   +-------------+                                                       |   |
|   |   | RLS Active  |                                                       |   |
|   |   | RBAC Check  |                                                       |   |
|   |   | Org Verify  |                                                       |   |
|   |   +-------------+                                                       |   |
|   |                                                                          |   |
|   +-------------------------------------------------------------------------+   |
|                              |                                                   |
|                              v                                                   |
|   +-------------------------------------------------------------------------+   |
|   |                    COMPOSITE HEALTH SCORE                                |   |
|   |                                                                          |   |
|   |   Score = (API * 0.30) + (DB * 0.40) + (INT * 0.20) + (SEC * 0.10)      |   |
|   |                                                                          |   |
|   |   >= 90: INFO      >= 80: WARNING     >= 60: ERROR     < 60: CRITICAL   |   |
|   +-------------------------------------------------------------------------+   |
|                                                                                  |
+---------------------------------------------------------------------------------+

Full Health Check

Endpoint

# Run comprehensive health check
curl "https://pilot.owkai.app/api/diagnostics/health" \
  -H "Authorization: Bearer <admin_jwt>"

Response

{
  "correlation_id": "diag_1_20251215_103045_a1b2c3d4",
  "status": "success",
  "health_score": 98.5,
  "severity": "INFO",
  "components": {
    "api": {
      "status": "healthy",
      "score": 100,
      "latency_ms": 12,
      "endpoints_tested": 1
    },
    "database": {
      "status": "healthy",
      "score": 100,
      "latency_ms": 8,
      "connection_test": "passed",
      "pool_size": 5,
      "pool_overflow": 0
    },
    "integrations": {
      "status": "healthy",
      "score": 95,
      "data_integrity": {
        "alerts_count": 1250,
        "actions_count": 8432
      }
    },
    "security": {
      "status": "healthy",
      "score": 100,
      "multi_tenant_isolation": "active",
      "organization_verified": true,
      "rbac_enforced": true
    }
  },
  "remediation": [],
  "duration_ms": 45,
  "timestamp": "2025-12-15T10:30:45Z"
}

Health Score Calculation

# Source: routes/diagnostics_routes.py:103
def calculate_health_score(components: dict) -> float:
    """
    Calculate composite health score (0-100).

    Weights:
    - API: 30%
    - Database: 40%
    - Integrations: 20%
    - Security: 10%
    """
    weights = {
        "api": 0.30,
        "database": 0.40,
        "integrations": 0.20,
        "security": 0.10
    }

    total_score = 0.0
    for component, weight in weights.items():
        if component in components:
            component_score = components[component].get("score", 0)
            total_score += component_score * weight

    return round(total_score, 1)

Component Diagnostics

API Health

curl "https://pilot.owkai.app/api/diagnostics/api" \
  -H "Authorization: Bearer <admin_jwt>"

Response:

{
  "correlation_id": "diag_1_20251215_103050_b2c3d4e5",
  "status": "success",
  "health_score": 100,
  "severity": "INFO",
  "endpoints": [
    {
      "endpoint": "/api/diagnostics/api",
      "status": "healthy",
      "latency_ms": 5
    }
  ],
  "duration_ms": 8,
  "timestamp": "2025-12-15T10:30:50Z"
}

Database Health

curl "https://pilot.owkai.app/api/diagnostics/database" \
  -H "Authorization: Bearer <admin_jwt>"

Response:

{
  "correlation_id": "diag_1_20251215_103055_c3d4e5f6",
  "status": "success",
  "health_score": 100,
  "severity": "INFO",
  "checks": {
    "connection": {
      "status": "passed",
      "latency_ms": 3
    },
    "query_performance": {
      "status": "passed",
      "latency_ms": 12
    }
  },
  "duration_ms": 18,
  "timestamp": "2025-12-15T10:30:55Z"
}

Integration Health

curl "https://pilot.owkai.app/api/diagnostics/integrations" \
  -H "Authorization: Bearer <admin_jwt>"

Response:

{
  "correlation_id": "diag_1_20251215_103100_d4e5f6g7",
  "status": "success",
  "health_score": 95,
  "severity": "INFO",
  "integrations": {
    "cognito": {
      "status": "configured",
      "score": 100,
      "pool_id": "us-east-2_abc12..."
    },
    "data_pipeline": {
      "status": "healthy",
      "score": 100,
      "alerts_ingested": 1250
    }
  },
  "duration_ms": 125,
  "timestamp": "2025-12-15T10:31:00Z"
}

Diagnostic History

Query Past Diagnostics

curl "https://pilot.owkai.app/api/diagnostics/history?limit=20&diagnostic_type=full_diagnostic" \
  -H "Authorization: Bearer <admin_jwt>"

Response:

{
  "status": "success",
  "total": 20,
  "history": [
    {
      "correlation_id": "diag_1_20251215_103045_a1b2c3d4",
      "type": "full_diagnostic",
      "status": "success",
      "health_score": 98.5,
      "severity": "INFO",
      "duration_ms": 45,
      "initiated_by": 1,
      "created_at": "2025-12-15T10:30:45Z"
    },
    {
      "correlation_id": "diag_1_20251215_093045_x1y2z3a4",
      "type": "full_diagnostic",
      "status": "success",
      "health_score": 97.2,
      "severity": "INFO",
      "duration_ms": 52,
      "initiated_by": 1,
      "created_at": "2025-12-15T09:30:45Z"
    }
  ]
}

SIEM Export

Export to Splunk CIM

curl -X POST "https://pilot.owkai.app/api/diagnostics/export" \
  -H "Authorization: Bearer <admin_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "splunk_cim",
    "start_date": "2025-12-01T00:00:00Z",
    "end_date": "2025-12-15T23:59:59Z",
    "include_details": true
  }'

Export to Datadog

curl -X POST "https://pilot.owkai.app/api/diagnostics/export" \
  -H "Authorization: Bearer <admin_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "datadog_metrics",
    "start_date": "2025-12-01T00:00:00Z",
    "end_date": "2025-12-15T23:59:59Z"
  }'

Severity Levels

Health Score	Severity	Status	Action
>= 90	INFO	Healthy	No action needed
80-89	WARNING	Degraded	Monitor closely
60-79	ERROR	Unhealthy	Investigation required
< 60	CRITICAL	Failed	Immediate action

Remediation Suggestions

When components are degraded, the diagnostic system provides AI-powered remediation suggestions:

{
  "remediation": [
    {
      "priority": 1,
      "component": "database",
      "action": "Investigate database component - performance degraded",
      "impact": "High"
    },
    {
      "priority": 2,
      "component": "integrations",
      "action": "Monitor integrations component - Cognito latency elevated",
      "impact": "Medium"
    }
  ]
}

Rate Limits

Endpoint	Rate Limit	Notes
/health	10/minute	Full diagnostic
/api	20/minute	API check
/database	20/minute	DB check
/integrations	20/minute	Integration check
/history	30/minute	Read-only
/export	5/minute	Heavy operation

Monitoring Integration

Prometheus Metrics

# Exposed metrics
METRICS = {
    "ascend_health_score": "Composite health score (0-100)",
    "ascend_api_latency_ms": "API response latency",
    "ascend_db_latency_ms": "Database query latency",
    "ascend_diagnostic_duration_ms": "Diagnostic run duration"
}

Alerting Rules

# Prometheus alerting rules
groups:
  - name: ascend-diagnostics
    rules:
      - alert: ASCENDHealthDegraded
        expr: ascend_health_score < 80
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: ASCEND health score degraded

      - alert: ASCENDHealthCritical
        expr: ascend_health_score < 60
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: ASCEND health critical

Compliance

Standard	Requirement	Implementation
SOC 2 CC7.2	Incident detection	Health monitoring
PCI-DSS 10.2	Event logging	Diagnostic audit
HIPAA 164.312	System monitoring	Health checks
NIST AU-6	Audit analysis	SIEM export

Best Practices

1. Scheduled Health Checks

# Run health checks every 5 minutes
import schedule

schedule.every(5).minutes.do(run_health_check)

2. Alert Thresholds

# Configure alerting thresholds
THRESHOLDS = {
    "health_score_warning": 80,
    "health_score_critical": 60,
    "api_latency_warning_ms": 500,
    "db_latency_warning_ms": 100
}

3. Trend Analysis

# Track health score trends
if current_score < previous_score - 5:
    alert("Health score declining rapidly")

Next Steps

• SIEM Integration - Security monitoring
• ServiceNow - ITSM integration
• Analytics - Metrics dashboard

---

Document Version: 1.0.0 | Last Updated: December 2025