message MediaSpan {
  string trace_id = 1;           // 全局唯一
  string span_id = 2;            // 本节点唯一
  string parent_span_id = 3;     // 上游节点 span_id
  enum NodeType { ENDPOINT=0; SFU=1; MCU=2; GATEWAY=3; }
  NodeType node_type = 4;
  int64 start_time_ns = 5;       // 处理开始（如收到首包）
  int64 end_time_ns = 6;         // 处理结束（如转发完毕）
  map<string, string> attributes = 7; // 关键指标 KV
  repeated Event events = 8;     // 关键事件流
}

[Media Nodes] → [Agent] → [Kafka: raw_spans] → [Flink/Spark Streaming] → [ClickHouse / Apache Doris]
                                                      ↓
                                            [Rule Engine / ML Pipeline]
                                                      ↓
                                            [Alerting / Dashboard / API]

// 采样决策上下文，随 SDP 协商下发至终端
type SamplingPolicy struct {
    // 基础采样率
    BaseRate          float64 `json:"base_rate"`           // 0.01 = 1%
    // 关键路径强制全量（主讲人、共享屏、主席模式）
    ForceFullPaths    []string `json:"force_full_paths"`    // ["role:speaker", "content:screen"]
    // 自适应熔断阈值
    AdaptiveThreshold struct {
        CpuPct       float64 `json:"cpu_pct"`        // Agent CPU > 70% 触发降级
        MemPct       float64 `json:"mem_pct"`        // Agent Mem > 75% 触发降级
        KafkaLagMs   int64   `json:"kafka_lag_ms"`   // 消费滞后 > 5s 触发降级
    } `json:"adaptive_threshold"`
    // 降级后的最低采样率
    MinRate           float64 `json:"min_rate"`            // 0.001 = 0.1%
}

// 终端侧决策逻辑（伪代码）
func (c *MediaClient) shouldReportXR(policy *SamplingPolicy, localStats *LocalStats) bool {
    // 1. 关键路径强制全量
    if slices.Contains(policy.ForceFullPaths, c.getRoleTag()) {
        return true
    }
    // 2. 自适应熔断：Agent 侧通过 gRPC 心跳下发当前负载因子 load_factor (0.0~1.0)
    effectiveRate := policy.BaseRate * (1.0 - localStats.AgentLoadFactor)
    if effectiveRate < policy.MinRate {
        effectiveRate = policy.MinRate
    }
    // 3. 一致性哈希采样，保证同一 TraceID 在链路两端决策一致
    return consistentHashSample(c.traceID, effectiveRate)
}

// 新增 Event 类型定义
enum MediaEventType {
  NACK_SENT = 100;           // 发送 NACK
  NACK_RECEIVED = 101;       // 收到 NACK (SFU/发送端)
  FEC_RECOVERED = 102;       // FEC 恢复成功帧数
  FEC_FAILED = 103;          // FEC 恢复失败
  PLC_CONCEALMENT = 104;     // 音频丢包隐藏 (ms)
  BWE_DROP = 105;            // 带宽估计下调 (target_bitrate_kbps)
  KEY_FRAME_REQUEST = 106;   // 请求关键帧 (PLI/FIR)
  JITTER_BUFFER_ADAPT = 107; // 抖动缓冲区动态调整 (target_delay_ms)
}

// Span.events 示例
events: [
  {time_ns: 1715000000123456, type: "BWE_DROP", attrs: {"old_kbps": 1800, "new_kbps": 900, "reason": "loss_based"}},
  {time_ns: 1715000000124000, type: "NACK_SENT", attrs: {"pid": 1024, "blp": 0x00FF}},
  {time_ns: 1715000000124500, type: "FEC_RECOVERED", attrs: {"packets": 3}},
  {time_ns: 1715000000130000, type: "PLC_CONCEALMENT", attrs: {"duration_ms": 40}},
]

graph LR
    A[Media Pod] --> B(eBPF TC Hook)
    B --> C{提取: src_ip, dst_ip, rt_tcp_rtt, retrans, tc_class}
    C --> D[Enrichment Sidecar]
    D --> E[Cloud Metadata APInAWS: DescribeNetworkInterfacesnAliyun: DescribeEipAddressesnK8s: Node Topology]
    E --> F[生成 NetworkTopology Span]
    F --> G[ClickHouse: network_topology_wide_table]

-- ClickHouse 查询示例：定位跨运营商互联点丢包
SELECT
    net.src_asn, net.dst_asn,
    quantile(0.99)(media.packet_loss_pct) AS p99_loss,
    count() AS session_cnt
FROM media_spans
JOIN network_topology USING (trace_id, span_id)
WHERE net.link_type = 'public_internet'
  AND net.src_asn != net.dst_asn
GROUP BY net.src_asn, net.dst_asn
HAVING p99_loss > 2 AND session_cnt > 100
ORDER BY p99_loss DESC
LIMIT 10;

# .gitlab-ci.yml / Jenkinsfile 片段
stages:
  - chaos_inject
  - observation_wait   # 等待 3 个采样周期 (15s)
  - root_cause_assert  # 调用根因定位 API 对比期望标签
  - chaos_recover
  - report_generate

root_cause_assert:
  script:
    - |
      python verify.py 
        --trace-id $CHAOS_TRACE_ID 
        --expected-label "uplink_congestion" 
        --tolerance 0.9 
        --api-endpoint $RCA_API
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"  # 每日定时跑全量矩阵

// Web/Electron/Flutter 统一接口定义
interface TelemetryConfig {
  // 采集开关位图
  enableFlags: {
    rtpStats: boolean;          // 基础 getStats (必开)
    rtcpXrExtended: boolean;    // RFC 3611/7002 扩展块
    timestampTrace: boolean;    // capture/encode/packetize 时间戳 (高开销)
    cpuMemProfile: boolean;     // 进程资源占用 (1s/次)
    gpuMetrics: boolean;        // VideoDecodeAccelerator/Encoder 统计
    networkStack: boolean;      // TCP_INFO / QUIC 内部状态
  };
  // 上报频率 (ms)
  reportIntervalMs: number;
  // 采样率 (0.0~1.0)
  sampleRate: number;
  // 敏感字段脱敏规则
  piiRedaction: {
    ipMasking: boolean;         // IP 最后一段置 0
    userIdHash: boolean;        // user_id -> SHA256(salt+uid)
    meetingIdHash: boolean;     // meeting_id -> Hash
  };
}

// 服务端下发逻辑 (配置中心 + 规则引擎)
function generateConfig(user: User, meeting: Meeting, network: NetworkEstimate): TelemetryConfig {
  const base = getGlobalDefaultConfig();
  // 1. VIP/投诉用户全量高频
  if (user.isVip || user.recentComplaints > 0) return { ...base, sampleRate: 1.0, reportIntervalMs: 2000 };
  // 2. 弱网用户开启高开销时间戳追踪
  if (network.rtt > 150 || network.loss > 0.02) return { ...base, enableFlags: { ...base.enableFlags, timestampTrace: true } };
  // 3. 低端设备关闭 GPU/CPU 采集
  if (device.benchmarkScore < LOW_END_THRESHOLD) return { ...base, enableFlags: { ...base.enableFlags, gpuMetrics: false, cpuMemProfile: false } };
  return base;
}

# RCA-KB-20240518-SG-CCN-PACKETLOSS

## 现象
2024-05-18 14:00-14:45，新加坡区域通过 Cloud Connect (CCN) 回源北京核心 SFU 的会议，用户投诉“花屏、冻结”，MOS 均值跌至 2.1。

## 根因定位链路
1. **TraceID 聚合**：`trace_id=018f...` 显示 `sfu.forward_queue_depth` P99=450，`network.rtt` 正常 (45ms)，但 `network.packet_loss_pct` 突增至 8%。
2. **拓扑关联**：`net.link_type=direct_connect`，`net.src_asn=45102` (阿里云), `net.dst_asn=45102`，路径为 `SG-POP -> CCN -> CN-BJ`。
3. **网络层证据**：eBPF 抓包显示 `tc_class=0x10` (Best Effort)，**DSCP EF (0x2e) 在 SG 网关被重写为 0**。同时 `tc_retrans` 激增。
4. **云厂商工单**：确认 CCN 控制平面变更导致 QoS 策略下发丢失，EF 流量进入 BE 队列，拥塞丢包。

## 处置动作
- T+5min：SRE 手动下发 `tc filter` 临时修正 DSCP 映射，流量恢复。
- T+30min：云厂商修复 CCN 策略下发逻辑，验证 EF 端到端透传。
- T+2h：会议质量恢复，MOS 回升 4.2+。

## 防复发措施
- [ ] **监控增强**：新增 `net.dscp_mismatch` 指标 (eBPF 对比 IP 头与 TC 类)，告警阈值 > 0。
- [ ] **混沌演练**：每月注入“DSCP 重写”故障，验证根因定位自动识别为 `qos_policy_lost`。
- [ ] **架构优化**：评估媒体流量绕过 CCN，改走专线/云厂商骨干网直连。

## 标签体系更新
- 新增根因标签：`qos_policy_lost` (归属：网络基础设施)
- 更新规则引擎：`IF dscp_sent != dscp_received AND loss > 1% THEN qos_policy_lost`