Analytics

Field	Value
Document ID	ASCEND-GOV-001
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: 12 minutes | Skill Level: Intermediate

Overview

ASCEND provides comprehensive analytics including real-time metrics, trend analysis, executive dashboards, and ML-powered predictive insights. All analytics are multi-tenant isolated with role-based access.

Analytics Architecture

+---------------------------------------------------------------------------------+
|                          ANALYTICS SYSTEM                                        |
+---------------------------------------------------------------------------------+
|                                                                                  |
|   +-------------------+    +-------------------+    +-------------------+        |
|   |   REAL-TIME       |    |   EXECUTIVE       |    |   PREDICTIVE      |       |
|   |   METRICS         |    |   DASHBOARD       |    |   ANALYTICS       |       |
|   +-------------------+    +-------------------+    +-------------------+        |
|   | - Active agents   |    | - Platform health |    | - Risk forecast   |       |
|   | - Recent actions  |    | - Security posture|    | - Anomaly detect  |       |
|   | - High-risk count |    | - Compliance      |    | - Workload predict|       |
|   | - System health   |    | - Business KPIs   |    | - Recommendations |       |
|   +-------------------+    +-------------------+    +-------------------+        |
|           |                        |                        |                   |
|           v                        v                        v                   |
|   +---------------------------------------------------------------------+       |
|   |                    PostgreSQL + CloudWatch                          |       |
|   +---------------------------------------------------------------------+       |
|                                                                                  |
+---------------------------------------------------------------------------------+

Real-Time Metrics

Get Trend Data

curl "https://pilot.owkai.app/api/analytics/trends" \
  -H "Authorization: Bearer owkai_..."

Response:

{
  "high_risk_actions_by_day": [
    {"date": "2025-12-09", "count": 12},
    {"date": "2025-12-10", "count": 8},
    {"date": "2025-12-11", "count": 15},
    {"date": "2025-12-12", "count": 10},
    {"date": "2025-12-13", "count": 7},
    {"date": "2025-12-14", "count": 11},
    {"date": "2025-12-15", "count": 9}
  ],
  "top_agents": [
    {"agent": "finance-bot-001", "count": 1247},
    {"agent": "data-processor-002", "count": 892},
    {"agent": "customer-support-003", "count": 654}
  ],
  "top_tools": [
    {"tool": "database.query", "count": 2156},
    {"tool": "file.read", "count": 1843},
    {"tool": "api.call", "count": 1204}
  ],
  "enriched_actions": [
    {
      "agent_id": "finance-bot-001",
      "action_type": "database.query",
      "risk_level": "medium",
      "mitre_tactic": "Collection",
      "nist_control": "AC-3",
      "recommendation": "Monitor for bulk data access patterns",
      "tool_name": "database.query",
      "timestamp": "2025-12-15T10:30:00Z"
    }
  ],
  "pending_actions_count": 5
}

Real-Time Overview

curl "https://pilot.owkai.app/api/analytics/realtime/metrics" \
  -H "Authorization: Bearer owkai_..."

Response:

{
  "timestamp": "2025-12-15T10:30:00Z",
  "real_time_overview": {
    "active_sessions": 24,
    "recent_high_risk_actions": 3,
    "active_agents": 12,
    "total_actions_last_hour": 156,
    "actions_last_24h": 2847,
    "status": {
      "has_data": true,
      "message": "Live data from production database",
      "data_age_minutes": 0
    }
  },
  "system_health": {
    "status": "live",
    "source": "cloudwatch_ecs",
    "cpu_usage": 45.2,
    "memory_usage": 62.8,
    "disk_usage": 34.5,
    "network_latency": 12.3,
    "api_response_time": 45.8
  },
  "performance_metrics": {
    "status": "live",
    "source": "cloudwatch_logs",
    "requests_per_second": 125.4,
    "avg_response_time": 42.3,
    "p95_response_time": 98.5,
    "error_rate": 0.002
  },
  "data_quality": {
    "source": "production_database",
    "has_historical_data": true,
    "has_recent_activity": true,
    "data_status": "live"
  },
  "meta": {
    "version": "1.0.0-phase2",
    "enterprise_grade": true,
    "mock_data": false,
    "cloudwatch_enabled": true
  }
}

Executive Dashboard

Get Executive KPIs

curl "https://pilot.owkai.app/api/analytics/executive/dashboard" \
  -H "Authorization: Bearer owkai_..."

Response:

{
  "report_date": "2025-12-15T10:30:00Z",
  "data_period": {
    "start_date": "2025-11-15T10:30:00Z",
    "end_date": "2025-12-15T10:30:00Z",
    "days": 30
  },
  "executive_summary": {
    "overall_health": "excellent",
    "key_achievements": [
      "Zero critical security incidents this month",
      "98.5% compliance score maintained",
      "97.2% system reliability achieved",
      "85% workflow automation rate"
    ],
    "areas_of_focus": [
      "Continue monitoring system health and performance"
    ],
    "data_quality": "real_database_queries"
  },
  "executive_kpis": {
    "platform_health": {
      "score": 97.2,
      "trend": "stable",
      "status": "excellent",
      "total_actions": 45678,
      "success_rate": 97.2
    },
    "security_posture": {
      "score": 94.5,
      "trend": "excellent",
      "critical_issues": 0,
      "high_risk_actions": 127,
      "medium_risk_actions": 892
    },
    "operational_efficiency": {
      "score": 85.0,
      "automation_rate": 0.85,
      "manual_interventions": 42,
      "pending_actions": 5
    },
    "compliance_status": {
      "score": 98.5,
      "violations": 3,
      "pending_reviews": 12,
      "compliance_actions": 456
    }
  },
  "business_metrics": {
    "user_growth": {
      "current_users": 156,
      "active_users": 134,
      "growth_rate": 0.12,
      "trend": "positive",
      "new_users_this_week": 8
    },
    "system_utilization": {
      "avg_actions_per_day": 1523,
      "peak_day_actions": 2847,
      "efficiency_score": 0.92,
      "total_actions_month": 45678
    }
  },
  "strategic_insights": [
    {
      "category": "security",
      "insight": "Strong security posture maintained (only 127 high-risk actions)",
      "action": "Continue current security protocols",
      "priority": "low",
      "data_source": "agent_actions_risk_analysis"
    },
    {
      "category": "efficiency",
      "insight": "Excellent automation rate (85%)",
      "action": "Maintain current automation strategies",
      "priority": "low",
      "data_source": "approval_workflow_metrics"
    }
  ],
  "next_review_date": "2025-12-22T10:30:00Z"
}

Predictive Analytics

Get Predictions

curl "https://pilot.owkai.app/api/analytics/predictive/trends" \
  -H "Authorization: Bearer owkai_..."

Response (with sufficient data):

{
  "status": "active",
  "prediction_quality": "high",
  "risk_forecast": [
    {
      "date": "2025-12-16",
      "predicted_high_risk": 12,
      "predicted_critical": 1,
      "confidence": 0.87
    },
    {
      "date": "2025-12-17",
      "predicted_high_risk": 15,
      "predicted_critical": 2,
      "confidence": 0.82
    },
    {
      "date": "2025-12-18",
      "predicted_high_risk": 10,
      "predicted_critical": 0,
      "confidence": 0.79
    }
  ],
  "agent_workload_forecast": [
    {
      "agent_id": "finance-bot-001",
      "predicted_actions_24h": 285,
      "predicted_peak_hour": 14,
      "confidence": 0.85
    }
  ],
  "anomalies": [
    {
      "type": "volume_spike",
      "agent_id": "data-processor-002",
      "detected_at": "2025-12-15T09:00:00Z",
      "severity": "medium",
      "description": "45% increase in action volume compared to baseline"
    }
  ],
  "risk_predictions": {
    "recommended_actions": [
      {
        "action": "Review data-processor-002 anomaly",
        "priority": "high",
        "reason": "Unusual volume pattern detected"
      },
      {
        "action": "Increase monitoring 14:00-16:00",
        "priority": "medium",
        "reason": "Historical peak hours identified"
      }
    ]
  },
  "data_collection": {
    "days_collected": 21,
    "total_actions": 32456,
    "collection_progress": 100.0,
    "ready": true,
    "quality": "Excellent data for high quality predictions"
  },
  "meta": {
    "version": "1.0.0-phase3",
    "mock_data": false,
    "prediction_method": "ml_powered",
    "confidence_range": [0.79, 0.87],
    "phase": "3_of_3_active"
  }
}

Response (collecting data):

{
  "status": "collecting_data",
  "message": "Collecting data for predictions. Minimum 4 days needed for pattern-based forecasting.",
  "data_collection": {
    "days_collected": 2,
    "minimum_required": 4,
    "optimal_required": 14,
    "total_actions": 1247,
    "collection_progress": 50.0,
    "estimated_ready_date": "2025-12-17"
  },
  "planned_features": [
    {
      "feature": "Risk Trend Forecasting",
      "description": "Predict high-risk action patterns 7 days ahead",
      "accuracy_target": "85%+",
      "benefit": "Proactive threat mitigation"
    },
    {
      "feature": "Anomaly Detection",
      "description": "Identify unusual patterns and potential security threats",
      "accuracy_target": "90%+",
      "benefit": "Early warning system for security incidents"
    }
  ]
}

System Performance

Get Performance Metrics

curl "https://pilot.owkai.app/api/analytics/performance" \
  -H "Authorization: Bearer owkai_..."

Response:

{
  "timestamp": "2025-12-15T10:30:00Z",
  "system_metrics": {
    "cpu": {
      "current": 45.2,
      "average": 42.8,
      "status": "normal",
      "source": "cloudwatch"
    },
    "memory": {
      "current": 62.8,
      "available": 37.2,
      "status": "normal",
      "source": "cloudwatch"
    },
    "storage": {
      "used": 34.5,
      "available": 65.5,
      "status": "healthy",
      "source": "cloudwatch"
    }
  },
  "application_metrics": {
    "response_times": {
      "average": 42.3,
      "p95": 98.5,
      "target": 200.0,
      "status": "good",
      "source": "cloudwatch_logs"
    },
    "throughput": {
      "requests_per_second": 125.4,
      "source": "cloudwatch_logs"
    },
    "error_rates": {
      "current": 0.002,
      "target": 0.01,
      "status": "good",
      "source": "cloudwatch_logs"
    }
  },
  "database_metrics": {
    "connections": {
      "active": 12,
      "idle": 88,
      "total": 100,
      "max": 400,
      "utilization": 25.0,
      "status": "healthy",
      "source": "postgresql"
    },
    "query_performance": {
      "recent_queries": 156,
      "slow_queries_estimate": 0,
      "status": "optimal",
      "source": "agent_actions_table"
    }
  }
}

WebSocket Real-Time Streaming

Connect to WebSocket

const ws = new WebSocket('wss://pilot.owkai.app/api/analytics/ws/realtime/user@company.com');

ws.onopen = () => {
  console.log('Connected to real-time analytics');
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  if (data.type === 'connection') {
    console.log('Connection confirmed:', data.message);
  } else if (data.type === 'metrics_update') {
    console.log('Metrics update:', data.metrics);
    updateDashboard(data.metrics);
  }
};

WebSocket Message Types

{
  "type": "connection",
  "status": "connected",
  "message": "Real-time analytics connected for user@company.com",
  "timestamp": "2025-12-15T10:30:00Z"
}

{
  "type": "metrics_update",
  "timestamp": "2025-12-15T10:30:10Z",
  "metrics": {
    "active_websocket_connections": 24,
    "recent_actions_last_hour": 156,
    "high_risk_actions_last_hour": 3,
    "active_agents_last_hour": 12
  },
  "system_metrics": {
    "status": "live",
    "cpu_usage": 45.2,
    "memory_usage": 62.8,
    "response_time": 45.8
  },
  "data_quality": {
    "source": "real_database",
    "mock_data": false,
    "has_activity": true
  }
}

Debug Endpoints

Get Debug Data

curl "https://pilot.owkai.app/api/analytics/debug" \
  -H "Authorization: Bearer owkai_..."

Response:

[
  {
    "id": 12345,
    "agent_id": "finance-bot-001",
    "risk_level": "medium",
    "mitre_tactic": "Collection",
    "nist_control": "AC-3",
    "recommendation": "Monitor for bulk data access",
    "summary": "Database query on customers table"
  }
]

Multi-Tenant Isolation

All analytics endpoints filter by organization:

# Source: routes/analytics_routes.py:55
# All queries include organization_id filter
daily_actions = db.execute(text("""
    SELECT DATE(timestamp) as date, COUNT(*) as count
    FROM agent_actions
    WHERE timestamp >= :start_date
      AND risk_level IN ('high', 'critical')
      AND organization_id = :org_id
    GROUP BY DATE(timestamp)
    ORDER BY DATE(timestamp)
"""), {"start_date": seven_days_ago, "org_id": org_id}).fetchall()

SDK Integration

from ascend import AscendClient

client = AscendClient(api_key="owkai_...")

# Get trend data
trends = client.analytics.get_trends()
print(f"High-risk actions today: {trends['high_risk_actions_by_day'][-1]['count']}")

# Get executive dashboard
dashboard = client.analytics.get_executive_dashboard()
print(f"Platform health: {dashboard['executive_kpis']['platform_health']['score']}%")

# Get predictions (if available)
predictions = client.analytics.get_predictions()
if predictions['status'] == 'active':
    for forecast in predictions['risk_forecast']:
        print(f"{forecast['date']}: {forecast['predicted_high_risk']} high-risk actions")

Best Practices

1. Use Real-Time for Operations

# Check real-time metrics for operational awareness
metrics = client.analytics.get_realtime_metrics()
if metrics['real_time_overview']['recent_high_risk_actions'] > 10:
    alert_security_team()

2. Executive Dashboard for Leadership

# Generate weekly executive reports
dashboard = client.analytics.get_executive_dashboard()
generate_pdf_report(dashboard)

3. Leverage Predictions

# Proactive risk management
predictions = client.analytics.get_predictions()
if predictions['status'] == 'active':
    for anomaly in predictions['anomalies']:
        if anomaly['severity'] == 'high':
            investigate_anomaly(anomaly)

4. WebSocket for Dashboards

// Real-time dashboard updates
const ws = connectToAnalytics();
ws.onmessage = (event) => {
  updateDashboardWidgets(JSON.parse(event.data));
};

Next Steps

Audit Logging — Track all events
Compliance — Generate compliance reports
Risk Assessment — Configure risk scoring

Document Version: 1.0.0 | Last Updated: December 2025

Overview​

Analytics Architecture​

Real-Time Metrics​

Get Trend Data​

Real-Time Overview​

Executive Dashboard​

Get Executive KPIs​

Predictive Analytics​

Get Predictions​

System Performance​

Get Performance Metrics​

WebSocket Real-Time Streaming​

Connect to WebSocket​

WebSocket Message Types​

Debug Endpoints​

Get Debug Data​

Multi-Tenant Isolation​

SDK Integration​

Best Practices​

1. Use Real-Time for Operations​

2. Executive Dashboard for Leadership​

3. Leverage Predictions​

4. WebSocket for Dashboards​

Next Steps​

Overview

Analytics Architecture

Real-Time Metrics

Get Trend Data

Real-Time Overview

Executive Dashboard

Get Executive KPIs

Predictive Analytics

Get Predictions

System Performance

Get Performance Metrics

WebSocket Real-Time Streaming

Connect to WebSocket

WebSocket Message Types

Debug Endpoints

Get Debug Data

Multi-Tenant Isolation

SDK Integration

Best Practices

1. Use Real-Time for Operations

2. Executive Dashboard for Leadership

3. Leverage Predictions

4. WebSocket for Dashboards

Next Steps