# taiji-AI-PAD API 接口文档 - 监控功能

**版本**: v2.0  
**创建时间**: 2025年12月23日  
**最后更新**: 2025年12月23日

---

## 📋 目录

1. [概述](#概述)
2. [基础信息](#基础信息)
3. [监控API端点](#监控api端点)
4. [请求/响应示例](#请求响应示例)
5. [错误处理](#错误处理)
6. [集成示例](#集成示例)

---

## 1. 概述

本文档描述了 taiji-AI-PAD 平台监控功能的 API 接口。监控功能提供系统健康检查、性能指标、资源使用、服务统计、性能趋势和系统告警等功能。

### 1.1 功能特性

- ✅ 系统健康检查
- ✅ 实时性能指标（CPU、内存、磁盘）
- ✅ 服务统计信息（Agent、执行、工具、用户）
- ✅ 性能趋势分析
- ✅ 系统告警
- ✅ 监控仪表板（聚合数据）

### 1.2 监控指标

- **系统资源**: CPU使用率、内存使用、磁盘使用
- **服务指标**: 活跃Agent数、执行次数、成功率、平均响应时间
- **业务指标**: 日活用户、EU消耗、成本统计
- **告警信息**: 资源告警、服务告警

---

## 2. 基础信息

### 2.1 基础URL

```
http://localhost:8002
```

### 2.2 认证方式

当前版本无需认证，未来版本将支持 JWT Token 认证。

### 2.3 响应格式

所有API响应均为 JSON 格式，使用 UTF-8 编码。

### 2.4 HTTP状态码

| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 500 | 服务器内部错误 |

---

## 3. 监控API端点

### 3.1 系统健康检查

#### GET /health

获取系统健康状态。

**请求参数**: 无

**响应示例**:
```json
{
  "status": "healthy",
  "timestamp": "2025-12-23T07:30:00.000000",
  "services": {
    "database": "healthy",
    "redis": "healthy",
    "nats": "healthy"
  }
}
```

**响应字段说明**:
- `status`: 系统整体状态 (`healthy`, `degraded`, `unhealthy`)
- `timestamp`: 检查时间戳
- `services`: 各服务健康状态

---

### 3.2 系统性能指标

#### GET /api/v1/monitoring/metrics

获取系统实时性能指标。

**请求参数**: 无

**响应示例**:
```json
{
  "timestamp": "2025-12-23T07:30:00.000000",
  "system": {
    "cpu_usage_percent": 15.5,
    "memory_usage_percent": 45.2,
    "memory_used_mb": 2048.5,
    "memory_total_mb": 4096.0,
    "disk_usage_percent": 32.1,
    "disk_used_gb": 128.5,
    "disk_total_gb": 400.0
  },
  "services": {
    "active_agents": 10,
    "total_executions_24h": 1250,
    "success_rate_percent": 98.5,
    "avg_execution_time_ms": 125.5,
    "daily_active_users": 25
  },
  "billing": {
    "total_eu_consumed_24h": 1250.5,
    "total_cost_24h": 12.50
  }
}
```

**响应字段说明**:
- `system`: 系统资源使用情况
  - `cpu_usage_percent`: CPU使用率（%）
  - `memory_usage_percent`: 内存使用率（%）
  - `memory_used_mb`: 已使用内存（MB）
  - `memory_total_mb`: 总内存（MB）
  - `disk_usage_percent`: 磁盘使用率（%）
  - `disk_used_gb`: 已使用磁盘（GB）
  - `disk_total_gb`: 总磁盘空间（GB）
- `services`: 服务指标（过去24小时）
  - `active_agents`: 活跃Agent数量
  - `total_executions_24h`: 总执行次数
  - `success_rate_percent`: 成功率（%）
  - `avg_execution_time_ms`: 平均执行时间（毫秒）
  - `daily_active_users`: 日活用户数
- `billing`: 计费统计（过去24小时）
  - `total_eu_consumed_24h`: 总EU消耗
  - `total_cost_24h`: 总成本

---

### 3.3 服务统计信息

#### GET /api/v1/monitoring/stats

获取服务统计信息。

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| service | string | 否 | 服务类型，可选值: `all`, `agents`, `executions`, `tools`, `users`，默认: `all` |

**请求示例**:
```
GET /api/v1/monitoring/stats?service=agents
```

**响应示例**:
```json
{
  "timestamp": "2025-12-23T07:30:00.000000",
  "stats": {
    "agents": {
      "total": 50,
      "active": 45,
      "inactive": 5,
      "avg_executions": 125.5,
      "avg_success_rate": 98.2
    },
    "executions": {
      "total_7d": 8750,
      "completed": 8600,
      "failed": 100,
      "running": 50,
      "avg_time_ms": 125.5,
      "total_eu": 8750.5
    },
    "tools": {
      "total": 20,
      "active": 18,
      "total_calls": 12500,
      "avg_success_rate": 99.5,
      "avg_response_time_ms": 50.2
    },
    "users": {
      "total": 100,
      "active": 95,
      "admins": 5
    }
  }
}
```

**响应字段说明**:
- `agents`: Agent统计
  - `total`: 总Agent数
  - `active`: 活跃Agent数
  - `inactive`: 非活跃Agent数
  - `avg_executions`: 平均执行次数
  - `avg_success_rate`: 平均成功率
- `executions`: 执行统计（过去7天）
  - `total_7d`: 总执行次数
  - `completed`: 成功完成数
  - `failed`: 失败数
  - `running`: 运行中数
  - `avg_time_ms`: 平均执行时间（毫秒）
  - `total_eu`: 总EU消耗
- `tools`: 工具统计
  - `total`: 总工具数
  - `active`: 活跃工具数
  - `total_calls`: 总调用次数
  - `avg_success_rate`: 平均成功率
  - `avg_response_time_ms`: 平均响应时间（毫秒）
- `users`: 用户统计
  - `total`: 总用户数
  - `active`: 活跃用户数
  - `admins`: 管理员数

---

### 3.4 性能趋势数据

#### GET /api/v1/monitoring/trends

获取性能趋势数据。

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| metric | string | 否 | 指标类型，可选值: `executions`, `eu_consumption`，默认: `executions` |
| period | string | 否 | 时间范围，可选值: `24h`, `7d`, `30d`，默认: `24h` |
| interval | string | 否 | 时间间隔，可选值: `1h`, `6h`, `1d`，默认: `1h` |

**请求示例**:
```
GET /api/v1/monitoring/trends?metric=executions&period=7d&interval=6h
```

**响应示例** (metric=executions):
```json
{
  "metric": "executions",
  "period": "7d",
  "interval": "6h",
  "data": [
    {
      "timestamp": "2025-12-23T00:00:00",
      "count": 125,
      "avg_time_ms": 120.5,
      "success_rate": 98.5
    },
    {
      "timestamp": "2025-12-23T06:00:00",
      "count": 150,
      "avg_time_ms": 125.2,
      "success_rate": 99.0
    }
  ]
}
```

**响应示例** (metric=eu_consumption):
```json
{
  "metric": "eu_consumption",
  "period": "24h",
  "interval": "1h",
  "data": [
    {
      "timestamp": "2025-12-23T00:00:00",
      "eu_consumed": 50.5,
      "cost": 0.50
    },
    {
      "timestamp": "2025-12-23T01:00:00",
      "eu_consumed": 52.3,
      "cost": 0.52
    }
  ]
}
```

**响应字段说明**:
- `metric`: 指标类型
- `period`: 时间范围
- `interval`: 时间间隔
- `data`: 趋势数据数组
  - `timestamp`: 时间点
  - `count`: 执行次数（executions指标）
  - `avg_time_ms`: 平均执行时间（executions指标）
  - `success_rate`: 成功率（executions指标）
  - `eu_consumed`: EU消耗（eu_consumption指标）
  - `cost`: 成本（eu_consumption指标）

---

### 3.5 系统告警

#### GET /api/v1/monitoring/alerts

获取系统告警信息。

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| severity | string | 否 | 严重程度过滤，可选值: `warning`, `critical`, `info` |

**请求示例**:
```
GET /api/v1/monitoring/alerts?severity=critical
```

**响应示例**:
```json
{
  "timestamp": "2025-12-23T07:30:00.000000",
  "alerts": [
    {
      "severity": "warning",
      "type": "high_cpu",
      "message": "CPU使用率过高: 85.5%",
      "timestamp": "2025-12-23T07:29:00.000000"
    },
    {
      "severity": "critical",
      "type": "low_disk",
      "message": "磁盘空间不足: 92.1%",
      "timestamp": "2025-12-23T07:25:00.000000"
    }
  ],
  "count": 2
}
```

**响应字段说明**:
- `timestamp`: 查询时间
- `alerts`: 告警列表
  - `severity`: 严重程度 (`warning`, `critical`, `info`)
  - `type`: 告警类型 (`high_cpu`, `high_memory`, `low_disk`, `high_failure_rate`)
  - `message`: 告警消息
  - `timestamp`: 告警时间
- `count`: 告警总数

**告警类型说明**:
- `high_cpu`: CPU使用率 > 80%
- `high_memory`: 内存使用率 > 85%
- `low_disk`: 磁盘使用率 > 90%
- `high_failure_rate`: 过去1小时内失败执行 > 10次

---

### 3.6 监控仪表板

#### GET /api/v1/monitoring/dashboard

获取监控仪表板数据（聚合所有监控信息）。

**请求参数**: 无

**响应示例**:
```json
{
  "timestamp": "2025-12-23T07:30:00.000000",
  "health": {
    "status": "healthy",
    "timestamp": "2025-12-23T07:30:00.000000",
    "uptime_seconds": 86400,
    "services": {
      "database": "healthy",
      "redis": "healthy",
      "nats": "healthy"
    }
  },
  "metrics": {
    "timestamp": "2025-12-23T07:30:00.000000",
    "system": {
      "cpu_usage_percent": 15.5,
      "memory_usage_percent": 45.2,
      "disk_usage_percent": 32.1
    },
    "services": {
      "active_agents": 10,
      "total_executions_24h": 1250,
      "success_rate_percent": 98.5
    },
    "billing": {
      "total_eu_consumed_24h": 1250.5,
      "total_cost_24h": 12.50
    }
  },
  "stats": {
    "agents": {
      "total": 50,
      "active": 45
    },
    "executions": {
      "total_7d": 8750,
      "completed": 8600
    },
    "tools": {
      "total": 20,
      "active": 18
    },
    "users": {
      "total": 100,
      "active": 95
    }
  },
  "alerts": {
    "items": [
      {
        "severity": "warning",
        "type": "high_cpu",
        "message": "CPU使用率过高: 85.5%",
        "timestamp": "2025-12-23T07:29:00.000000"
      }
    ],
    "count": 1,
    "critical_count": 0,
    "warning_count": 1
  }
}
```

**响应字段说明**:
- `health`: 系统健康状态
- `metrics`: 系统性能指标
- `stats`: 服务统计信息
- `alerts`: 系统告警
  - `items`: 告警列表
  - `count`: 告警总数
  - `critical_count`: 严重告警数
  - `warning_count`: 警告告警数

---

## 4. 请求/响应示例

### 4.1 cURL 示例

#### 获取系统性能指标
```bash
curl -X GET "http://localhost:8002/api/v1/monitoring/metrics"
```

#### 获取Agent统计
```bash
curl -X GET "http://localhost:8002/api/v1/monitoring/stats?service=agents"
```

#### 获取执行趋势（7天，6小时间隔）
```bash
curl -X GET "http://localhost:8002/api/v1/monitoring/trends?metric=executions&period=7d&interval=6h"
```

#### 获取严重告警
```bash
curl -X GET "http://localhost:8002/api/v1/monitoring/alerts?severity=critical"
```

#### 获取监控仪表板
```bash
curl -X GET "http://localhost:8002/api/v1/monitoring/dashboard"
```

### 4.2 Python 示例

```python
import httpx
import asyncio

async def get_monitoring_data():
    base_url = "http://localhost:8002"
    
    async with httpx.AsyncClient() as client:
        # 获取系统指标
        metrics = await client.get(f"{base_url}/api/v1/monitoring/metrics")
        print("系统指标:", metrics.json())
        
        # 获取服务统计
        stats = await client.get(f"{base_url}/api/v1/monitoring/stats?service=all")
        print("服务统计:", stats.json())
        
        # 获取性能趋势
        trends = await client.get(
            f"{base_url}/api/v1/monitoring/trends",
            params={"metric": "executions", "period": "24h", "interval": "1h"}
        )
        print("性能趋势:", trends.json())
        
        # 获取告警
        alerts = await client.get(f"{base_url}/api/v1/monitoring/alerts")
        print("系统告警:", alerts.json())
        
        # 获取监控仪表板
        dashboard = await client.get(f"{base_url}/api/v1/monitoring/dashboard")
        print("监控仪表板:", dashboard.json())

asyncio.run(get_monitoring_data())
```

### 4.3 JavaScript 示例

```javascript
const baseUrl = 'http://localhost:8002';

// 获取系统指标
async function getMetrics() {
  const response = await fetch(`${baseUrl}/api/v1/monitoring/metrics`);
  const data = await response.json();
  console.log('系统指标:', data);
}

// 获取服务统计
async function getStats(service = 'all') {
  const response = await fetch(`${baseUrl}/api/v1/monitoring/stats?service=${service}`);
  const data = await response.json();
  console.log('服务统计:', data);
}

// 获取性能趋势
async function getTrends(metric = 'executions', period = '24h', interval = '1h') {
  const url = new URL(`${baseUrl}/api/v1/monitoring/trends`);
  url.searchParams.append('metric', metric);
  url.searchParams.append('period', period);
  url.searchParams.append('interval', interval);
  
  const response = await fetch(url);
  const data = await response.json();
  console.log('性能趋势:', data);
}

// 获取告警
async function getAlerts(severity = null) {
  let url = `${baseUrl}/api/v1/monitoring/alerts`;
  if (severity) {
    url += `?severity=${severity}`;
  }
  
  const response = await fetch(url);
  const data = await response.json();
  console.log('系统告警:', data);
}

// 获取监控仪表板
async function getDashboard() {
  const response = await fetch(`${baseUrl}/api/v1/monitoring/dashboard`);
  const data = await response.json();
  console.log('监控仪表板:', data);
}

// 使用示例
getMetrics();
getStats('agents');
getTrends('executions', '7d', '6h');
getAlerts('critical');
getDashboard();
```

---

## 5. 错误处理

### 5.1 错误响应格式

```json
{
  "detail": "错误描述信息"
}
```

### 5.2 常见错误

| HTTP状态码 | 错误类型 | 说明 |
|-----------|---------|------|
| 400 | Bad Request | 请求参数错误 |
| 500 | Internal Server Error | 服务器内部错误 |

### 5.3 错误处理示例

```python
import httpx

async def get_metrics_safe():
    try:
        async with httpx.AsyncClient() as client:
            response = await client.get("http://localhost:8002/api/v1/monitoring/metrics")
            response.raise_for_status()
            return response.json()
    except httpx.HTTPStatusError as e:
        print(f"HTTP错误: {e.response.status_code}")
        print(f"错误信息: {e.response.text}")
    except Exception as e:
        print(f"其他错误: {e}")
```

---

## 6. 集成示例

### 6.1 实时监控仪表板

```python
import asyncio
import httpx
from datetime import datetime

async def update_dashboard():
    """每30秒更新一次监控仪表板"""
    base_url = "http://localhost:8002"
    
    while True:
        try:
            async with httpx.AsyncClient() as client:
                response = await client.get(f"{base_url}/api/v1/monitoring/dashboard")
                data = response.json()
                
                # 显示关键指标
                print(f"\n[{datetime.now()}] 监控仪表板")
                print(f"系统状态: {data['health']['status']}")
                print(f"CPU使用率: {data['metrics']['system']['cpu_usage_percent']:.1f}%")
                print(f"内存使用率: {data['metrics']['system']['memory_usage_percent']:.1f}%")
                print(f"活跃Agent: {data['metrics']['services']['active_agents']}")
                print(f"24小时执行次数: {data['metrics']['services']['total_executions_24h']}")
                print(f"成功率: {data['metrics']['services']['success_rate_percent']:.2f}%")
                print(f"告警数量: {data['alerts']['count']} (严重: {data['alerts']['critical_count']})")
                
        except Exception as e:
            print(f"获取监控数据失败: {e}")
        
        await asyncio.sleep(30)

# 运行监控
asyncio.run(update_dashboard())
```

### 6.2 告警通知

```python
import httpx
import asyncio

async def check_alerts():
    """检查系统告警并发送通知"""
    base_url = "http://localhost:8002"
    
    async with httpx.AsyncClient() as client:
        # 获取严重告警
        response = await client.get(f"{base_url}/api/v1/monitoring/alerts?severity=critical")
        alerts = response.json()
        
        if alerts['count'] > 0:
            print(f"⚠️ 发现 {alerts['count']} 个严重告警:")
            for alert in alerts['alerts']:
                print(f"  - {alert['message']} ({alert['type']})")
                # 这里可以添加通知逻辑（邮件、短信、Slack等）
        
        # 获取警告告警
        response = await client.get(f"{base_url}/api/v1/monitoring/alerts?severity=warning")
        alerts = response.json()
        
        if alerts['count'] > 0:
            print(f"⚠️ 发现 {alerts['count']} 个警告:")
            for alert in alerts['alerts']:
                print(f"  - {alert['message']} ({alert['type']})")

asyncio.run(check_alerts())
```

---

## 7. 最佳实践

### 7.1 监控频率建议

- **系统指标**: 每30秒-1分钟查询一次
- **服务统计**: 每5-10分钟查询一次
- **性能趋势**: 根据需求，建议每1小时查询一次
- **系统告警**: 每1-5分钟检查一次

### 7.2 性能优化

- 使用 `/api/v1/monitoring/dashboard` 端点获取聚合数据，减少请求次数
- 对于趋势数据，合理选择时间范围和间隔，避免查询过大数据集
- 使用缓存机制，避免频繁查询数据库

### 7.3 告警阈值建议

- **CPU使用率**: > 80% 警告，> 90% 严重
- **内存使用率**: > 85% 警告，> 95% 严重
- **磁盘使用率**: > 85% 警告，> 90% 严重
- **失败率**: > 5% 警告，> 10% 严重

---

## 8. 更新日志

### v2.0 (2025-12-23)
- ✅ 新增系统性能指标API
- ✅ 新增服务统计信息API
- ✅ 新增性能趋势数据API
- ✅ 新增系统告警API
- ✅ 新增监控仪表板API
- ✅ 优化健康检查API

---

**文档版本**: v2.0  
**最后更新**: 2025年12月23日  
**维护者**: taiji-AI-PAD 开发团队