iomgaa
3058f4c744
Add architecture doc (research-wiki/ARCHITECTURE.md), CLAUDE.md with tiered SOP for Fable 5, adapted .claude skills/hooks/settings, package skeleton (src/polygateway), pyproject with import-linter contracts, Makefile, .env.example and smoke test.
51 lines
3.0 KiB
Markdown
51 lines
3.0 KiB
Markdown
---
|
|
name: structured-logging
|
|
description: "设计结构化日志/遥测方案。当功能会产生运行时数据时,在 brainstorming 产出 design 之后、writing-plans 之前调用:确定记录什么、记到哪、如何评估,并注册到 Wiki。纯内部重构、不产生运行时数据的改动不需要。"
|
|
argument-hint: "[功能描述]"
|
|
---
|
|
|
|
# Structured Logging
|
|
|
|
## Overview
|
|
|
|
为即将开发的功能设计结构化日志/遥测方案:记录什么数据、落到哪张表、如何评估。
|
|
|
|
**边界**: 会产生运行时数据的功能,编码前必须有日志方案——埋点是"当前需要"(CLAUDE.md P1),事后补埋点意味着丢失基线数据。不产生运行时数据的改动直接跳过本 skill。
|
|
|
|
本项目背景:PolyGateway 自带遥测子系统(`telemetry/`,SQLite 后端,每次调用必录,见 CLAUDE.md 库铁律"遥测必录")。本 skill 设计的是**具体功能的埋点方案**,必须与遥测子系统对齐,不另起炉灶。
|
|
|
|
## 设计要回答的问题
|
|
|
|
1. **这个功能产生什么运行时数据?** 网关领域的典型维度:
|
|
- 每次调用的时延 / TTFT / token 用量与成本
|
|
- 错误分类计数(Transient/SourceDead/RequestRejected/ResultInvalid)与重试次数
|
|
- 熔断状态迁移、限流等待/拒绝、缓存命中率
|
|
- 阶段事件(开始/结束/错误/降级)
|
|
2. **新建表还是复用现有表?** 现有表能覆盖就复用;需要新维度才新建。先对照 `research-wiki/schemas/` 已登记的 schema 与实际库中的表,标记不一致。
|
|
3. **每张表的 schema**: 列名、类型、说明、主键、哪些列服务于诊断查询。
|
|
4. **埋点位置**: 具体模块与函数;必须走库的 `TelemetryRecorder` 端口/统一 helper,禁止散落的 ad-hoc 写库(三项目遥测调用被复制 4 次的教训)。
|
|
5. **评估基线**: 可量化指标 + 阈值 + 判定方式;基线来源(对比哪次历史运行;首次则标"待首次运行后建立")。
|
|
|
|
## 注册到 Wiki(留痕,不可省略)
|
|
|
|
```bash
|
|
.claude/tools/research_wiki.py add_entity research-wiki/ --type schema --id <table-name> --title "表结构: <table-name>"
|
|
.claude/tools/research_wiki.py add_entity research-wiki/ --type metric --id <metric-name> --title "<指标描述>"
|
|
.claude/tools/research_wiki.py add_edge research-wiki/ --from "metric:<id>" --to "schema:<id>" --type measures --evidence "..."
|
|
.claude/tools/research_wiki.py add_edge research-wiki/ --from "schema:<id>" --to "design:<id>" --type implements --evidence "..."
|
|
.claude/tools/research_wiki.py rebuild_index research-wiki/
|
|
```
|
|
|
|
在生成的 md 中填入完整列定义、埋点位置、基线值与阈值。
|
|
|
|
## 产出(交给 writing-plans)
|
|
|
|
埋点清单:哪些文件、哪些函数、在什么位置记什么。这些埋点必须成为 plan 中的显式步骤,不得遗漏。
|
|
|
|
| 产出 | 位置 |
|
|
|------|------|
|
|
| schema 实体 | `research-wiki/schemas/<name>.md` |
|
|
| metric 实体 | `research-wiki/metrics/<name>.md` |
|
|
| edge 关系 | `research-wiki/graph/edges.json` |
|
|
| 埋点清单 | 传递给 writing-plans |
|