Netis/TokenScope

# TokenScope **网络层面的 LLM API 可观测性。** 一个被动的、提供者端的分析器，可将 LLM API 流量转化为结构化的性能、成本和行为遥测数据——无需在请求路径中引入 SDK、sidecar 或代理。  ## 它的功能 TokenScope 读取 LLM API 流量（TLS 解密后，在推理主机或 TLS 终结器的下游），解码协议——包括 SSE 流式传输和分块编码——通过缝合多次调用交互来重建 **agent turns**，并通过内置的 Web 控制台发出可查询的指标和每次调用的详细信息。 ``` NIC / .pcap file / cloud-probe (ZMQ) │ ▼ capture → flow dispatcher (hash by 5-tuple) │ ▼ N parallel workers: HTTP/SSE parse → wire-API detection → semantic extraction │ ▼ turn tracker + metrics aggregator + storage sink │ ▼ DuckDB ─── REST API ─── React console (localhost:3000) ``` 同一连接的数据包总是会分发到同一个 worker，因此解析状态是本地且无锁的。多个独立的 pipeline 可以并行运行——例如，将低延迟的本地抓包与突发性的 cloud-probe 入站流量隔离开来。 ## 为什么不使用 SDK / 代理 / OpenTelemetry？ | 方案 | 在请求路径中 | 需要客户端配合 | 查看完整正文 | | -------------------------- | :-------------: | :----------------------: | :--------------: | | SDK 插桩 | 是 | 每个客户端都必须 | 是 | | 反向代理 (LiteLLM …) | 是 | 客户端指向它 | 是 | | 服务端的 OpenTelemetry | 是 | 服务端必须发出 | 部分 | | **TokenScope** | **否** | **否** | **是**¹ | ¹ 仅限已终止 TLS 的流量——TokenScope 查看的是明文 HTTP。请将其安装在流量已解密的位置：推理主机上、TLS 终结器之后，或者通过 [cloud-probe](https://github.com/Netis/cloud-probe) 从 SPAN/TAP 接入点输入。 这种权衡是坦率的：您放弃了跨集群的客户端追踪，换来的是一条单一的被动证据链，当观察者发生故障时它不会中断调用，并且不需要被观察的工作负载提供任何配合。 ## v0.1 中包含的内容 **入站流量** - 在活动接口上的 libpcap 抓包（BPF 过滤） - 从 `.pcap` 文件回放（任何速度） - 通过 ZMQ 接收来自 [cloud-probe](https://github.com/Netis/cloud-probe) 的数据，用于您无法直接安装的主机 **线路 API 解码器** - OpenAI Chat Completions (`/v1/chat/completions`) - OpenAI Responses (`/v1/responses`) - Anthropic Messages (`/v1/messages`) 这涵盖了 OpenAI 直连、Azure OpenAI、Anthropic 直连、AWS Bedrock / GCP Vertex（Anthropic 线路协议）以及任何兼容 OpenAI 的本地服务器——vLLM、Ollama、llama.cpp 的 server、LM Studio 等。Gemini 的原生 API 尚未被解码。 **Agent turn 重建**，带有针对 **Claude CLI** (Claude Code) 和 **OpenAI Codex CLI** 的命名配置文件，一个适用于其他情况的通用配置文件，以及一个实验性的 OpenClaw 配置文件。Turns 将多次调用的 agent 交互（tool calls、后续操作）缝合为一个单一的可寻址单元——上面的截图就是这样一个 turn。 **每次调用的深入下钻**——每个 LLM 调用都捕获了结构化的请求/响应*以及*原始正文。停滞的 tool calls、格式错误的 prompt、意外的 token 计数：证据就在页面上，无需重新运行。  **指标**（滑动窗口，按 LLM 调用划分）：TTFT · E2E 延迟 · TPOT · token 吞吐量 · 调用率 · 活跃调用数 · 调用错误率 · prompt 缓存命中率。有关各项的含义和原因，请参阅[词汇表](docs/glossary.md)。 **存储**在 DuckDB 中（默认，嵌入式，单文件），开箱即支持每表保留策略。可插拔的后端 trait——PostgreSQL 和 ClickHouse 已设计但尚未接入。 **控制台**位于 `http://localhost:3000`：概览 · 性能 · 流量 · 模型 · 错误 · LLM 调用（带有完整的请求/响应正文下钻）· 原始 HTTP 交换 · Agent turns · Agent 会话 · pipeline 健康状况调试视图。

更多控制台截图

   

**分发**：为 Linux musl (x86_64 + aarch64) 和 macOS (Intel + Apple Silicon) 预构建的静态二进制文件。Web 控制台**嵌入在二进制文件中**——单一构件，无需单独部署前端。 ## 适用人群 - **LLM 提供商运维及本地推理运营商**——根据基本事实而非各个 SDK 的报告来衡量您的集群 - **Agent 开发者**——无需修改 agent 即可调试停滞的 tool calls 并检测 agent 循环 - **FinOps 及工程经理**——根据真实流量而非周期性导出，将支出归因到各个团队/仓库/项目 - **合规与安全**——一次捕获的关于线路上传输内容的证据链 ## 快速开始 ``` # 安装 (Linux/macOS, 无 sudo, 用户级) curl -fsSL https://raw.githubusercontent.com/Netis/TokenScope/main/install.sh \ | INSTALL_DIR="$HOME/.local" sh # Linux: 为 binary 授予 capture 权限 (运行时无 sudo) sudo setcap cap_net_raw,cap_net_admin=eip ~/.local/bin/tokenscope # 从 live interface 进行 capture tokenscope -i eth0 --bpf-filter "tcp port 8000" # ...或重放 pcap (无需权限) tokenscope --pcap-file capture.pcap --no-retention ``` 然后打开 。 在 pcap 回放完成后，进程会保持 API/控制台可用，以便您浏览结果——按 Ctrl+C 退出，或者对于在 pipeline 排空后立即退出的批处理/CI 用法，传入 `--exit-after-drain` 参数。 有关 systemd 部署、capability 选项、macOS BPF 设置和卸载的信息，请参阅 [docs/install.md](docs/install.md)。 ## 文档 - [安装](docs/install.md) — 一行安装器、systemd、capabilities - [配置](docs/configure.md) — pipelines、来源、存储、保留、BPF 过滤器 - [词汇表](docs/glossary.md) — 每个指标的含义 - [架构](docs/design/01-architecture.md) — pipeline 设计与权衡 - [使命](docs/mission.md) — 长期愿景与 BPC 背景 ## 路线图 v0.1 的表现是基础层（Ops 用例）。正在开发中： - **存储** — PostgreSQL 和 ClickHouse 后端（schemas 已设计完成） - **线路 API** — Gemini 原生 API，更多特定于提供商的扩展 有关完整的发展阶梯，请参见 [docs/mission.md](docs/mission.md)。 ## 项目起源 TokenScope 是 **Netis Systems** 的一个开源项目，Netis Systems 是一家位于深圳的 NPM/BPC 供应商（成立于 2000 年），在为受监管企业提供数据包证据可观测性方面拥有二十年的经验。该项目的目标是**供应商中立**：对任何操作 LLM API 流量的人都有用，而不仅仅是 Netis 的客户。[cloud-probe](https://github.com/Netis/cloud-probe) 是一个受支持的入站来源，而非硬性要求。 ## 许可证 [Apache 2.0](LICENSE)。

标签：AIOps, AI基础设施, Anthropic, API性能监控, API网关监控, Azure OpenAI, CIS基准, DLL 劫持, DuckDB, Gemini, LLM可观测性, LLM评估, Observability, Ollama, OpenAI, pcap, React, REST API, SSE解析, Syscalls, Token吞吐量, TPOT, TTFT, vLLM, Web控制台, ZMQ, 云原生监控, 代理端部署, 内存规避, 协议分析, 可视化界面, 多并发处理, 大语言模型, 大语言模型蜜罐, 成本分析, 抓包工具, 旁路监控, 无SDK, 无Sidecar, 无锁设计, 智能体追踪, 服务管理, 权限提升, 流式数据解码, 流量解析, 端到端延迟, 网络嗅探器, 网络探针, 网络流量分析, 自动化侦查, 遥测, 防御绕过, 零侵入