/* 示例 1：实验切片的指标体系——按实验组维度切分核心指标 */
/* Prometheus recording rules：实验组 vs 对照组的稳态指标 */
groups:
  - name: experiment-slicing
    interval: 15s          /* 实验期间的高频评估（日常规则组为 1m） */
    rules:
      /* 实验组成功率（应用上报时携带 exp_group label） */
      - record: orders:success_rate:canary_5m
        expr: |
          sum(rate(order_created_total{status="success",exp_group="canary"}[5m]))
          / sum(rate(order_created_total{exp_group="canary"}[5m]))

      /* 对照组成功率 */
      - record: orders:success_rate:control_5m
        expr: |
          sum(rate(order_created_total{status="success",exp_group="control"}[5m]))
          / sum(rate(order_created_total{exp_group="control"}[5m]))

      /* 组间相对差异——护栏与判定的核心信号 */
      - record: orders:success_rate:canary_relative_drop
        expr: |
          (orders:success_rate:control_5m - orders:success_rate:canary_5m)
          / orders:success_rate:control_5m

      /* 分实验 ID 的目标服务延迟——支持多实验并行时的独立判定 */
      - record: experiment:target_latency:p99
        expr: |
          histogram_quantile(0.99,
            sum(rate(http_request_duration_seconds_bucket{exp_id!=""}[2m])) by (le, exp_id, service)
          )

这组 recording rules 实现了指标层的实验切片能力，是对照组实验（第 3 章示例 4）的判定基础。设计要点：（1）exp_group 与 exp_id 两级标签——exp_group（canary/control）支持单实验的组间对比，exp_id 支持多实验并行时按实验独立判定；标签由应用在上报指标时附加（从请求 header 读取实验标记），这是「标记透传工程」在指标层的落地。（2）15 秒的评估间隔专用于实验规则组——日常规则组保持 1 分钟（控制计算成本），实验期间高频评估让护栏的判定延迟从分钟级降到 15 秒级；这个规则组常驻启用（而非实验时动态加载），因为动态加载本身有失败风险，常驻的成本（几个规则的计算量）可接受。（3）canary_relative_drop 预计算了组间相对差异——护栏直接消费这个指标（> 0.02 连续 3 次即中止），判定逻辑集中在 recording rule 而非散落在各消费方，修改判定标准只改一处。（4）基数控制的实践：exp_id 标签的取值是实验 ID（每天几十个），不是请求 ID（每秒几万个）——高基数红线在实验指标设计中同样适用。注意 order_created_total 必须携带 exp_group 标签才有意义，这要求应用埋点的配合：无标记流量归入 exp_group="none"，避免与对照组混淆。

/* 示例 2：OpenTelemetry Collector——实验流量的差异化采样 */
/* otel-collector-config.yaml */
receivers:
  otlp:
    protocols: { grpc: {}, http: {} }

processors:
  /* 尾部采样：按实验标记差异化 */
  tail_sampling:
    decision_wait: 10s
    policies:
      /* 策略 1：实验标记流量 100% 采样——实验分析的完整数据 */
      - name: chaos-experiment-traces
        type: string_attribute
        string_attribute:
          key: chaos.experiment_id
          values: [".*"]
          enable_regex_matching: true
      /* 策略 2：错误与慢请求 100% 采样（日常也需要） */
      - name: errors-and-slow
        type: status_code
        status_code: { status_codes: [ERROR] }
      - name: slow-traces
        type: latency
        latency: { threshold_ms: 2000 }
      /* 策略 3：其余流量 1% 概率采样——控制日常成本 */
      - name: baseline-probabilistic
        type: probabilistic
        probabilistic: { sampling_percentage: 1 }

  /* 把实验标记从 header 提升为 trace attribute（供采样与查询） */
  attributes/experiment:
    actions:
      - key: chaos.experiment_id
        from_attribute: http.request.header.x_chaos_experiment
        action: upsert
      - key: chaos.exp_group
        from_attribute: http.request.header.x_exp_group
        action: upsert

exporters:
  otlp/tempo:
    endpoint: tempo.observability:4317

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [attributes/experiment, tail_sampling]
      exporters: [otlp/tempo]

这个 OTel Collector 配置解决了混沌实验的追踪采样核心矛盾：实验需要完整数据（故障只影响 0.5% 流量，1% 采样下实验组追踪几乎为零），日常需要控制成本（100% 采样的存储费用不可接受）。解法是尾部采样（tail sampling）+ 标记驱动：请求的追踪数据先在 Collector 缓冲（decision_wait 10 秒等待完整 trace 到齐），然后按策略决定保留或丢弃——带 chaos.experiment_id 属性的追踪 100% 保留，错误与慢请求 100% 保留（这两类日常也珍贵），其余 1% 概率采样。attributes processor 把 HTTP header 中的实验标记提升为 trace attribute，这是采样策略能按标记过滤的前提——也意味着标记透传断裂的服务，其追踪不会被实验采样捕获（透传完整性再次成为关键依赖）。尾部采样的工程代价要清楚：Collector 需要缓冲 10 秒的全量追踪数据（内存与 CPU 成本），decision_wait 内到达不完整的 trace 可能被误判——高流量系统需要按 trace_id 一致性哈希把同一 trace 的 span 路由到同一 Collector 实例（loadbalancing exporter）。实验结束后的成本回收是自动的：没有实验标记的流量回到 1% 采样，无需人工干预——这就是「增强观测自动化」在追踪层的实现。

/* 示例 3：Grafana 实验作战面板——annotation 联动与组间对比 */
/* experiment-war-room-dashboard.json（核心面板节选） */
{
  "annotations": {
    "list": [{
      "name": "chaos-experiments",
      "datasource": "Prometheus",
      "expr": "chaos_experiment_active{namespace='production'} == 1",
      "titleFormat": "{{experiment_name}} ({{chaos_kind}})",
      "textFormat": "目标: {{target}} | 强度: {{intensity}} | 负责人: {{owner}}"
    }]
  },
  "panels": [
    {
      "title": "稳态判定：实验组 vs 对照组成功率",
      "type": "timeseries",
      "targets": [
        { "expr": "orders:success_rate:canary_5m", "legendFormat": "实验组" },
        { "expr": "orders:success_rate:control_5m", "legendFormat": "对照组" },
        { "expr": "orders:success_rate:control_5m * 0.98", "legendFormat": "中止红线(-2%)" }
      ]
    },
    {
      "title": "注入强度与目标延迟的因果联动",
      "type": "timeseries",
      "targets": [
        { "expr": "chaos_injected_delay_ms{experiment='payment-slow'}", "legendFormat": "注入延迟(ms)" },
        { "expr": "experiment:target_latency:p99{exp_id='payment-slow'} * 1000", "legendFormat": "目标服务P99(ms)" }
      ]
    },
    {
      "title": "级联传播：调用链各环节延迟",
      "type": "timeseries",
      "targets": [
        { "expr": "histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket{service=~'frontend|checkout|payment'}[2m])) by (le, service))", "legendFormat": "{{service}} P99" }
      ]
    }
  ]
}

这个作战面板配置体现了实验仪表盘与普通运维面板的三个本质差异。第一，annotation 的实验上下文注入：chaos_experiment_active 指标（混沌平台或护栏上报的实验状态）作为 annotation 源，实验的起止时间、名称、目标、强度、负责人直接标注在所有面板的时间轴上——任何指标异常与实验窗口的时间关系一目了然，这是「相关 vs 因果」归因的第一道视觉工具；textFormat 里带上负责人，作战室里「这个实验是谁的」不需要问。第二，因果联动面板：把注入强度（chaos_injected_delay_ms）与目标指标（P99 延迟）画在同一张图——如果注入 500ms 后 P99 上升约 500ms，因果链清晰；如果 P99 上升 3s（远超注入量），说明存在放大机制（重试、排队），这个「放大倍数」本身就是重要发现。第三，级联传播面板：调用链上多个服务的 P99 并排展示，故障从注入点向上传播的路径与衰减/放大形态直接可见——payment 延迟注入后 checkout 涨了多少、frontend 涨了多少，级联的「形状」是架构韧性（隔离、降级是否生效）的直观证据。面板的组织逻辑是「判定 → 因果 → 机制」的下钻顺序，与诊断思维路径一致；作战室大屏按此布局，值班工程师扫一眼就能回答「稳态还在吗、实验在影响什么、影响传播到哪了」三个核心问题。

/* 示例 4：告警验证实验——用混沌实验测试告警体系 */
/* alert-validation-experiment.json（Chaos Toolkit 格式） */
{
  "title": "验证 payment-service 依赖超时告警链路的完整性",
  "steady-state-hypothesis": [
    {
      "type": "probe",
      "name": "baseline-no-alerts-firing",
      "provider": { "type": "http", "url": "http://alertmanager:9093/api/v2/alerts?filter=severity%3Dcritical" },
      "tolerance": { "type": "jsonpath", "jsonpath": "$.length(@)", "range": [0, 0] }
    }
  ],
  "method": [
    {
      "type": "action",
      "name": "inject-payment-timeout",
      "provider": { "type": "python", "module": "chaosmesh.faults", "func": "http_chaos", "arguments": { "target": "payment-service", "delay": "5s", "duration": "180s" } }
    },
    {
      "type": "probe",
      "name": "expect-dependency-latency-alert",
      "provider": { "type": "python", "module": "alert_validation", "func": "wait_for_alert", "arguments": { "alert_name": "DependencyLatencyHigh", "service": "payment-service", "timeout_seconds": 420 } },
      "tolerance": { "type": "probe", "provider": { "type": "python", "module": "alert_validation", "func": "alert_received" } }
    },
    {
      "type": "probe",
      "name": "measure-alert-latency",
      "provider": { "type": "python", "module": "alert_validation", "func": "alert_delivery_breakdown", "arguments": { "alert_name": "DependencyLatencyHigh" } }
    }
  ],
  "rollbacks": [
    { "type": "action", "name": "resolve-alerts", "provider": { "type": "python", "module": "alert_validation", "func": "silence_and_resolve", "arguments": { "experiment_tag": true } } }
  ]
}

这个 Chaos Toolkit 实验把「告警体系」本身作为被试对象，是可观测性检验的规范化实现。实验逻辑：注入 payment-service 5 秒延迟（持续 3 分钟）→ 断言「DependencyLatencyHigh 告警应当在 420 秒内触发并送达」→ 测量告警链路的分段延迟。420 秒的超时预算来自告警配置的推算：指标评估间隔 1 分钟 + for 窗口 5 分钟 + Alertmanager 分组等待 1 分钟 = 7 分钟——如果告警没在预算内到达，要么配置与预期不符，要么链路某段故障。alert_delivery_breakdown 探针测量分段延迟（指标越界时刻 → Prometheus 评估触发 → Alertmanager 接收 → 通知渠道送达），实验报告直接输出「这个告警从故障发生到人知道需要 X 分 Y 秒」——这个数字是告警体系最有价值的实测指标，也是推动 for 窗口与评估间隔优化的证据。steady-state-hypothesis 的设计巧妙：实验前断言「当前无 critical 告警」，保证实验从干净的告警状态开始（否则无法区分实验触发的告警与既有告警）。rollback 的 silence_and_resolve 只静默带实验标记的告警——精确静默而非全局静默，实验期间真实事故告警依然畅通（第 7 章误区 4 的正确实践）。建议为告警体系中的每条 critical 规则建立对应的验证实验，纳入季度套件——告警规则变更后的 CI 验证是更激进的形态。

/* 示例 5：诊断下行路径的自检脚本——三大支柱联动性测试 */
#!/bin/bash
/* observability-path-check.sh - 验证「指标→追踪→日志」诊断路径的完整性 */
TRACE_ID=$(uuidgen | tr -d '-' | tr 'A-Z' 'a-z' | cut -c1-32)
MARKER="obs-path-check-$(date +%s)"

echo "=== 步骤 1：发送带标记的测试请求（trace_id 将由 OTel 生成） ==="
RESP=$(curl -s -D - "https://shop.example.com/api/checkout"   -H "X-Exp-Group: canary"   -H "X-Debug-Marker: ${MARKER}"   -H "traceparent: 00-${TRACE_ID}-$(uuidgen | tr -d '-' | cut -c1-16)-01")
ACTUAL_TRACE=$(echo "$RESP" | grep -i traceresponse | grep -oE '[0-9a-f]{32}' | head -1)
echo "请求完成，trace_id=${ACTUAL_TRACE:-未返回}"

echo "=== 步骤 2：追踪可查性（等待采样管道 15s） ==="
sleep 15
TRACE_FOUND=$(curl -s "http://tempo.observability:3200/api/traces/${ACTUAL_TRACE}" | jq '.batches | length')
[ "${TRACE_FOUND:-0}" -gt 0 ] && echo "[OK] 追踪可查，含 ${TRACE_FOUND} 个 span 批次" || echo "[FAIL] 追踪缺失——采样或透传断裂"

echo "=== 步骤 3：日志关联性（按 trace_id 检索） ==="
LOG_COUNT=$(curl -s -G "http://loki.observability:3100/loki/api/v1/query"   --data-urlencode "query=count_over_time({app=~'.+'} | json | trace_id='${ACTUAL_TRACE}' [5m])" | jq '.data.result[0].value[1] // 0')
[ "${LOG_COUNT}" -gt 0 ] && echo "[OK] 找到 ${LOG_COUNT} 条关联日志" || echo "[FAIL] 日志无 trace_id 关联——诊断路径在此断裂"

echo "=== 步骤 4：指标 exemplar 关联 ==="
EXEMPLAR=$(curl -s "http://prometheus:9090/api/v1/query_exemplars?query=http_request_duration_seconds_bucket" | jq 'length')
[ "${EXEMPLAR:-0}" -gt 0 ] && echo "[OK] exemplar 已启用（${EXEMPLAR} 条）" || echo "[WARN] exemplar 未配置——指标到追踪的一键跳转不可用"

echo "=== 路径完整性结论 ==="
echo "指标→追踪: exemplar | 追踪→日志: trace_id | 全链路标记: ${MARKER}"

这个自检脚本把「三大支柱联动」从架构愿景变成可定期验证的工程事实，它模拟了值班工程师的诊断下行路径并逐段测试。四个步骤对应四个联动环节：步骤 1 发送带 W3C traceparent 的测试请求（强制指定 trace_id 使后续检索可预测），同时携带实验标记与 debug marker——这个请求就是「探针请求」，它走过的路径就是被测试的观测路径。步骤 2 验证追踪可查性：15 秒等待覆盖采样管道的延迟（OTel Collector 的 decision_wait + 导出间隔），查不到追踪的原因可能是采样丢弃（实验标记透传断裂导致 100% 采样策略未命中——这正是示例 2 配置的依赖）、span 上报失败、或 Tempo 索引延迟。步骤 3 验证日志关联：按 trace_id 在 Loki 中检索，零结果说明应用的日志没有结构化输出 trace_id（instrumentation 缺口）——这是最常见的断裂点，很多团队的日志里根本没有 trace_id 字段。步骤 4 验证 exemplar：Prometheus 的 exemplar 特性把指标数据点关联到具体 trace_id，是「指标→追踪」一键跳转的基础，未启用则诊断路径的第一跳就要手动拼查询。建议把这个脚本做成每日定时任务，结果指标化（obs_path_check_passed{stage="traces|logs|exemplars"}）——观测路径的退化（某次框架升级悄悄破坏了透传）能在一天内被发现，而不是等到真实事故的凌晨三点。

/* 示例 6：实验生命周期的观测增强自动化——编排器钩子 */
/* observation_boost.py - 实验开始/结束时自动调整观测配置 */
import requests

OTEL_COLLECTOR_ADMIN = "http://otel-collector:13133"
LOKI_ADMIN = "http://loki.observability:3100"
SERVICES_DEBUG_API = {
    "order-service": "http://order-service:8080/actuator/loggers",
    "checkout-service": "http://checkout-service:8080/actuator/loggers",
}

def on_experiment_start(experiment):
    """实验开始钩子：提升目标服务的观测密度"""
    /* 1. 目标服务 debug 日志（限定 logger，避免全量 debug） */
    for svc in experiment.target_services:
        if svc in SERVICES_DEBUG_API:
            requests.post(f"{SERVICES_DEBUG_API[svc]}/com.example.payment",
                          json={"configuredLevel": "DEBUG"})

    /* 2. 通知 OTel Collector 激活实验采样策略（配置热加载） */
    requests.post(f"{OTEL_COLLECTOR_ADMIN}/admin/experiment-sampling",
                  json={"experiment_id": experiment.id, "sampling_pct": 100,
                        "ttl_seconds": experiment.duration_seconds + 600})

    /* 3. Grafana 写入实验开始 annotation */
    requests.post("http://grafana:3000/api/annotations",
                  headers={"Authorization": "Bearer $GRAFANA_TOKEN"},
                  json={"time": now_ms(), "tags": ["chaos", experiment.id],
                        "text": f"实验开始: {experiment.name} 目标={experiment.target_services}"})

def on_experiment_end(experiment):
    """实验结束钩子：恢复日常观测配置（幂等，失败重试）"""
    for svc in experiment.target_services:
        if svc in SERVICES_DEBUG_API:
            requests.post(f"{SERVICES_DEBUG_API[svc]}/com.example.payment",
                          json={"configuredLevel": None})   /* None = 继承默认 */
    requests.post(f"{OTEL_COLLECTOR_ADMIN}/admin/experiment-sampling",
                  json={"experiment_id": experiment.id, "sampling_pct": None})
    requests.post("http://grafana:3000/api/annotations",
                  json={"time": now_ms(), "tags": ["chaos", experiment.id],
                        "text": f"实验结束: {experiment.name}"})

这个钩子模块实现了「增强观测自动化」的编排器集成：实验生命周期事件驱动观测配置的动态调整。三个增强动作各有工程细节。debug 日志提升限定到具体 logger（com.example.payment）而非 root——全量 debug 的日志量可能压垮磁盘 IO 与 Loki 摄入（观测者效应的直接形态），限定 logger 把成本控制在相关组件；Spring Boot Actuator 的 loggers endpoint 支持运行时调整，Go 服务可用 zap.AtomicLevel 暴露等价接口。采样策略激活带 TTL（实验时长 + 600 秒恢复观察期）——TTL 是防「忘记恢复」的兜底：即使 on_experiment_end 钩子失败（编排器崩溃、网络分区），Collector 也会在 TTL 后自动回落到日常采样率；这是增强观测的安全设计范式：所有临时提升都必须自带过期机制。annotation 写入让实验窗口自动出现在所有 Grafana 面板上（示例 3 的 annotation 数据源），复盘时不需要人工记录时间线。on_experiment_end 的幂等性要求：恢复动作可能被重试执行（钩子失败重投），configuredLevel: None（恢复继承）与采样率置空都是幂等操作。把这个模块挂到实验编排器（第 6 章示例 4 的调度器）的 launch/cleanup 阶段，观测增强就成为实验的标准配件而非人工负担。