《移动游戏产品的架构·客户端与移动运行时》12.3 线上问题定位闭环

// file: src/obs/event.ts
// tier: L1
// verify: node --test test/obs/event.test.ts

export type ObsKind = "crash" | "anr" | "jank" | "error";

export interface Dimensions {
  readonly version: string;
  readonly model: string;
  readonly channel: string;
  readonly region: string;
}

export type DimensionKey = keyof Dimensions;

export const DIMENSION_KEYS: readonly DimensionKey[] = ["version", "model", "channel", "region"];

export interface ObsEvent {
  readonly tsMs: number;
  readonly kind: ObsKind;
  readonly signature: string;
  readonly dims: Dimensions;
  readonly weight?: number;
}

export interface Exposure {
  readonly dims: Dimensions;
  readonly sessions: number;
  readonly renderedFrames?: number;
}

export function hash32(text: string): number {
  let hash = 0x811c9dc5;
  for (let index = 0; index < text.length; index += 1) {
    hash ^= text.charCodeAt(index);
    hash = Math.imul(hash, 0x01000193) >>> 0;
  }
  return hash >>> 0;
}

export function normalizeForFingerprint(message: string, topFrame: string): string {
  return `${message} @ ${topFrame}`
    .replace(/0x[0-9a-f]+/gi, "0x?")
    .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "<uuid>")
    .replace(/\b\d{6,}\b/g, "#")
    .replace(/\s+/g, " ")
    .trim();
}

export function fingerprint(message: string, topFrame: string): string {
  return hash32(normalizeForFingerprint(message, topFrame)).toString(16).padStart(8, "0");
}

export interface Interval {
  readonly low: number;
  readonly high: number;
}

export function wilsonInterval(successes: number, total: number, z = 1.96): Interval {
  if (total <= 0) {
    return { low: 0, high: 1 };
  }
  const p = successes / total;
  const z2 = z * z;
  const denominator = 1 + z2 / total;
  const center = (p + z2 / (2 * total)) / denominator;
  const margin = (z * Math.sqrt((p * (1 - p) + z2 / (4 * total)) / total)) / denominator;
  return { low: Math.max(0, center - margin), high: Math.min(1, center + margin) };
}

export interface AlertConfig {
  readonly baseline: number;
  readonly minSessions: number;
  readonly minLift: number;
  readonly z: number;
}

export const DEFAULT_ALERT_CONFIG: AlertConfig = {
  baseline: 0.0018,
  minSessions: 2000,
  minLift: 1.5,
  z: 1.96,
};

export type AlertReason = "ok" | "insufficient-sample" | "below-threshold" | "regression";

export interface AlertDecision {
  readonly alert: boolean;
  readonly reason: AlertReason;
  readonly rate: number;
  readonly lift: number;
  readonly interval: Interval;
}

export function evaluateAlert(
  count: number,
  denominator: number,
  config: AlertConfig = DEFAULT_ALERT_CONFIG,
): AlertDecision {
  if (!Number.isInteger(count) || !Number.isInteger(denominator)) {
    throw new RangeError("count and denominator must be integers");
  }
  if (count < 0 || denominator < 0 || count > denominator) {
    throw new RangeError("count must be within [0, denominator]");
  }
  const interval = wilsonInterval(count, denominator, config.z);
  const rate = denominator === 0 ? 0 : count / denominator;
  const lift = config.baseline === 0 ? (rate > 0 ? Infinity : 0) : rate / config.baseline;
  if (denominator < config.minSessions) return { alert: false, reason: "insufficient-sample", rate, lift, interval };
  if (rate < config.baseline * config.minLift || interval.low <= config.baseline) return { alert: false, reason: "below-threshold", rate, lift, interval };
  return { alert: true, reason: "regression", rate, lift, interval };
}

export interface SliceStat {
  readonly values: Readonly<Record<string, string>>;
  readonly count: number;
  readonly denominator: number;
  readonly rate: number;
  readonly lift: number;
  readonly decision: AlertDecision;
}

export type DenominatorUnit = "sessions" | "frames";

export interface SliceReport {
  readonly unit: DenominatorUnit;
  readonly slices: readonly SliceStat[];
  readonly orphanEvents: number;
}

export class SliceAnalyzer {
  readonly #exposures: Exposure[] = [];
  readonly #events: ObsEvent[] = [];

  addExposure(exposure: Exposure): void {
    if (!Number.isInteger(exposure.sessions) || exposure.sessions < 0) {
      throw new RangeError("sessions must be a non-negative integer");
    }
    this.#exposures.push(exposure);
  }

  addEvent(event: ObsEvent): void {
    const weight = event.weight ?? 1;
    if (!Number.isInteger(weight) || weight < 0) {
      throw new RangeError("event weight must be a non-negative integer");
    }
    this.#events.push(event);
  }

  analyze(
    keys: readonly DimensionKey[],
    kind: ObsKind,
    config: AlertConfig = DEFAULT_ALERT_CONFIG,
  ): SliceReport {
    if (keys.length === 0) {
      throw new RangeError("slice needs at least one dimension");
    }
    const unit: DenominatorUnit = kind === "jank" ? "frames" : "sessions";
    const buckets = new Map<string, { values: Record<string, string>; sessions: number; frames: number; count: number }>();

    for (const exposure of this.#exposures) {
      const values = pick(exposure.dims, keys);
      const key = keyOf(values, keys);
      const bucket = buckets.get(key) ?? { values, sessions: 0, frames: 0, count: 0 };
      bucket.sessions += exposure.sessions;
      bucket.frames += exposure.renderedFrames ?? 0;
      buckets.set(key, bucket);
    }

    let orphanEvents = 0;
    for (const event of this.#events) {
      if (event.kind !== kind) {
        continue;
      }
      const weight = event.weight ?? 1;
      const values = pick(event.dims, keys);
      const bucket = buckets.get(keyOf(values, keys));
      if (!bucket) {
        orphanEvents += weight;
        continue;
      }
      bucket.count += weight;
    }

    const slices: SliceStat[] = [];
    for (const bucket of buckets.values()) {
      const denominator = unit === "frames" ? bucket.frames : bucket.sessions;
      if (denominator <= 0) {
        orphanEvents += bucket.count;
        continue;
      }
      const decision = evaluateAlert(bucket.count, denominator, config);
      slices.push({
        values: bucket.values,
        count: bucket.count,
        denominator,
        rate: decision.rate,
        lift: decision.lift,
        decision,
      });
    }
    slices.sort((left, right) => right.lift - left.lift || right.count - left.count);
    return { unit, slices, orphanEvents };
  }
}

function pick(dims: Dimensions, keys: readonly DimensionKey[]): Record<string, string> {
  const values: Record<string, string> = {};
  for (const key of keys) {
    values[key] = dims[key];
  }
  return values;
}

function keyOf(values: Record<string, string>, keys: readonly DimensionKey[]): string {
  return keys.map((key) => values[key]).join("\u0001");
}

export interface GrayArm {
  readonly crashes: number;
  readonly sessions: number;
}

export interface GrayConfig {
  readonly baseline: number;
  readonly tolerance: number;
  readonly minSessionsPerArm: number;
  readonly z: number;
}

export const DEFAULT_GRAY_CONFIG: GrayConfig = {
  baseline: 0.0018,
  tolerance: 0.0004,
  minSessionsPerArm: 5000,
  z: 1.96,
};

export type GrayVerdict = "continue" | "hold" | "rollback";

export interface GrayDecision {
  readonly verdict: GrayVerdict;
  readonly reason: string;
  readonly control: { readonly rate: number; readonly interval: Interval };
  readonly treatment: { readonly rate: number; readonly interval: Interval };
}

export function evaluateGray(
  control: GrayArm,
  treatment: GrayArm,
  config: GrayConfig = DEFAULT_GRAY_CONFIG,
): GrayDecision {
  for (const arm of [control, treatment]) {
    if (!Number.isInteger(arm.crashes) || !Number.isInteger(arm.sessions)) {
      throw new RangeError("gray arms need integer counts");
    }
    if (arm.crashes < 0 || arm.sessions < 0 || arm.crashes > arm.sessions) {
      throw new RangeError("gray arm crashes must be within [0, sessions]");
    }
  }
  const controlInterval = wilsonInterval(control.crashes, control.sessions, config.z);
  const treatmentInterval = wilsonInterval(treatment.crashes, treatment.sessions, config.z);
  const controlRate = control.sessions === 0 ? 0 : control.crashes / control.sessions;
  const treatmentRate = treatment.sessions === 0 ? 0 : treatment.crashes / treatment.sessions;
  const arms = {
    control: { rate: controlRate, interval: controlInterval },
    treatment: { rate: treatmentRate, interval: treatmentInterval },
  };
  if (control.sessions < config.minSessionsPerArm || treatment.sessions < config.minSessionsPerArm) return { verdict: "hold", reason: "insufficient-sample", ...arms };
  const threshold = config.baseline + config.tolerance;
  if (treatmentInterval.low > threshold) return { verdict: "rollback", reason: "treatment-ci-above-threshold", ...arms };
  if (treatmentRate <= threshold) return { verdict: "continue", reason: "within-tolerance", ...arms };
  return { verdict: "hold", reason: "point-above-but-ci-overlaps", ...arms };
}