# 使用统计和回调功能快速指南

## 📋 概述

本指南介绍如何使用 Tavily MCP 服务器的使用统计和回调反馈功能。

## 🚀 快速开始

### 1. 启用使用统计

在配置文件中添加环境变量：

```json
{
  "mcpServers": {
    "tavily-mcp": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "your-api-key-here",
        "USAGE_TRACKING_ENABLED": "true"
      }
    }
  }
}
```

### 2. 配置回调 Webhook（可选）

如果需要接收实时通知，添加 webhook URL：

```json
{
  "env": {
    "TAVILY_API_KEY": "your-api-key-here",
    "USAGE_TRACKING_ENABLED": "true",
    "USAGE_CALLBACK_URL": "https://your-webhook-url.com/tavily-usage",
    "USAGE_REPORT_INTERVAL": "3600",
    "USAGE_ALERT_THRESHOLD": "80"
  }
}
```

## 📊 功能说明

### 可获取的信息

#### ✅ 总请求数
- 累计 API 调用次数
- 成功和失败分类统计

#### ✅ 本月使用量
- 当前月份的请求数
- 月度统计数据

#### ✅ 每日使用趋势
- 按天统计的使用量
- 最近 90 天的数据

#### ✅ 配额剩余
- 通过 `tavily-quota-check` 工具查询
- 每个 API key 的配额状态

#### ✅ 使用统计分布
- 不同类型请求（search/extract/crawl/map）的分布
- 成功率和失败率

## 🛠️ 使用 MCP 工具

### 查询本地统计

```typescript
// 使用 tavily-usage-stats 工具
{
  "name": "tavily-usage-stats",
  "arguments": {
    "days": 30,    // 查询最近 30 天
    "months": 12   // 查询最近 12 个月
  }
}
```

**返回信息：**
```
=== Usage Statistics ===

Period: 2025-12-01T00:00:00Z to 2025-12-17T02:55:30Z
Total Requests: 1234
Successful: 1200 (97.24%)
Failed: 34 (2.76%)

--- Requests by Type ---
Search: 800
Extract: 300
Crawl: 100
Map: 34

--- Recent Daily Stats ---
2025-12-17:
  Total: 150 | Success: 145 | Failed: 5
  Search: 100 | Extract: 30 | Crawl: 15 | Map: 5
...
```

### 检查 API 配额

```typescript
// 使用 tavily-quota-check 工具
{
  "name": "tavily-quota-check",
  "arguments": {}
}
```

**返回信息：**
```
=== API Quota Status ===

API Key #1:
  Plan: Pro
  Usage: 9500 / 10000 (95.00%)
  Remaining: 500
  Billing Period: 2025-12-01 to 2025-12-31
  ⚠️  WARNING: Approaching quota limit!

API Key #2:
  Plan: Basic
  Usage: 500 / 1000 (50.00%)
  Remaining: 500
  Billing Period: 2025-12-01 to 2025-12-31
```

## 📡 Webhook 回调

### 回调事件类型

#### 1. 定期报告（periodic_report）

按配置的间隔发送统计报告。

```json
{
  "timestamp": "2025-12-17T02:55:30Z",
  "event": "periodic_report",
  "stats": {
    "totalRequests": 1234,
    "successfulRequests": 1200,
    "failedRequests": 34,
    "requestsByType": {
      "search": 800,
      "extract": 300,
      "crawl": 100,
      "map": 34
    },
    "dailyStats": [...],
    "monthlyStats": [...]
  }
}
```

#### 2. 错误激增告警（error_spike）

当错误率超过阈值时触发。

```json
{
  "timestamp": "2025-12-17T02:55:30Z",
  "event": "error_spike",
  "stats": {...},
  "alertDetails": {
    "message": "High error rate detected: 85.50%",
    "severity": "critical",
    "threshold": 80,
    "currentValue": 85.5
  }
}
```

#### 3. 配额告警（quota_alert）

当任何 API key 接近配额限制时触发。

```json
{
  "timestamp": "2025-12-17T02:55:30Z",
  "event": "quota_alert",
  "stats": {...},
  "quotaInfo": [
    {
      "api_key": "tvly-...",
      "plan": "Pro",
      "usage": {
        "requests": 9500,
        "requests_limit": 10000,
        "requests_remaining": 500
      },
      "billing_period": {
        "start": "2025-12-01",
        "end": "2025-12-31"
      }
    }
  ],
  "alertDetails": {
    "message": "1 API key(s) approaching quota limit",
    "severity": "warning"
  }
}
```

## 💾 本地数据存储

### 统计数据文件

默认保存在 `usage-stats.json`，包含：

```json
{
  "startDate": "2025-12-01T00:00:00Z",
  "lastUpdated": "2025-12-17T02:55:30Z",
  "totalRequests": 1234,
  "successfulRequests": 1200,
  "failedRequests": 34,
  "requestsByType": {
    "search": 800,
    "extract": 300,
    "crawl": 100,
    "map": 34
  },
  "dailyStats": [
    {
      "date": "2025-12-17",
      "total": 150,
      "success": 145,
      "failed": 5,
      "byType": {
        "search": 100,
        "extract": 30,
        "crawl": 15,
        "map": 5
      }
    }
  ],
  "monthlyStats": [
    {
      "month": "2025-12",
      "total": 1234,
      "success": 1200,
      "failed": 34,
      "byType": {
        "search": 800,
        "extract": 300,
        "crawl": 100,
        "map": 34
      },
      "dailyBreakdown": [...]
    }
  ],
  "recentCalls": [
    {
      "timestamp": 1734402930000,
      "type": "search",
      "apiKeyIndex": 0,
      "success": true,
      "responseTime": 1250
    }
  ]
}
```

### 数据保留策略

- **每日统计**：保留最近 90 天
- **月度统计**：保留最近 12 个月
- **最近调用记录**：保留最近 100 次调用

## ⚙️ 配置参数详解

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `USAGE_TRACKING_ENABLED` | boolean | `false` | 是否启用使用统计 |
| `USAGE_STATS_FILE` | string | `./usage-stats.json` | 统计数据存储路径 |
| `USAGE_CALLBACK_URL` | string | - | Webhook 回调 URL（可选） |
| `USAGE_REPORT_INTERVAL` | number | - | 定期报告间隔（秒） |
| `USAGE_ALERT_THRESHOLD` | number | `80` | 错误率告警阈值（0-100） |

## 🎯 使用场景

### 场景 1: 监控 API 使用情况

```json
{
  "env": {
    "USAGE_TRACKING_ENABLED": "true",
    "USAGE_STATS_FILE": "./stats/tavily-usage.json"
  }
}
```

定期使用 `tavily-usage-stats` 工具查询统计数据。

### 场景 2: 接收实时告警

```json
{
  "env": {
    "USAGE_TRACKING_ENABLED": "true",
    "USAGE_CALLBACK_URL": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
    "USAGE_ALERT_THRESHOLD": "70"
  }
}
```

当错误率超过 70% 时，自动发送告警到 Slack。

### 场景 3: 定期生成使用报告

```json
{
  "env": {
    "USAGE_TRACKING_ENABLED": "true",
    "USAGE_CALLBACK_URL": "https://your-api.com/tavily-reports",
    "USAGE_REPORT_INTERVAL": "86400"
  }
}
```

每 24 小时自动发送使用报告到指定 API。

### 场景 4: 监控配额使用

使用 `tavily-quota-check` 工具定期检查配额状态，配合告警功能在接近限制时自动通知。

## 🔍 故障排查

### 统计数据未保存

1. 检查 `USAGE_TRACKING_ENABLED` 是否为 `true`
2. 确认有写入权限到 `USAGE_STATS_FILE` 路径
3. 查看服务器日志输出

### 回调未触发

1. 确认 `USAGE_CALLBACK_URL` 配置正确
2. 检查 webhook URL 是否可访问
3. 查看日志中的回调错误信息

### 配额查询失败

1. 确认 API key 有效
2. 检查网络连接
3. 查看是否有 API 频率限制

## 📚 更多信息

- 完整文档：[README.md](./README.md)
- 多 Key 支持：[多KEY支持说明.md](./多KEY支持说明.md)
- 问题反馈：GitHub Issues

## 🎉 总结

使用统计和回调功能让您能够：

✅ 实时监控 API 使用情况  
✅ 跟踪每日和每月使用趋势  
✅ 接收配额告警避免服务中断  
✅ 分析不同类型请求的分布  
✅ 自动化使用报告和告警通知

启用这些功能，让您的 API 使用更加透明和可控！