API Analytics：轻量级、零配置的跨语言 API 监控方案
API Analytics
一个简单易用的 API 分析解决方案，可用于监控项目中 API 请求、响应、错误等指标，并提供可视化的仪表盘。
目前兼容以下框架：
- Python: FastAPI、Flask、Django 和 Tornado
- Node.js: Express、Fastify、Koa 和 Hono
- Go: Gin、Echo、Fiber 和 Chi
- Rust: Actix、Axum 和 Rocket
- Ruby: Rails 和 Sinatra
- C#: ASP.NET Core
项目地址： API Analytics
快速开始
1. 生成 API 密钥
数据收集、分析及 dashboard 指标展示都托管在作者的服务器上，当然也可以选择自托管（参考下文）。
如果懒得自己部署或者只想快速体验一下，可访问 apianalytics.dev/generate 一键生成一个专属 API 密钥，后面访问 API Analytics 仪表盘和日志数据时需要用到它。
2. 为项目 API 添加中间件
为项目 API 添加轻量级中间件。由于大部分数据处理都在 API Analytics 服务器端完成，对项目 API 性能影响极小。
FastAPI
pip install api-analytics[fastapi]import uvicorn
from fastapi import FastAPI
from api_analytics.fastapi import Analytics
app = FastAPI()
app.add_middleware(Analytics, api_key=<API-KEY>) # Add middleware
@app.get('/')
async def root():
return {'message': 'Hello, World!'}
if __name__ == "__main__":
uvicorn.run("app:app", reload=True)Hono
npm install node-api-analyticsimport { Hono } from 'hono';
import { serve } from '@hono/node-server';
import { honoAnalytics } from 'node-api-analytics';
const app = new Hono();
app.use('*', honoAnalytics(<API-KEY>));
app.get('/', (c) => c.text('Hello, world!'));
serve(app, (info) => {
console.log(`Server listening at http://localhost:${info.port}`);
});Gin
go get -u github.com/tom-draper/api-analytics/analytics/go/ginpackage main
import (
"net/http"
"github.com/gin-gonic/gin"
analytics "github.com/tom-draper/api-analytics/analytics/go/gin"
)
func root(c * gin.Context) {
data := map[string]string{
"message": "Hello, World!",
}
c.JSON(http.StatusOK, data)
}
func main() {
r := gin.Default()
r.Use(analytics.Analytics(<API-KEY>)) // Add middleware
r.GET("/", root)
r.Run(":8080")
}其他框架请参考官方文档。
3. 查看分析数据
项目 API 现在将记录并存储所有路由的传入请求数据。可以通过两种方式查看记录的数据：
- 通过仪表盘上的可视化图表和统计数据
- 通过数据 API 直接访问
同一个 API 密钥可用于多个 API，但所有请求都会显示在同一个仪表盘中。建议为每个 API 服务器生成一个新的 API 密钥。
仪表盘
访问 apianalytics.dev/dashboard 并粘贴 API 密钥以访问仪表盘。
Demo：apianalytics.dev/dashboard/demo
数据 API
可以从数据 API 获取原始记录的请求数据。只需向 https://apianalytics-server.com/api/data 发送 GET 请求，并在请求头中将 API 密钥设置为 X-AUTH-TOKEN: <API-KEY>。
Python
import requests
response = requests.get("https://apianalytics-server.com/api/data", headers={
"X-AUTH-TOKEN": <API-KEY>
})
print(response.json())Node.js
fetch("https://apianalytics-server.com/api/data", {
headers: { "X-AUTH-TOKEN": <API-KEY> },
})
.then((response) => {
return response.json();
})
.then((data) => {
console.log(data);
});cURL
curl --header "X-AUTH-TOKEN: <API-KEY>" https://apianalytics-server.com/api/data参数
可以通过在请求中提供 URL 参数来过滤数据。
page- 页码，最大页面大小为 50,000（默认为 1）date- 请求发生的日期（YYYY-MM-DD）dateFrom- 请求发生日期范围的下限（YYYY-MM-DD）dateTo- 请求发生日期范围的上限（YYYY-MM-DD）hostname- 你的服务的主机名ipAddress- 客户端的 IP 地址status- 响应的状态码location- 客户端的双字符位置代码user_id- 自定义用户标识符（仅当配置中设置了get_user_id映射函数时相关）
示例：
curl --header "X-AUTH-TOKEN: <API-KEY>" https://apianalytics-server.com/api/data?page=3&dateFrom=2022-01-01&hostname=apianalytics.dev&status=200&user_id=b56cbd92-1168-4d7b-8d94-0418da207908客户端 ID 和隐私
默认情况下，API Analytics 会记录并存储对项目 API 发出的所有传入请求的客户端 IP 地址，并尽可能从每个 IP 地址推断位置（国家）。IP 地址在仪表盘中用作客户端识别的一种形式，以估算访问项目 API 的用户数量。
此行为可通过 API 中间件配置中定义的隐私级别进行控制。隐私级别从 0 到 2 共有三个级别。隐私级别为 1 将禁用 IP 地址存储，级别为 2 还将禁用位置推断，默认为 0 。
隐私级别：
0- 客户端 IP 地址用于推断位置，然后存储以进行用户识别。1- 客户端 IP 地址用于推断位置，然后丢弃。2- 永远不会访问客户端 IP 地址，也永远不会推断位置。
from fastapi import FastAPI
from api_analytics.fastapi import Analytics, Config
config = Config(privacy_level=2) # Disable IP storing and location inference
app = FastAPI()
app.add_middleware(Analytics, api_key=<API-KEY>, config=config) # Add middleware无论使用哪个隐私级别，你都可以选择通过在 API 中间件配置中提供映射函数来定义用户 ID 作为请求的函数。例如，你的服务可能需要在 X-AUTH-TOKEN 头字段中保存 API 密钥，用于识别你服务的用户。在仪表盘中，此自定义用户 ID 将与 IP 地址一起识别用户，或者根据设置的隐私级别作为替代方案。
from fastapi import FastAPI
from api_analytics.fastapi import Analytics, Config
config = Config(
get_user_id=lambda request: request.headers.get('X-AUTH-TOKEN', '')
)
app = FastAPI()
app.add_middleware(Analytics, api_key=<API-KEY>, config=config) # Add middleware数据删除
用户可以随时访问 apianalytics.dev/delete 并输入 API 密钥来删除与 API 密钥关联的所有存储数据。
如果 API 密钥 6 个月未活动或 3 个月内未记录请求，则其及其关联的记录请求数据将被自动删除。
主动监控
访问 apianalytics.dev/monitoring 并输入 API 密钥即可设置主动端点监控。服务器将定期 ping 选定的端点以监控正常运行时间和响应时间。
限制
为了保持服务持续免费可用，每个 API 密钥最多可以存储 100 万个请求。如果超出，旧请求将被新请求按时间顺序滚动替换。如果项目请求量特别大，还是建议尝试其他解决方案或查看自托管。
自托管
如上所述，如果有隐私及安全性考虑，可以按照指南自托管该项目。
请注意：自托管仍在进行测试、开发和进一步改进，可能还不是特别稳定，目前建议避免将自托管用于生产环境。
