httpstat 结构化输出与 SLO 阈值诊断:单文件 curl 计时 CLI 的 Agent 友好化改造

原创2026-10-06 17:35:361,745 阅读
文章标签:开发工具

httpstat 结构化输出与 SLO 阈值诊断:单文件 curl 计时 CLI 的 Agent 友好化改造

httpstat 是一个将 curl(1) 计时统计可视化的单文件 Python CLI,本文基于仓库内 AGENTS.md 项目规划,系统梳理其 2.0 时代的现代化改造路径:从补齐类型标注、严格布尔解析等代码卫生工作,到 Phase 1 引入 --format 结构化输出(JSON v1 schema)、--slo 阈值检查、NO_COLOR 与 --save 等 Agent 友好能力。读完本文,你将掌握这套结构化输出与 SLO 诊断机制的完整设计、源码实现原理、测试验证方式,以及面向 AI Agent 的诊断 Skill 层设计思路。

一、项目现状:单文件 CLI 与现代化改造

1.1 单文件、零依赖的技术形态

httpstat 的全部核心逻辑收敛在单个文件 httpstat.py 中(AGENTS.md 记载约 370 行,当前版本实际约 575 行),要求 Python >= 3.9,版本号为 2.0.0(见 httpstat.py 的 __version__)。它本质上是 curl 的薄封装:调用 curl 的 -w 写入格式收集各阶段时间戳,再渲染出 DNS、TCP、TLS、服务端处理、内容传输的分段耗时图。

打包完全由 pyproject.toml 驱动(setuptools 后端,requires = <a href="https://link.gitcode.com/i/6210df7d494bef818b3ecf21602ce03f" target="_blank">"setuptools>=61", "wheel"]),setup.py 已删除;构建与发布使用 uv build / uv publish(见 [Makefile 的 build/publish 目标)。pyproject.toml 还声明了命令行入口 httpstat = "httpstat:main",并支持 Python 3.9 ~ 3.13 全部版本。

1.2 已完成的现代化工作

AGENTS.md 记录了以下已经落地的改造,均可在源码中直接印证:

  • 去除所有 Python 2 兼容代码:shebang 改为 #!/usr/bin/env python,并引入 from __future__ import annotations(httpstat.py);
  • 全量 f-string 与新式语法:字符串插值、类型标注全面启用,包括 Env 类的 @overload 声明(httpstat.py)与 NoReturn 标注(httpstat.py);
  • 严格布尔解析 parse_bool():替代原先 'true' in value.lower() 的宽松判断,只接受 1/true/yes/on 与 0/false/no/off 两组取值(httpstat.py);
  • 临时文件 try/finally 统一清理:body/header 临时文件在 finally 块中按需删除,不再泄漏(httpstat.py);
  • quit() 重命名为 _exit() 并标注 NoReturn,语义更清晰。

二、剩余技术债:改造的动机所在

AGENTS.md 把未解决的问题归为两类,这直接决定了 Phase 1 的方向:

A. 测试可靠性不足(高优先级)

  • 当时仅有 shell 端到端测试(httpstat_test.sh),强依赖公网与第三方站点行为(脚本开头会检查 gstatic.com/generate_204 与 http2.akamai.com 的可达性),CI/本地结果不稳定;
  • 缺少单元测试,核心逻辑——指标换算、区间计算、parse_bool——没有稳定的回归保障。

B. Agent 适配能力不足(中高优先级)

  • 当时的 JSON 输出(HTTPSTAT_METRICS_ONLY)缺少 schema version、状态码语义、错误结构、上下文元数据;
  • 缺少「可机器判断」的 SLO/阈值能力(例如总耗时超阈值即非 0 退出);
  • 输出模式较少,无法直接覆盖 Agent 常见流水线(JSONL、紧凑 JSON、纯错误对象)。

三、Phase 1 核心设计:--format 结构化输出与 JSON v1 schema

Phase 1(本轮实施)的目标是「结构化输出 + SLO」,AGENTS.md 给出了完整方案,源码与测试均已落地。

3.1 输出格式参数

新增 --format(-f)参数,可选值为 pretty | json | jsonl,默认 pretty 以兼容现有行为。参数解析由手写的 pop_arg() 完成(httpstat.py),它会从 sys.argv 列表中原地摘除 flag 及其值,再校验格式合法性(httpstat.py)。

旧环境变量 HTTPSTAT_METRICS_ONLY 保留兼容:当它为 true 且用户未显式指定 --format 时,等价于 --format json(httpstat.py)。两种输出模式的差异:

  • json:json.dumps(..., indent=2) 多行美化输出;
  • jsonl:紧凑单行 JSON,便于进入日志流水线逐行消费(见 httpstat.py)。

3.2 JSON v1 schema(最小集)

AGENTS.md 定义的最小 schema 如下,后续通过 schema_version 扩展:

{
  "schema_version": 1,
  "url": "...",
  "ok": true,
  "exit_code": 0,
  "response": {
    "status_line": "HTTP/2 200",
    "status_code": 200,
    "remote_ip": "...",
    "remote_port": "...",
    "headers": {"Content-Type": "application/json", "Server": "nginx", "...": "..."}
  },
  "timings_ms": {
    "dns": 5,
    "connect": 10,
    "tls": 15,
    "server": 50,
    "transfer": 20,
    "total": 100,
    "namelookup": 5,
    "initial_connect": 15,
    "pretransfer": 30,
    "starttransfer": 80
  },
  "speed": {
    "download_kbs": 1234.5,
    "upload_kbs": 0.0
  },
  "slo": {
    "pass": true,
    "violations": []
  }
}

该结构由 build_json_result() 统一构造(httpstat.py),可从源码确认各字段的取值逻辑:

  • response.status_line / status_code:从 -D 导出的响应头首行解析,兼容 HTTP/2 200 与 HTTP/1.1 301 Moved Permanently 两种格式;
  • response.headers:首行之后的 key: value 行解析为字典;
  • timings_ms:前五个字段(dns/connect/tls/server/transfer)是区间耗时(range),后五个字段(namelookup/initial_connect/pretransfer/starttransfer/total)是累计耗时(cumulative),单位均为毫秒;
  • speed.download_kbs / upload_kbs:由 curl 的字节/秒速度除以 1024 并保留一位小数;
  • slo:未指定 --slo 时为 null,指定后为 {pass, violations} 对象。

与之对应的单元测试见 tests/test_httpstat.py 的 TestBuildJsonResult(含 schema_version、响应字段、timings 映射、速度换算、HTTP/1.1 状态行、JSON 可序列化等用例)。

四、SLO 阈值检查:--slo、退出码 4 与违规输出

SLO(Service Level Objective)能力是 Phase 1 的另一根支柱,它让 httpstat 从「给人看」的工具升级为「可被脚本和 Agent 判定」的探针。

4.1 语法与支持的 key

单一参数 --slo key=value,...,例如 --slo total=500,connect=100,ttfb=200。支持的 key 及其到 curl 指标的映射,定义在 SLO_KEY_MAP(httpstat.py):

SLO key 映射的 curl 指标 衡量内容
dns time_namelookup DNS 解析耗时
connect time_connect DNS + TCP 建连
tls time_pretransfer DNS + TCP + TLS
ttfb time_starttransfer 首字节时间(TTFB)
total time_total 完整请求总耗时

所有阈值单位均为毫秒。

4.2 解析与校验

parse_slo()(httpstat.py)负责把 "total=500,connect=100" 解析为 {'total': 500, 'connect': 100},并在以下非法输入下以退出码 1 报错:

  • 空字符串或空的分段(Error: empty SLO spec);
  • 分段缺少 =(Error: invalid SLO spec ...);
  • key 不在 SLO_KEY_MAP 中(会列出合法 key);
  • value 不是整数或不是正整数。

对应测试 TestParseSlo 覆盖了全部这些非法分支,以及带空格输入 ' total = 500 , connect = 100 ' 会被 trim 后正确解析。

4.3 判定与退出码

check_slo()(httpstat.py)将每个 key 的实测毫秒值与阈值比较,actual > threshold 即记一次违规;恰好等于阈值不算违规(测试 test_exactly_at_threshold_passes 明确锁定该边界语义)。返回值是 (pass, violations),每个 violation 形如 {'key': ..., 'threshold_ms': ..., 'actual_ms': ...}。

在 main() 中,一旦 slo.pass 为 false,进程退出码变为 4。这一退出码语义在 httpstat_test.sh 中用 --slo total=1(1ms 阈值必然超标)断言 assert_exit 4 进行了 E2E 验证。

4.4 两种模式下的违规呈现

  • pretty 模式:在计时图输出末尾,用红色逐行标注 SLO VIOLATION: {key} = {actual}ms (threshold: {threshold}ms)(httpstat.py);
  • JSON 模式:违规出现在 slo 字段中,例如:
{
  "slo": {
    "pass": false,
    "violations": [
      { "key": "total", "threshold_ms": 500, "actual_ms": 823 }
    ]
  }
}

五、颜色控制:遵循 NO_COLOR 约定

Phase 1 明确了颜色控制策略:遵循 NO_COLOR 环境变量约定,只要该变量被设置(无论值是什么)即禁用所有 ANSI 颜色;同时不新增 --no-color 命令行参数,避免 flag 膨胀。

源码层面,模块级判定为 ISATTY = sys.stdout.isatty() and 'NO_COLOR' not in os.environ(httpstat.py),make_color() 在非 TTY 或设置了 NO_COLOR 时原样返回文本(httpstat.py)。E2E 测试「NO_COLOR disables ANSI escapes」验证输出中不存在 \x1b[ 转义序列;单元测试 TestNoColor 则同时覆盖了 NO_COLOR 设置与 ISATTY 开关两种路径。

六、Agent 友好细节:--save 与不设 --quiet 的取舍

  • --save <path>:将结果写入文件(httpstat.py、httpstat.py),适合多步 Agent 工作流复用结果;它不依赖 --format,pretty 模式下也会写出同结构的 JSON 文件(此时使用 indent=2)。E2E 测试会验证保存的文件可被 json.load 且 schema_version == 1。
  • 不另设 --quiet:因为 --format json 已天然抑制装饰文本,无需再引入一个功能重叠的 flag。

这两个决策体现了 AGENTS.md 反复强调的原则:保持命令行接口精简,避免 flag 膨胀。

七、源码级原理:从 curl 输出到结构化数据

7.1 时间单位换算

curl 通过 -w 格式串输出 JSON(httpstat.py)。curl 版本差异导致时间字段有两种表示方式:7.61.0 之前是秒(float),7.61.0 起是微秒(int)。main() 中据此换算为毫秒整数(httpstat.py):

if isinstance(v, float):
    d[k] = int(v * 1000)          # 秒 → 毫秒
elif isinstance(v, int):
    d[k] = int(v / 1000)          # 微秒 → 毫秒

7.2 区间(range)计算

五个累计时间戳经过差分得到各阶段独立耗时(httpstat.py):

range_dns       = time_namelookup
range_connection= time_connect - time_namelookup
range_ssl       = time_pretransfer - time_connect
range_server    = time_starttransfer - time_pretransfer
range_transfer  = time_total - time_starttransfer

这正是 pretty 模式计时图(https_template/http_template,httpstat.py)与 JSON timings_ms 前五个字段的数据来源。

7.3 curl 参数约束与语言环境

  • httpstat 内部已占用 -w、-D、-o、-s、-S,用户在 URL 后追加 curl 参数时这些选项会被拒绝(httpstat.py);
  • 子进程强制 LC_ALL=C(httpstat.py),确保时间戳解析不受区域设置影响——E2E 测试专门用 LC_ALL=ru_RU 验证过这一点;
  • HTTPSTAT_CURL_BIN 可指定 curl 路径(如 brew 版 curl 以启用 HTTP/2)。

八、测试与完成标准(Definition of Done)

8.1 三层测试体系

改造后的测试体系分三层:

  1. 单元测试 tests/test_httpstat.py(pytest):覆盖 parse_bool、pop_arg、parse_slo、check_slo、build_json_result、NO_COLOR 六大逻辑块,把 AGENTS.md 点名的「指标换算、区间计算、parse_bool」全部纳入稳定回归。开发依赖在 pyproject.toml 的 [dependency-groups] dev 中声明为 pytest>=8.4.2,可用 uv run pytest tests/ -v 运行;
  2. 端到端测试 httpstat_test.sh:新增用例包括 --format json 输出合法 JSON 且含 schema_version、--format jsonl 单行输出、--slo total=1 触发退出码 4、--save 写文件、NO_COLOR=1 无 ANSI 转义、HTTPSTAT_METRICS_ONLY 向后兼容。注意:该脚本依赖外网站点可达性,与 AGENTS.md 记载的技术债一致;
  3. 手工冒烟:python httpstat.py https://example.com --format json --slo total=100 等组合验证。

8.2 Definition of Done 对照

AGENTS.md 定义的完成标准与当前实现逐一对应:

  • --format json 输出具备 schema_version=1 的稳定结构,有单元测试锁定 → TestBuildJsonResult.test_schema_version;
  • --slo 阈值判定正确,退出码 4 有测试覆盖 → TestCheckSlo 全部用例 + httpstat_test.sh 的 assert_exit 4;
  • NO_COLOR 正确禁用颜色输出 → TestNoColor + E2E 无 ANSI 断言;
  • 不破坏现有 pretty 模式的默认行为 → --format 默认值即 pretty,且「基本用法」与「https 站点」等原有 E2E 用例继续通过。

九、Phase 2:Skill 层与 Agent 评估

9.1 诊断 Skill

Phase 2(进行中)在 skills/httpstat/SKILL.md 实现了面向 AI Agent 的 HTTP 性能诊断技能,覆盖:

  • 自动安装:which httpstat || pip install httpstat(或 uv pip install / pipx / brew),不假设环境已装;
  • 结构化运行:优先 httpstat <URL> --format json [curl options] 获取机器可读结果;
  • 瓶颈识别:把 timings_ms 中的 5 个区间字段分别对应 DNS/TCP/TLS/Server/Transfer 五类瓶颈,每类给出典型健康区间、可能原因与修复建议(如 DNS 慢建议 --resolve 绕过解析、TLS 慢建议核对证书链与 OCSP stapling);
  • SLO 阈值:--slo total=500,ttfb=300 用于持续监控;
  • curl 命令转换:将已有 curl 命令转换为 httpstat(去掉 -w/-o/-s/-S,保留 headers、method、data 等)。

9.2 评估用例

skills/httpstat/evals/evals.json 包含 3 个评估用例:慢 API 诊断(httpbin.org/delay/2,期望识别 server 阶段为瓶颈)、curl 命令耗时拆解、TLS 开销对比(http vs https)。根据 kb/sessions/2026-04-08-create-httpstat-diagnostics-skill.md 的 session 记录,该 Skill 经过两轮迭代评估:第二轮在干净目录中运行,with-skill 通过率 91.7% 对比 baseline(仅用 raw curl -w)的 78.3%,验证了 Skill 引导 Agent 自动安装并使用结构化诊断的价值。session 记录同时指出了两个后续优化点:评估环境隔离(避免全局 pip install 造成测试污染)与「是否重定向到 HTTPS」这一非区分性断言的处理。

9.3 待补充项

AGENTS.md 明确记录:诊断推理输出结构(bottleneck_stage、next_actions)尚未结构化为 JSON,目前仍以自然语言分析为主,这是 Phase 2 的后续工作方向。

十、总结:一条清晰的 Agent 友好化路线

从 AGENTS.md 的规划到 httpstat.py、tests/test_httpstat.py、httpstat_test.sh、skills/httpstat/SKILL.md 的落地实现,httpstat 的 2.0 时代完成了从「纯人类可读」到「机器可判定、Agent 可消费」的跃迁:--format json 提供带 schema version 的稳定结构,--slo 给出可脚本判定的退出码语义,NO_COLOR 与 --save 补全了流水线集成细节,Skill 层则把「如何诊断瓶颈」本身也变成了可复用的结构化能力。如果你正在为自己的诊断工具设计 Agent 友好接口,这套「单文件 CLI + 结构化输出 + 阈值退出码 + 文档化 Skill」的组合是一个值得参考的最小实现范本。

登录后查看全文
httpstat