可观测性即代码：仪表盘、告警规则与采集配置的 GitOps

1. 不可追溯：阈值被改了，没人知道是谁、为什么改
2. 不可复现：新建集群要手工重配一遍，容易漏
3. 不可评审：一个错误的正则告警规则直接上生产
4. 不可测试：规则写错只有等它该响的时候才发现

仪表盘（Dashboards）：JSON 模型，可存文件、可导入
告警规则（Alert Rules）：PrometheusRule CRD / Grafana 规则文件
采集配置（Collectors）：OTel Collector config / Prometheus scrape config

结论：配置规模一旦超过几十个面板、几十条规则，手工维护必然失控

Grafana 仪表盘 = 一个 JSON 文档
  包含：panels、queries、variables、layout、datasource 引用

导出方式：
  UI → Dashboard settings → JSON Model → 复制
  或 API：GET /api/dashboards/uid/{uid}

Grizzly 是 Grafana 官方的 as-code 工具：
  grr pull   https://grafana.example.com   # 拉取现有仪表盘为文件
  grr push   dashboards/                   # 推送本地文件到 Grafana
  grr export                               # 导出为可版本化格式

# dashboards/api-latency.json 的引用配置示例
apiVersion: grizzly.grafana.com/v1alpha1
kind: Dashboard
metadata:
  name: api-latency
spec:
  title: API Latency Overview
  uid: api-latency
  schemaVersion: 39

resource "grafana_dashboard" "api_latency" {
  config_json = file("${path.module}/dashboards/api-latency.json")
  folder      = grafana_folder.observability.id
}

问题：仪表盘里写死了 datasource uid 与集群名
方案：用变量占位，渲染时注入
  - Jsonnet / Grafonnet：用代码生成 JSON，复用面板模板
  - Terraform 变量：同一份 HCL 渲染 dev/staging/prod
  - Grafana 内置变量：$datasource、$cluster、$namespace

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: api-slo-rules
  namespace: observability
spec:
  groups:
  - name: api-slo
    interval: 30s
    rules:
    - alert: HighErrorRate
      expr: |
        sum(rate(http_requests_total{status=~"5.."}[5m])) by (service)
          / sum(rate(http_requests_total[5m])) by (service) > 0.05
      for: 10m
      labels:
        severity: critical
      annotations:
        summary: "服务 {{ $labels.service }} 错误率超过 5%"
        runbook_url: "https://runbook.example.com/high-error-rate"

# tests/api-slo-test.yml
rule_files:
- api-slo-rules.yml
evaluation_interval: 1m
tests:
- interval: 1m
  input_series:
  - series: 'http_requests_total{service="checkout",status="500"}'
    values: '0+10x20'
  - series: 'http_requests_total{service="checkout",status="200"}'
    values: '0+90x20'
  alert_rule_test:
  - eval_time: 12m
    alertname: HighErrorRate
    exp_alerts:
    - exp_labels:
        severity: critical
        service: checkout

运行：promtool test rules tests/api-slo-test.yml
价值：在 CI 里验证"这条规则在什么数据下会响、什么时候不响"
     避免"规则上线后才发现永远不触发"或"疯狂误报"

□ 每条告警都有 for（避免瞬时抖动）与 severity 标签
□ 都有 summary 与 runbook_url
□ 表达式不含高基数 label 聚合（防 OOM）
□ 阈值有数据依据（SLO / 历史 P99），不是拍脑袋
□ 有对应的单元测试用例

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
processors:
  memory_limiter:
    check_interval: 1s
    limit_percentage: 75
  batch:
    timeout: 5s
    send_batch_size: 8192
  resource:
    attributes:
    - key: deployment.environment
      value: prod
      action: upsert
exporters:
  otlphttp:
    endpoint: http://tempo.observability:4318
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch, resource]
      exporters: [otlphttp]

scrape_configs:
- job_name: kubernetes-service-endpoints
  kubernetes_sd_configs:
  - role: endpoints
  relabel_configs:
  - source_labels: [__meta_kubernetes_service_annotation_prometheus_io_scrape]
    action: keep
    regex: "true"
  - source_labels: [__meta_kubernetes_pod_label_app]
    target_label: service

模式一：配置内嵌 CRD（Prometheus Operator）
  改 PrometheusRule / ServiceMonitor → Operator 自动重载，天然 GitOps
模式二：配置文件 + ConfigMap 挂载
  ConfigMap 更新 → 挂载卷刷新 → 需 reload（SIGHUP 或 /-/reload）
  注意：reload 失败会静默不生效，必须监控

验证手段：
  otelcol validate --config=config.yaml       # OTel Collector 配置校验
  promtool check config prometheus.yml        # Prometheus 配置校验
  promtool check rules rules/*.yml            # 规则语法校验
全部可放进 CI，PR 阶段就拦住语法错误

开发者提交 PR
  → CI：lint + 单元测试 + 渲染校验
  → 评审：SRE / 值班同学 review
  → 合并到 main
  → GitOps 控制器（ArgoCD / Flux）检测差异并自动同步
  → 冒烟验证（规则是否加载、面板是否可见）

# .github/workflows/observability-ci.yml 关键步骤
steps:
- name: Validate Prometheus rules
  run: promtool check rules rules/*.yml
- name: Run rule unit tests
  run: promtool test rules tests/*.yml
- name: Validate OTel Collector config
  run: otelcol validate --config=collector/config.yaml
- name: Lint dashboards JSON
  run: ./scripts/lint-dashboards.sh
- name: Check dashboard datasource refs
  run: ./scripts/check-datasource-refs.sh

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: observability-config
spec:
  source:
    repoURL: https://git.example.com/sre/observability
    path: overlays/prod
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

selfHeal: true → 有人手工改了规则，会被自动改回
prune: true    → 删掉的文件对应资源也会被清理
注意：prune 有风险，务必先在非生产验证

告警规则评审清单：
  1. 这条告警对应哪个 SLO / 用户影响？
  2. 阈值依据是什么（历史数据 / 压测）？
  3. 有没有 for 与 severity？误报时怎么静默？有没有 runbook？
  4. 单元测试覆盖了吗？

仪表盘评审清单：
  1. 变量是否参数化（不写死集群/实例）？
  2. 查询是否高基数（可能拖垮 Prometheus）？

分支策略：main 为唯一真相，变更走 PR
回滚：git revert <commit> → GitOps 自动同步回滚
关键：所有变更都有 Git 记录，回滚是"重放"而非"重做"

目录结构示例：
  base/                    公共规则与面板
  overlays/dev/            开发环境差异（阈值放宽）
  overlays/prod/           生产（阈值严格）
Kustomize / Helm 渲染 base + overlay → 目标环境配置
收益：规则逻辑只写一份，环境差异用补丁表达

□ 仪表盘、告警规则、采集配置全部纳入 Git 单一仓库
□ 用 base + overlay 表达环境差异，规则逻辑只写一份
□ 每条告警规则配单元测试，CI 中 promtool test rules
□ CI 集成 promtool check、otelcol validate、JSON lint
□ 仪表盘用变量参数化数据源与集群，不写死 uid
□ 用 ArgoCD/Flux 自动同步，开启 selfHeal 防手工漂移
□ 告警规则强制 for、severity、summary、runbook_url
□ 配置变更走 PR 评审，SRE 参与 review
□ 监控 reload/sync 成功率，防止静默失效
□ 建立 git revert 一键回滚流程并演练

可观测性即代码 = 配置进 Git + PR 评审 + CI 测试 +
GitOps 自动同步，让每条规则都有出处与回滚路径。