feat: gate the automatic ALTER behind an explicit mode

两个 recorder 的 `__init__` 增 keyword-only 必填 `auto_migrate`(设计 D-c: 缺省规则只写在 config 一处,不与类签名漂移),并把写入语句从模块级常量改为实例级: manual 档探测到旧表缺列时一条 ALTER 都不发,改按现有列裁剪 INSERT, 准备期发一次 warning(逐列点名 + "以下维度不会被记录" + 可直接执行的补列 SQL)。裁剪是关掉 ALTER 的前提而非增强: 旧表缺列时若既不 ALTER 又不裁剪,每一行 INSERT 都撞 `no column named tenant_id` 被整行丢弃,比自动 ALTER 更严重地违反"遥测必录"。auto 档行为逐字不变(先探测后 ALTER、duplicate column 视为成功、失败只 warning 不判死、写入沿用全量列)。探测失败、或探测结果与 COLUMNS 毫无交集,两档都保守回落全量列——空列集会让 `insert_sql` 产出 `INSERT INTO llm_calls () VALUES ()`(它不拒空列表,空集技术上是子集)。PG 侧 `_columns`/`_insert` 与 `_schema_ready` 在同一处一起赋值,不留"已就绪但语句还是旧的"窗口。同批改 `GatewaySettings.telemetry_auto_migrate`(按后端派生: PG False、 SQLite True)与 `client._build_telemetry` 透传: 签名变更与其唯一调用点必须落在同一次提交,否则该提交点整条装配路 TypeError。env 键留给下一步。
2026-08-19 11:57:41 -04:00
parent ecc22b34fc
commit e949edb62a
8 changed files with 466 additions and 73 deletions
@@ -35,13 +35,60 @@ _EXISTING_COLUMNS = (
    "WHERE attrelid = to_regclass('llm_calls') AND attnum > 0 AND NOT attisdropped"
 )

-_INSERT = insert_sql("postgres", COLUMNS)
+# 缺列 warning 要打印可直接执行的补列语句,与库内 ALTER 同源(不许两份)
+_BACKFILL_STATEMENTS = dict(PG_BACKFILL)
+
+
+def _missing_columns_message(missing: list[str], *, alien_table: bool) -> str:
+    """拼 manual 档的缺列告警: 逐列点名 + 讲清后果 + 给出可直接执行的 SQL。
+
+    只说"缺列"是不够的: 静默丢维度的后果是多租户账目全归空串且无任何报错,
+    看告警的人必须一眼看到丢的是哪几个维度、以及怎么补。
+
+    Args:
+        missing: 缺失的列名(按 `COLUMNS` 保序)。
+        alien_table: 连主键列 `call_id` 都没有——该表多半不是本库的 `llm_calls`。
+
+    Returns:
+        单条 warning 的完整文本(库只在准备期发一次,不逐行发)。
+    """
+    statements = [
+        f"{_BACKFILL_STATEMENTS[column]};" for column in missing if column in _BACKFILL_STATEMENTS
+    ]
+    unknown = [column for column in missing if column not in _BACKFILL_STATEMENTS]
+    if unknown:
+        # 这些列本库从未经 ALTER 补过(建表即有),给不出单条 ALTER,指向完整脚本
+        statements.append(
+            f"-- 另缺 {', '.join(unknown)};完整建表脚本见 "
+            'polygateway.telemetry_schema_sql("postgres")'
+        )
+    head = (
+        "Postgres 遥测表 llm_calls 缺主键列 call_id,很可能不是本库的遥测表"
+        "(库不做二次判定,仍照常尝试写入)"
+        if alien_table
+        else "Postgres 遥测表 llm_calls 缺列,且 auto_migrate=False(库不发任何 DDL)"
+    )
+    return (
+        f"{head};以下维度不会被记录: {', '.join(missing)}。"
+        "补列请自行执行(建议挑低峰,ALTER 取 ACCESS EXCLUSIVE 锁):\n" + "\n".join(statements)
+    )


 class PostgresRecorder:
    """TelemetryRecorder 端口的 Postgres 实现;asyncpg 原生异步,无线程桥接。"""

-    def __init__(self, dsn: str, *, pool: asyncpg.Pool | None = None) -> None:
+    def __init__(self, dsn: str, *, pool: asyncpg.Pool | None = None, auto_migrate: bool) -> None:
+        """记下装配参数(不连库);列与 INSERT 语句在首次准备期定型。
+
+        Args:
+            dsn: asyncpg 连接串(已剥驱动后缀)。
+            pool: 外部注入的池;注入方自己负责关闭。
+            auto_migrate: True 则给已存在的旧表自动补列;False(PG 侧的缺省档)
+                则一条 ALTER 都不发——`ALTER TABLE ADD COLUMN` 取 ACCESS EXCLUSIVE
+                锁,会排在长事务后阻塞该表其后所有查询,而遥测是业务路径上的内联
+                await。keyword-only **必填**: 缺省规则只写在 config 一处,不与本类
+                签名漂移(设计 D-c)。
+        """
        try:
            import asyncpg  # noqa: F401 - 仅探测 extra 是否安装
        except ImportError as exc:
@@ -51,6 +98,10 @@ class PostgresRecorder:
        self._dsn = dsn
        self._pool: asyncpg.Pool | None = pool
        self._external_pool = pool is not None
+        self._auto_migrate = auto_migrate
+        # 先按全量列定型: 准备期探测失败时保守沿用全量(今天的行为)
+        self._columns: tuple[str, ...] = COLUMNS
+        self._insert = insert_sql("postgres", COLUMNS)
        self._schema_ready = False
        self._failed = False  # 结构性降级标志: 置位后所有写入短路
        self._init_lock = asyncio.Lock()
@@ -93,7 +144,7 @@ class PostgresRecorder:
        """备好表并交回可用的池;瞬时失败只跳过本次,确定写不进去才判死。"""
        try:
            async with pool.acquire() as conn:
-                writable = await self._prepare_table(conn)
+                columns = await self._prepare_table(conn)
        except asyncio.CancelledError:
            raise
        except Exception as exc:
@@ -101,14 +152,20 @@ class PostgresRecorder:
            # 只跳过本次记录,下次调用重新准备
            logger.warning("Postgres 遥测建表探测失败(跳过本条,下次重试): {}", exc)
            return None
-        if not writable:
+        if columns is None:
            self._failed = True
            return None
+        # 写入列、语句与就绪标志必须**一起**生效: `_ensure_ready` 只看 `_schema_ready`
+        # 就绕开 `_init_lock` 直接返回池,先置就绪会开出"已就绪但语句还是旧的"的窗口
+        self._columns = columns
+        self._insert = insert_sql("postgres", columns)
        self._schema_ready = True
        return pool

-    async def _prepare_table(self, conn: object) -> bool:
-        """备好 `llm_calls`;**表存在就绝不发 DDL**。返回 False 仅表示表确定不存在。
+    async def _prepare_table(self, conn: object) -> tuple[str, ...] | None:
+        """备好 `llm_calls` 并返回本实例要写的列;**表存在就绝不发 DDL**。
+
+        返回 None 仅表示表确定不存在且建不出来(唯一允许判死的情形)。

        `CREATE TABLE IF NOT EXISTS` 不能无条件发: PostgreSQL 对 schema 的
        CREATE 权限检查**早于** `IF NOT EXISTS` 的存在性判断(PG 16.14 实测:
@@ -121,32 +178,74 @@ class PostgresRecorder:
        """
        exists = await conn.fetchval(_TABLE_EXISTS) is not None  # type: ignore[attr-defined]
        if exists:
-            await self._backfill_columns(conn)  # 旧表可能缺列;失败只逐行降级
-            return True
+            return await self._resolve_columns(conn)  # 旧表可能缺列
        try:
            await conn.execute(PG_DDL)  # type: ignore[attr-defined]
        except asyncio.CancelledError:
            raise
        except Exception as exc:
            logger.warning("Postgres 遥测建表失败(表不存在,记录无处可落): {}", exc)
-            return False
-        return True  # 新建表列已齐全,无需再走补列
+            return None
+        return COLUMNS  # 新建表列已齐全,无需再走补列

-    async def _backfill_columns(self, conn: object) -> None:
-        """给已存在的旧表补新列(issue #3);**先探测再 ALTER,失败绝不置 `_failed`**。
+    async def _resolve_columns(self, conn: object) -> tuple[str, ...]:
+        """探测旧表现有列并定型写入列: auto 档先补齐,manual 档改为裁剪(issue #13)。

-        两条纪律各有实测理由:
-        ① 不置 `_failed`: 应用账号只有 INSERT 权限时,`ALTER TABLE` 的 ownership
-           检查早于 `IF NOT EXISTS` 的存在性判断——列明明齐全也会失败。置位会让
-           整个 recorder 永久 no-op,与「补列失败只降级为逐行丢弃」的承诺相悖
-           (SQLite 侧同款守卫,两侧必须对称)。
-        ② 先探测: `ADD COLUMN IF NOT EXISTS` 即便列已存在,也会**先取 ACCESS
-           EXCLUSIVE 锁**再判存在性(实测会被一个开着的读事务阻塞)。遥测是内联
-           await,让每个进程的首次写入都去抢共享审计表的排他锁,等于用记录基础设施
-           拖垮业务调用。探测走 ACCESS SHARE,稳态下一条 ALTER 都不会发。
+        **先探测**的理由(两档共用): `ADD COLUMN IF NOT EXISTS` 即便列已存在,也会
+        **先取 ACCESS EXCLUSIVE 锁**再判存在性(实测会被一个开着的读事务阻塞)。遥测是
+        内联 await,让每个进程的首次写入都去抢共享审计表的排他锁,等于用记录基础设施
+        拖垮业务调用。探测走 ACCESS SHARE,稳态下一条 ALTER 都不会发。
+
+        探测失败保守沿用全量列(今天的行为): 猜不出真实列集合时,让写入照常尝试。
        """
        try:
            existing = {row["attname"] for row in await conn.fetch(_EXISTING_COLUMNS)}  # type: ignore[attr-defined]
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            logger.warning("Postgres 遥测列探测失败(沿用全量列,写入将逐行降级): {}", exc)
+            return COLUMNS
+        if self._auto_migrate:
+            await self._backfill_columns(conn, existing)
+            return COLUMNS
+        return self._trim_columns(existing)
+
+    def _trim_columns(self, existing: set[str]) -> tuple[str, ...]:
+        """manual 档: 按现有列裁剪写入列,并把缺列一次讲清楚。
+
+        裁剪是关掉 ALTER 的**前提**而非增强: 旧表缺列时仍发全量 INSERT,每一行
+        都会因未知列被拒 → 遥测彻底丢失,比自动 ALTER 更严重地违反"遥测必录"。
+        探测结果与 `COLUMNS` 毫无交集时视同探测异常保守回落全量: 空列集会构造出
+        `INSERT INTO llm_calls () VALUES ()` 这种语法非法的语句(`insert_sql` 拦
+        不住——空集技术上是子集),必须在交给它之前拦下。
+        """
+        effective = tuple(column for column in COLUMNS if column in existing)
+        if not effective:
+            logger.warning(
+                "Postgres 遥测表 llm_calls 没有任何本库认识的列(沿用全量列,写入将逐行降级);"
+                "现有列: {}",
+                sorted(existing),
+            )
+            return COLUMNS
+        missing = [column for column in COLUMNS if column not in existing]
+        if missing:
+            # 单参数传入: 补列 SQL 里带 `'{}'::jsonb` 字面量,拼进 format 模板会被当占位符
+            logger.warning(
+                "{}", _missing_columns_message(missing, alien_table="call_id" not in existing)
+            )
+        return effective
+
+    async def _backfill_columns(self, conn: object, existing: set[str]) -> None:
+        """auto 档: 给已存在的旧表补新列(issue #3);**失败绝不置 `_failed`**。
+
+        不置 `_failed` 的实测理由: 应用账号只有 INSERT 权限时,`ALTER TABLE` 的
+        ownership 检查早于 `IF NOT EXISTS` 的存在性判断——列明明齐全也会失败。置位会让
+        整个 recorder 永久 no-op,与「补列失败只降级为逐行丢弃」的承诺相悖
+        (SQLite 侧同款守卫,两侧必须对称)。补列失败后写入沿用全量列(今天的行为):
+        auto 档承诺的是"把列补上",补不上就让缺列以逐行 warning 暴露;要降级写入
+        请显式选 manual。
+        """
+        try:
            for column, statement in PG_BACKFILL:
                if column not in existing:
                    await conn.execute(statement)  # type: ignore[attr-defined]
@@ -156,14 +255,18 @@ class PostgresRecorder:
            logger.warning("Postgres 遥测补列失败(写入将逐行降级): {}", exc)

    async def record_llm_call(self, **fields: object) -> None:
-        """写一行遥测;单条失败逐条 warning 丢弃(两级降级之二),绝不冒泡。"""
+        """写一行遥测;单条失败逐条 warning 丢弃(两级降级之二),绝不冒泡。
+
+        取值按 `self._columns`(manual 档可能已被裁剪),与 `self._insert` 的
+        占位符同序——两者必须一起改,分开改就是把值写进错位的列。
+        """
        pool = await self._ensure_ready()
        if pool is None:
            return
-        row = tuple(fields[col] for col in COLUMNS)
+        row = tuple(fields[col] for col in self._columns)
        try:
            async with pool.acquire() as conn:
-                await conn.execute(_INSERT, *row)
+                await conn.execute(self._insert, *row)
        except asyncio.CancelledError:
            raise
        except Exception as exc: