API Analytics：轻量级、零配置的跨语言 API 监控方案

2025年11月26日1472 words, 8 min read
Authors
    API Analytics 仪表盘界面

    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-analytics

    import { 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/gin

    package 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 现在将记录并存储所有路由的传入请求数据。可以通过两种方式查看记录的数据：

    1. 通过仪表盘上的可视化图表和统计数据
    2. 通过数据 API 直接访问

    同一个 API 密钥可用于多个 API，但所有请求都会显示在同一个仪表盘中。建议为每个 API 服务器生成一个新的 API 密钥。

    仪表盘

    访问 apianalytics.dev/dashboard 并粘贴 API 密钥以访问仪表盘。

    Demo：apianalytics.dev/dashboard/demo

    Dashboard

    数据 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 选定的端点以监控正常运行时间和响应时间。

    Monitoring

    限制

    为了保持服务持续免费可用，每个 API 密钥最多可以存储 100 万个请求。如果超出，旧请求将被新请求按时间顺序滚动替换。如果项目请求量特别大，还是建议尝试其他解决方案或查看自托管。

    自托管

    如上所述，如果有隐私及安全性考虑，可以按照指南自托管该项目。

    请注意：自托管仍在进行测试、开发和进一步改进，可能还不是特别稳定，目前建议避免将自托管用于生产环境。