查询、过滤、采样、脱敏、导出与用量

数据治理的顺序应是：先决定什么不能离开进程，再决定记录多少，最后决定如何检索和导出。UI 隐藏字段不是脱敏，采样也不能替代敏感数据控制。

一、三层控制

二、查询模型

UI 的 filter builder 最适合日常排查；SDK/API 的 filter DSL 适合自动化。可筛：

• run name、run type、status/error。
• trace、run、project、thread 标识。
• start/end time、latency、TTFT。
• tags 和 metadata。
• token、input/output/total cost。
• feedback key、score 和是否存在。

DSL 常见思想：

and(eq(name, "agent"), gt(latency, 2)) has(metadata, '{"environment":"prod"}') and(eq(run_type, "llm"), gt(total_tokens, 1000))

具体字段和操作符以当前 Trace query syntax 为准；不要把 UI 文案直接拼成 DSL。保存的视图应纳入变更审查，因为字段重命名会让规则静默失配。

三、Thread 查询

Thread 查询需要 project/session 与 thread ID 语义一致。可查询：

• thread 的 traces/messages。
• thread 时间范围和聚合统计。
• thread 级 feedback。
• 满足 trace filter 的 thread stats。

多轮评估前先验证：

• 相同用户的不同业务会话没有复用 thread ID。
• 同一会话没有因服务重启产生多个 ID。
• 迟到 trace 能进入正确 thread。
• thread idle window 足以覆盖完整会话。

四、Semantic Search

语义搜索用于按含义寻找相似 trace，而不是精确条件过滤。适合：

• 找相似失败、用户意图或输出模式。
• 从生产 trace 建候选数据集。
• 辅助聚类与根因分析。

不适合替代：

• ID、时间、环境、状态等精确筛选。
• 合规发现和删除。
• 可重复的告警条件。

生产检索应先用精确过滤缩小环境/版本/时间，再做语义搜索，减少跨租户或跨版本误匹配。

五、条件追踪与采样

条件追踪用于按业务条件启停，例如：

• 只追 prod 的特定功能。
• 对内部健康检查禁用。
• 对已获用户同意的会话启用完整 trace。

随机采样用于按比例保留。采样策略要明确：

• root 级决策，整棵 trace 一致，避免只有孤儿子 run。
• 错误、超时、关键租户可提高采样率。
• 采样率写入 metadata，统计时才能校正。
• 先脱敏再采样；未被抽中的数据也可能在采样决策前经过内存/日志。

LangSmith SDK 的采样和 OTel sampler 处于不同层。混合接入时只能指定一个主决策源，避免双重 10% 变成约 1%。

六、Mask 与 Anonymizer

常见模式：

• 全隐藏：inputs/outputs 只上传空或固定占位。
• 正则/函数 anonymizer：替换邮箱、电话、账号、token。
• Presidio 或 Amazon Comprehend：实体识别后替换。
• 自定义 processor：按 schema 删除字段或只保留白名单。

批处理回调必须保持输入 run 与输出 run 的数量、顺序、ID 一一对应，否则会把内容写到错误 run。脱敏函数应：

• 对异常 fail closed，不能因识别器失败而上传原文。
• 保留必要结构，例如角色、长度、工具名，而不是破坏整条消息。
• 有确定性占位符，便于同 trace 内关联，但不能可逆。
• 对 attachments、tool arguments、metadata、错误栈分别覆盖。

七、OTel Gateway redaction

OTel Collector 可在出口前通过 transform/processor 删除或替换 span attributes/events。它适合统一处理多语言服务，但要注意：

• LangSmith 特有字段、GenAI semantic conventions 和自定义字段都需列入规则。
• 删除 <code>gen_ai.prompt</code> 不会自动删除其他 message/event 属性。
• Collector 日志、debug exporter 和失败队列也可能泄露原文。
• 规则升级要用固定样本回归，避免字段改名后失效。

八、导出

SDK export 适合小批查询和脚本；Bulk Export 适合大规模、定期数据管道。可导出 runs、trace/thread 相关字段，近期更新支持显式选择 feedbacks 列。

生产导出要求：

• 固定时间窗口与游标，支持断点续传和去重。
• 输出落到受控对象存储，启用加密、最小权限和生命周期。
• 记录导出 schema/version。
• 对删除/合规请求建立下游传播机制。
• 大文件优先 zstd；自托管旧路径可能仍默认 gzip。

BigQuery Bulk Export 是仓库化方案，不等于实时告警通道。需单独处理分区、成本、schema 演进、重复 run update 和迟到数据。

九、Granular Usage

Granular Usage 用于查看组织范围的可计费用量，可按 workspace、项目、保留层等维度过滤/分组。解释数字时区分：

• trace 数与 run 数。
• base/short-lived 与 extended/long-lived retention。
• Observability、Evaluation、Deployment、Gateway/Fleet 等不同产品单位。
• 当前 workspace 页面和组织账单的范围。

不要把 trace UI 当前查询行数当作计费量；采样、保留升级、反馈/annotation queue 行为和组织限额都会影响最终用量。

十、治理基线

• ○ 数据分类表覆盖 prompt、completion、tool、retrieval、metadata、attachment 和 error。
• ○ SDK 与 OTel 各自只有一套明确的脱敏责任。
• ○ 采样在 root 统一决策，错误/高价值路径有保留策略。
• ○ 导出有加密、审计、生命周期和删除传播。
• ○ 保存的 filter/rule 有 owner、版本和失配监控。
• ○ 用量按组织、workspace、project 与 retention 层定期对账。