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