《移动游戏产品的架构·客户端与移动运行时》12.2 日志分级、采样与隐私脱敏

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

export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";

export const LEVEL_RANK: Readonly<Record<LogLevel, number>> = {
  trace: 10,
  debug: 20,
  info: 30,
  warn: 40,
  error: 50,
  fatal: 60,
};

export interface SamplingPolicy {
  readonly minLevel: LogLevel;
  readonly rates: Readonly<Record<LogLevel, number>>;
  readonly maxPerEventPerSession: number;
}

export const DEFAULT_POLICY: SamplingPolicy = {
  minLevel: "info",
  rates: { trace: 0, debug: 0.05, info: 0.2, warn: 0.8, error: 1, fatal: 1 },
  maxPerEventPerSession: 20,
};

export interface LogRecord {
  readonly level: LogLevel;
  readonly event: string;
  readonly sessionId: string;
  readonly tsMs: number;
  readonly fields: Readonly<Record<string, unknown>>;
}

export type DropReason = "below-level" | "sampled-out" | "rate-limited";
export type KeepReason = "full-rate" | "sampled";

export interface Decision {
  readonly keep: boolean;
  readonly reason: KeepReason | DropReason;
  readonly bucket: 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 bucketOf(sessionId: string, event: string): number {
  return hash32(`${sessionId}|${event}`) % 10_000;
}

export class LogSampler {
  readonly #policy: SamplingPolicy;
  readonly #counts = new Map<string, number>();

  constructor(policy: SamplingPolicy = DEFAULT_POLICY) {
    this.#policy = policy;
  }

  decide(record: LogRecord): Decision {
    if (LEVEL_RANK[record.level] < LEVEL_RANK[this.#policy.minLevel]) {
      return { keep: false, reason: "below-level", bucket: -1 };
    }
    const rate = this.#policy.rates[record.level];
    if (rate <= 0) {
      return { keep: false, reason: "sampled-out", bucket: -1 };
    }
    const bucket = bucketOf(record.sessionId, record.event);
    if (rate < 1 && bucket >= Math.floor(rate * 10_000)) {
      return { keep: false, reason: "sampled-out", bucket };
    }
    const key = `${record.sessionId}|${record.event}`;
    const count = this.#counts.get(key) ?? 0;
    if (count >= this.#policy.maxPerEventPerSession) {
      return { keep: false, reason: "rate-limited", bucket };
    }
    this.#counts.set(key, count + 1);
    return { keep: true, reason: rate >= 1 ? "full-rate" : "sampled", bucket };
  }

  countOf(sessionId: string, event: string): number {
    return this.#counts.get(`${sessionId}|${event}`) ?? 0;
  }

  resetSession(sessionId: string): void {
    const prefix = `${sessionId}|`;
    for (const key of [...this.#counts.keys()]) {
      if (key.startsWith(prefix)) {
        this.#counts.delete(key);
      }
    }
  }
}

export function maskEmail(value: string): string {
  const at = value.indexOf("@");
  if (at <= 0) {
    return "[email]";
  }
  const local = value.slice(0, at);
  const domain = value.slice(at + 1);
  return `${local.slice(0, 1)}***@${domain}`;
}

export function maskPhone(value: string): string {
  const digits = value.replace(/\D/g, "");
  if (digits.length < 7) {
    return "[phone]";
  }
  return `${digits.slice(0, 3)}****${digits.slice(-4)}`;
}

export function truncateIp(value: string): string {
  if (value.includes(":")) {
    const groups = value.split(":").filter((group) => group.length > 0);
    if (groups.length < 3) {
      return "[ip]";
    }
    return `${groups.slice(0, 3).join(":")}::`;
  }
  const parts = value.split(".");
  if (parts.length !== 4) {
    return "[ip]";
  }
  return `${parts[0]}.${parts[1]}.${parts[2]}.0`;
}

export function pseudonymize(value: string, salt: string, day: string): string {
  const left = hash32(`${salt}:${day}:${value}`).toString(16).padStart(8, "0");
  const right = hash32(`${value}:${day}:${salt}`).toString(16).padStart(8, "0");
  return `${left}${right}`;
}

export function scrubText(text: string): string {
  return text
    .replace(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, "[email]")
    .replace(/(?<!\d)1[3-9]\d{9}(?!\d)/g, "[phone]")
    .replace(/\b\d{15,18}\b/g, "[id]")
    .replace(/\b(?:token|key|secret|password)\s*=\s*[^&\s]+/gi, "[secret]")
    .replace(/\b[0-9a-f]{32,}\b/gi, "[hex]");
}

export type RedactionMode = "mask" | "hash" | "truncate-ip" | "drop";

export interface RedactionRule {
  readonly pattern: RegExp;
  readonly mode: RedactionMode;
}

export const REDACTION_RULES: readonly RedactionRule[] = [
  { pattern: /^(user_?id|uid|account_?id|role_?id)$/i, mode: "hash" },
  { pattern: /^(device_?id|imei|idfa|aaid|oaid|android_?id|mac_?addr(ess)?|installation_?id)$/i, mode: "hash" },
  { pattern: /^(phone|mobile|tel)$/i, mode: "mask" },
  { pattern: /^(email|mail)$/i, mode: "mask" },
  { pattern: /^(ip|client_?ip|remote_?addr)$/i, mode: "truncate-ip" },
  { pattern: /^(token|access_?token|refresh_?token|session_?token|password|passwd|secret|auth|signature)$/i, mode: "drop" },
  { pattern: /^(order_?id|transaction_?id|pay_?id)$/i, mode: "hash" },
  { pattern: /^(free_?text|message|comment|nickname|player_?name|chat)$/i, mode: "drop" },
];

export const SAFE_FIELDS: ReadonlySet<string> = new Set([
  "event",
  "level",
  "tsMs",
  "sessionId",
  "appVersion",
  "osVersion",
  "deviceModel",
  "channel",
  "region",
  "scene",
  "errorCode",
  "durationMs",
  "network",
  "result",
]);

export function redactField(key: string, value: unknown, salt: string, day: string): string | undefined {
  const rule = REDACTION_RULES.find((item) => item.pattern.test(key));
  const text = typeof value === "string" ? value : String(value);
  if (!rule) {
    return scrubText(text);
  }
  switch (rule.mode) {
    case "hash":
      return pseudonymize(text, salt, day);
    case "mask":
      return /mail|email/i.test(key) ? maskEmail(text) : maskPhone(text);
    case "truncate-ip":
      return truncateIp(text);
    case "drop":
      return undefined;
  }
}

export interface RedactedRecord {
  readonly level: LogLevel;
  readonly event: string;
  readonly sessionId: string;
  readonly tsMs: number;
  readonly fields: Readonly<Record<string, string>>;
  readonly dropped: readonly string[];
}

export function redactRecord(
  record: LogRecord,
  salt: string,
  day: string,
  allow: ReadonlySet<string> = SAFE_FIELDS,
): RedactedRecord {
  const fields: Record<string, string> = {};
  const dropped: string[] = [];
  for (const [key, value] of Object.entries(record.fields)) {
    const knownSensitive = REDACTION_RULES.some((item) => item.pattern.test(key));
    if (!knownSensitive && !allow.has(key)) {
      dropped.push(key);
      continue;
    }
    const redacted = redactField(key, value, salt, day);
    if (redacted === undefined) {
      dropped.push(key);
      continue;
    }
    fields[key] = redacted;
  }
  return {
    level: record.level,
    event: record.event,
    sessionId: pseudonymize(record.sessionId, salt, day),
    tsMs: record.tsMs,
    fields,
    dropped,
  };
}