第十八章　可观测性：Sentry、日志与调试

def _mask_user_paths(text: str) -> str:
    """
    将用户路径中的用户名替换为 ***，跨平台支持。

    替换规则：
    - macOS: /Users/username/... → /Users/***/...
    - Windows: C:\\Users\\username\\... → C:\\Users\\***\\...
    - Linux: /home/username/... → /home/***/...
    - WSL: /mnt/c/Users/username/... → /mnt/c/Users/***/...
    """
    # macOS
    text = re.sub(r"/Users/[^/]+(?=/|$)", "/Users/***", text)

    # Windows（保留盘符）
    text = re.sub(
        r"[A-Za-z]:\\Users\\[^\\]+(?=\\|$)",
        lambda m: f"{m.group(0)[0]}:\\Users\\***",
        text,
    )

    # Linux
    text = re.sub(r"/home/[^/]+(?=/|$)", "/home/***", text)

    # WSL
    text = re.sub(
        r"/mnt/[a-z]/Users/[^/]+(?=/|$)",
        lambda m: f"{m.group(0)[:6]}/Users/***",
        text,
    )

    return text

def _mask_object_paths(obj: Any, _depth: int = 0) -> Any:
    """递归脱敏对象中的所有路径字符串。"""
    # 防止无限递归（循环引用或深度嵌套结构）
    if _depth > 50:
        return obj

    if obj is None:
        return obj
    if isinstance(obj, str):
        return _mask_user_paths(obj)
    if isinstance(obj, list):
        return [_mask_object_paths(item, _depth + 1) for item in obj]
    if isinstance(obj, dict):
        return {
            key: _mask_object_paths(value, _depth + 1)
            for key, value in obj.items()
        }

    # 其他类型（int, float, bool 等）直接返回
    return obj

def _before_send(event: dict, hint: dict) -> dict | None:
    """Sentry 发送前的最后处理：脱敏所有路径。"""
    # 递归脱敏整个 event 对象
    return _mask_object_paths(event)

def _get_version() -> str:
    """读取前端 package.json 中的版本号，保持前后端版本一致。"""
    try:
        backend_dir = Path(__file__).parent.parent
        frontend_dir = backend_dir.parent / "frontend"
        package_json = frontend_dir / "package.json"

        if package_json.exists():
            with open(package_json, encoding="utf-8") as f:
                data = json.load(f)
                return data.get("version", "0.0.0")
    except Exception as e:
        logger.debug(f"Version detection failed: {e}")

    return "0.0.0"

// apps/frontend/src/shared/utils/debug-logger.ts（概念化）

const isDebug = process.env.DEBUG === 'true';

export function debugLog(message: string, ...args: unknown[]): void {
  if (!isDebug) return;  // 生产环境静默
  console.log(`[DEBUG] ${message}`, ...args);
}

export function debugError(message: string, ...args: unknown[]): void {
  if (!isDebug) return;
  console.error(`[DEBUG ERROR] ${message}`, ...args);
}

# 每个模块都声明自己的 logger
import logging
logger = logging.getLogger(__name__)

# 使用示例（来自 sentry.py）
logger.debug(f"Version detection failed: {e}")
logger.info("Sentry initialized with version %s", version)
logger.warning("SENTRY_DSN not set, Sentry disabled")
logger.error("Failed to initialize Sentry: %s", e)

# 启动调试模式
npm run dev:debug

# 设置 MCP 标志
echo "ELECTRON_MCP_ENABLED=true" >> apps/backend/.env

# 运行 QA（QA 智能体可以控制 UI）
python run.py --spec 001 --qa

# sentry.py
PRODUCTION_TRACE_SAMPLE_RATE = 0.1  # 10% 的请求会被追踪

def init_sentry():
    sentry_sdk.init(
        dsn=os.environ.get('SENTRY_DSN'),
        traces_sample_rate=PRODUCTION_TRACE_SAMPLE_RATE,
        environment=_get_environment(),
        release=_get_version(),
        before_send=_before_send,
    )

# lab18/path_masker.py
import re

def mask_user_paths(text: str) -> str:
    """
    脱敏文件路径中的用户名。
    支持 macOS、Windows、Linux 和 WSL。
    """
    if not text:
        return text

    # TODO Part A: 实现路径脱敏
    # 提示：使用 re.sub()，注意边界匹配
    # macOS: /Users/username/... → /Users/***/...
    # Linux: /home/username/... → /home/***/...
    # Windows: C:\Users\username\... → C:\Users\***\...

    return text

def mask_object_paths(obj, _depth: int = 0):
    """递归脱敏对象中所有字符串字段的路径。"""
    # TODO Part A:
    # - depth > 50 时返回原始值（防止无限递归）
    # - str → 调用 mask_user_paths
    # - list → 递归处理每个元素
    # - dict → 递归处理每个值
    # - 其他类型 → 直接返回
    return obj

# 验证：
assert mask_user_paths("/Users/johndoe/project") == "/Users/***/project"
assert mask_user_paths("/home/alice/code") == "/home/***/code"
assert mask_user_paths("no path here") == "no path here"

data = {"error": "File not found: /Users/bob/work/main.py", "count": 42}
masked = mask_object_paths(data)
assert "bob" not in masked["error"]
assert masked["count"] == 42  # 非字符串类型不受影响

# lab18/logger.py
import os
import logging
from typing import Any

# 读取调试标志
DEBUG = os.environ.get('DEBUG', '').lower() in ('true', '1', 'yes')

def setup_logging(level: str = 'WARNING') -> None:
    """配置日志系统。DEBUG 模式下使用 DEBUG 级别。"""
    # TODO Part B: 配置 logging.basicConfig
    # DEBUG 模式：使用 DEBUG 级别，显示文件名和行号
    # 生产模式：使用 level 参数指定的级别，简单格式
    pass

def get_logger(name: str) -> logging.Logger:
    """获取模块 logger。"""
    return logging.getLogger(name)

# 使用示例（给调用方）：
# logger = get_logger(__name__)
# logger.debug("只在 DEBUG=true 时显示")
# logger.warning("总是显示")

// lab18/error-collector.ts

interface ErrorReport {
  message: string;
  stack?: string;
  context: Record<string, unknown>;
  timestamp: number;
  masked: boolean;  // 是否已脱敏
}

export class ErrorCollector {
  private reports: ErrorReport[] = [];
  private maskFn: (text: string) => string;

  constructor(maskFn?: (text: string) => string) {
    // TODO Part C: 保存 maskFn，默认使用 identity 函数
    this.maskFn = maskFn ?? ((text) => text);
  }

  /**
   * 收集错误，自动脱敏路径
   */
  capture(error: Error, context: Record<string, unknown> = {}): void {
    // TODO Part C:
    // 1. 创建 ErrorReport
    // 2. 对 message 和 stack 调用 maskFn
    // 3. 对 context 的每个字符串值调用 maskFn
    // 4. 推入 reports 列表
  }

  /**
   * 获取最近 N 条报告
   */
  getRecentReports(n: number = 10): ErrorReport[] {
    // TODO Part C
    return [];
  }

  /**
   * 清空报告
   */
  clear(): void {
    this.reports = [];
  }
}

// 验证：
const masker = (text: string) => text.replace(/\/Users\/[^/]+/g, '/Users/***');
const collector = new ErrorCollector(masker);

const err = new Error('Failed to read /Users/alice/project/config.json');
collector.capture(err, { path: '/Users/alice/project' });

const reports = collector.getRecentReports(1);
console.log(reports[0].message); // → 'Failed to read /Users/***/project/config.json'
console.log(reports[0].context.path); // → '/Users/***/project'
console.log(reports[0].masked); // → true