Grafana as Code (Tipsy)
把"高优指标 → 告警/看板"做成 DRY 单一事实源 + 一键生成 + 托管 Grafana 可落地。
分工:通用工具随 skill 分发(<skill>/scripts/),各服务的资产就近放各自仓库
(看板 JSON、告警 spec 由指标归属者维护)。
环境:阿里云托管 Grafana grafana-cn-c064otf0j01.grafana.aliyuncs.com,多数据源——
prod 业务指标在 ARMS us-east-1(uid efflgyrdjhyiof),但新服务上板前必须先探测指标
落在哪个源(见 references/dashboards.md 数据源清单与探测法)。告警统一上报飞书联系点
feishu-tipsy-alerts(经 CF Worker + HMAC)。
和 logfire-ops 的边界("读告警"歧义先看这里)
本 skill 与 logfire-ops 都涉及"告警/看板",但监控对象不同,不要混用:
- grafana-as-code(本 skill)= 基础设施指标:Grafana alert 盯的是 ARMS Prometheus 指标
(内存、circuit_state、时延桶、namespace 等),告警走
deploy/grafana/ 的
spec→generate→push;看板走经典 Grafana API。
- logfire-ops = 应用层 telemetry:Logfire alert 盯的是应用 trace/日志信号
(Input too long、newapi 渠道缺失 503、sunrise 等);看板是 Logfire dashboard(Perses)。
本 skill 的强项是写:加/改告警规则、校准阈值、推看板。当用户只说"读一下线上告警"
未指明平台时,那多半是想看现有告警状态——若指基础设施指标(内存/时延/Prometheus)用本
skill;若指应用层 telemetry 告警,那属于 logfire-ops。不确定就先反问澄清,别默默猜一个。
按任务读对应手册(分层暴露,只读当前任务相关那份)
| 你要做的 |
先读 |
关键纪律 |
| 新增/修改告警规则、排查告警误报 |
references/alerting.md |
写告警前必读——含 circuit_state/时延/namespace 等指标陷阱铁律;告警文案写给接收人(出了什么事/影响谁/该干什么),定标依据与排查步骤放 runbook 不进推送 |
| 推送/更新看板(dashboard) |
references/dashboards.md |
用 skill 自带脚本;先探测数据源;folder-SA 首推 403 直接重跑;耗时(duration)指标必须 P50/P90/P95/P99 四口径、一分位一 panel |
| 校准阈值 / 诊断误报根因 / 调整告警分级与接收人 |
references/diagnostics.md |
写任何阈值前必读——先查真实 series,不凭假设;分级与路由按「用户可感/不可逆」「谁会处理」定,别自己发挥 |
这些 references 平时不占上下文,按需读取。不确定该读哪份就先读 alerting.md(覆盖面最广)。
§0 前置:每次操作前必做(凭证)
凭证不落盘,运行时从 secrets.sh 注入(不要 echo $GRAFANA_TOKEN、不要写进任何文件):
source "$HOME/github/my_dot_files/secrets.sh" # 注入 GRAFANA_URL / GRAFANA_TOKEN
[ -n "$GRAFANA_TOKEN" ] || { echo "secrets.sh 未注入 GRAFANA_TOKEN"; exit 1; }
工具定位(按任务二选一):
跨切面铁律(任何操作都适用 —— 违反必出事)
- token 不落盘:
GRAFANA_TOKEN 只在运行时由 secrets.sh 注入 env,绝不写 .env、不
echo、不提交。
- 数据源先探测再 pin:prod 业务指标在
efflgyrdjhyiof(ARMS us-east-1),但实例里有
3 个 Prometheus 数据源,新服务的指标位置用 count() 探测确认,别按集群区域猜
(tipsy-memory 部署在 cn-hongkong、指标却在 us-east-1)。
- 改全局 Grafana 资源前先确认不冲别人:通知策略 root、联系点是全局单资源,推之前务必
确认不会冲掉其他团队的路由(告警
make push 默认已不动它们,详见 alerting.md)。
- 跨服务告警/看板就近放各自仓库(指标归属者维护),别把 K8s/Pineapple 等基础设施告警
塞进本后端仓。通用脚本随 skill 分发,不复制进业务仓。
- 监控产物不进 PR(用户多次纠偏后定下的纪律):服务仓 grafana 部署目录下的看板 JSON、
告警 spec/generated 产物,一律不随业务代码 PR 提交——推送靠脚本直连 Grafana,产物
本地留档即可。提 PR 前自查
git status / diff,把这类文件从暂存区剔除;发现已混入的,
先从 PR 里删掉再谈合入。
⚠️ 能力专属的铁律(circuit_state=1 可用、gin 时延桶上限陷阱、namespace 混服务过滤、
比率必 clamp_max、多副本 Gauge 必聚合…)在 references/alerting.md —— 写告警必读那份,
历史上最大的误报事故都出在这些点上。
收尾 / 更深问题
- 各能力的故障速查见对应
references/*.md。
- 开放问题(阈值校准清单、现网指标 bug、recsys 文件夹迁移)见
deploy/grafana/alerting/NOTES.md 与 deploy/grafana/PROGRESS.md。
- 改完
deploy/grafana/ 务必 git diff 审查;这些产物不进业务代码 PR(见铁律 5),本地留档即可。
1---2name: grafana-as-code3description: org 全部后端服务的 Grafana「告警即代码 / 看板推送 / 阈值校准」操作 skill(tipsy-backend、 tipsy-memory、recsys 等)。当用户要新增或修改 Grafana 告警规则、推送或更新看板(dashboard)、 校准告警阈值、排查告警误报/漏报时使用。看板推送用 skill 自带通用脚本(scripts/push_dashboard.py, 任何服务仓可用);告警封装 tipsy-backend deploy/grafana/ 下的 spec→generate→validate→push 工作流;另含 diagnostics 校准/诊断。典型触发:"加一条告警"、"改告警阈值"、"推个看板 / 更新看板"、"告警在误报"、"校准阈值"、"push 到 grafana"、"新建一个 dashboard 面板"。 环境为阿里云托管 Grafana + ARMS Prometheus。4---56# Grafana as Code (Tipsy)78把"高优指标 → 告警/看板"做成 **DRY 单一事实源 + 一键生成 + 托管 Grafana 可落地**。9分工:**通用工具随 skill 分发**(`<skill>/scripts/`),**各服务的资产就近放各自仓库**10(看板 JSON、告警 spec 由指标归属者维护)。1112环境:阿里云托管 Grafana `grafana-cn-c064otf0j01.grafana.aliyuncs.com`,**多数据源**——13prod 业务指标在 ARMS us-east-1(uid `efflgyrdjhyiof`),但新服务上板前**必须先探测**指标14落在哪个源(见 `references/dashboards.md` 数据源清单与探测法)。告警统一上报飞书联系点15`feishu-tipsy-alerts`(经 CF Worker + HMAC)。1617## 和 logfire-ops 的边界("读告警"歧义先看这里)1819本 skill 与 `logfire-ops` 都涉及"告警/看板",但**监控对象不同,不要混用**:2021- **grafana-as-code(本 skill)= 基础设施指标**:Grafana alert 盯的是 ARMS Prometheus 指标22 (内存、circuit_state、时延桶、namespace 等),告警走 `deploy/grafana/` 的23 spec→generate→push;看板走经典 Grafana API。24- **logfire-ops = 应用层 telemetry**:Logfire alert 盯的是应用 trace/日志信号25 (Input too long、newapi 渠道缺失 503、sunrise 等);看板是 Logfire dashboard(Perses)。2627本 skill 的强项是**写**:加/改告警规则、校准阈值、推看板。**当用户只说"读一下线上告警"28未指明平台时**,那多半是想**看现有告警状态**——若指基础设施指标(内存/时延/Prometheus)用本29skill;若指应用层 telemetry 告警,那属于 logfire-ops。**不确定就先反问澄清**,别默默猜一个。3031---3233## 按任务读对应手册(分层暴露,只读当前任务相关那份)3435| 你要做的 | **先读** | 关键纪律 |36|---|---|---|37| 新增/修改告警规则、排查告警误报 | `references/alerting.md` | **写告警前必读**——含 circuit_state/时延/namespace 等指标陷阱铁律;告警文案写给接收人(出了什么事/影响谁/该干什么),定标依据与排查步骤放 runbook 不进推送 |38| 推送/更新看板(dashboard) | `references/dashboards.md` | 用 skill 自带脚本;**先探测数据源**;folder-SA 首推 403 直接重跑;耗时(duration)指标必须 P50/P90/P95/P99 四口径、一分位一 panel |39| 校准阈值 / 诊断误报根因 / 调整告警分级与接收人 | `references/diagnostics.md` | **写任何阈值前必读**——先查真实 series,不凭假设;分级与路由按「用户可感/不可逆」「谁会处理」定,别自己发挥 |4041> 这些 references 平时不占上下文,按需读取。**不确定该读哪份就先读 alerting.md**(覆盖面最广)。4243---4445## §0 前置:每次操作前必做(凭证)4647凭证不落盘,运行时从 secrets.sh 注入(**不要 `echo $GRAFANA_TOKEN`、不要写进任何文件**):4849```bash50source "$HOME/github/my_dot_files/secrets.sh" # 注入 GRAFANA_URL / GRAFANA_TOKEN51[ -n "$GRAFANA_TOKEN" ] || { echo "secrets.sh 未注入 GRAFANA_TOKEN"; exit 1; }52```5354工具定位(按任务二选一):5556- **看板推送**:用 skill 自带脚本,无仓库依赖——57 `python3 "$HOME/.claude/skills/grafana-as-code/scripts/push_dashboard.py" --folder <目录> <JSON>`。58 看板 JSON 在当前服务仓里(tipsy-memory 为 `deploy/observability/`,tipsy-backend 为59 `deploy/grafana/dashboards/`)。60- **告警 / diagnostics**:脚本仍在 tipsy-backend 仓 `deploy/grafana/`(spec→generate→push61 与看板不同通道)——`cd` 到 tipsy-backend 后:62 ```bash63 cd "$(git rev-parse --show-toplevel)/deploy/grafana" || { echo "告警工作流须在 tipsy-backend 仓"; exit 1; }64 ```65 > ⚠️ 若该目录在你的 clone 里不存在,说明 feature/alerts 的产物仍未提交进主干——先把它66 > 落库,否则告警 as-code 工作流不可用(看板推送不受影响)。6768---6970## 跨切面铁律(任何操作都适用 —— 违反必出事)71721. **token 不落盘**:`GRAFANA_TOKEN` 只在运行时由 secrets.sh 注入 env,绝不写 .env、不73 `echo`、不提交。742. **数据源先探测再 pin**:prod 业务指标在 `efflgyrdjhyiof`(ARMS us-east-1),但实例里有75 3 个 Prometheus 数据源,新服务的指标位置**用 count() 探测确认**,别按集群区域猜76 (tipsy-memory 部署在 cn-hongkong、指标却在 us-east-1)。773. **改全局 Grafana 资源前先确认不冲别人**:通知策略 root、联系点是全局单资源,推之前务必78 确认不会冲掉其他团队的路由(告警 `make push` 默认已不动它们,详见 alerting.md)。794. **跨服务告警/看板就近放各自仓库**(指标归属者维护),别把 K8s/Pineapple 等基础设施告警80 塞进本后端仓。通用脚本随 skill 分发,不复制进业务仓。815. **监控产物不进 PR**(用户多次纠偏后定下的纪律):服务仓 grafana 部署目录下的看板 JSON、82 告警 spec/generated 产物,一律**不随业务代码 PR 提交**——推送靠脚本直连 Grafana,产物83 本地留档即可。提 PR 前自查 `git status` / diff,把这类文件从暂存区剔除;发现已混入的,84 先从 PR 里删掉再谈合入。8586> ⚠️ **能力专属的铁律**(circuit_state=1 可用、gin 时延桶上限陷阱、namespace 混服务过滤、87> 比率必 clamp_max、多副本 Gauge 必聚合…)在 `references/alerting.md` —— **写告警必读那份**,88> 历史上最大的误报事故都出在这些点上。8990## 收尾 / 更深问题9192- 各能力的故障速查见对应 `references/*.md`。93- 开放问题(阈值校准清单、现网指标 bug、recsys 文件夹迁移)见94 `deploy/grafana/alerting/NOTES.md` 与 `deploy/grafana/PROGRESS.md`。95- 改完 `deploy/grafana/` 务必 `git diff` 审查;这些产物**不进业务代码 PR**(见铁律 5),本地留档即可。
igoingdown