启用 TTL 和数据保留

LangSmith 自托管支持对追踪自动执行 TTL 和数据保留。你可以使用此功能来遵守数据隐私法规，或通过自动清理旧追踪来减少存储占用。运行规则和其他符合条件的操作也可以自动延长追踪的保留期。

NOTE

自托管企业版客户： 你可以通过 UI 在工作区层级配置延长数据保留。无需更改环境变量。请参阅自定义延长保留策略。本页介绍的系统级 TTL 配置仍然受支持。

TTL 配置优先级

LangSmith 通过两个步骤确定追踪的保留时长：追踪属于哪个保留层级，以及该层级适用多长时间。

LangSmith 按以下顺序分配层级，优先级从高到低：

1. 追踪升级：运行规则或其他符合条件的操作会将单个追踪提升为 longlived，覆盖原本适用的任何层级。
2. 项目层级：为追踪项目配置的层级。
3. 工作区默认值：新项目会继承此层级。更改它只会影响新项目，除非你将其应用到所有现有项目。
4. 组织默认值：适用于没有自己默认值的工作区。
5. shortlived：未设置默认值时的回退。

然后，LangSmith 会解析所分配层级的保留期：

• longlived：工作区延长保留期（如果通过 UI 设置），否则使用 Helm 配置中的 longlived 值。
• shortlived：Helm 配置中的 shortlived 值。

Helm chart 默认将 shortlived 设为 14 天，将 longlived 设为 400 天。

要求

通过 Helm 或环境变量设置配置保留：

• Enabled：启用或禁用自动数据保留。启用后，通过 UI 设置默认组织和项目 TTL 层级（请参阅数据保留指南）。
• 保留期：设置 shortlived 和 longlived 追踪的系统级保留期。设置后，可以在项目级别管理保留，或为新项目设置组织范围的默认值。

config:
  ttl:
    enabled: true
    ttl_period_seconds:
      # -- 400 day longlived and 14 day shortlived
      longlived: "34560000"
      shortlived: "1209600"

ClickHouse TTL 清理作业

从 0.11 版本开始，周末会运行一个 cron 作业，删除 ClickHouse 内置 TTL 机制可能未清理的过期数据。

WARNING

此作业使用 mutations（ALTER TABLE DELETE），这是开销很大的操作，可能影响 ClickHouse 性能。请仅在非高峰时段（夜间和周末）运行它们。使用 1 个并发活动 mutation（默认值）进行测试时，未观察到 CPU、内存或延迟显著增加。

默认时间表

默认情况下，清理作业在以下时间运行：

• 周六：UTC 晚上 8 点和 10 点。
• 周日：UTC 凌晨 12 点、2 点和 4 点。

禁用作业

要完全禁用清理作业：

queue:
  deployment:
    extraEnv:
      - name: "ENABLE_CLICKHOUSE_TTL_CLEANUP_CRON"
        value: "false"

配置时间表

通过修改 cron 表达式来自定义清理作业的运行时间：

queue:
  deployment:
    extraEnv:
      # UTC: Sunday 12am/2am/4am
      - name: "CLICKHOUSE_TTL_CLEANUP_CRON_WEEKEND_MORNING"
        value: "0 0,2,4 * * 0"
      # UTC: Saturday 8pm/10pm
      - name: "CLICKHOUSE_TTL_CLEANUP_CRON_WEEKEND_EVENING"
        value: "0 20,22 * * 6"

TIP

要使用单个 cron 时间表，请将 CLICKHOUSE_TTL_CLEANUP_CRON_WEEKEND_EVENING 和 CLICKHOUSE_TTL_CLEANUP_CRON_WEEKEND_MORNING 设置为相同的值。作业锁定可防止重叠执行。

配置每个 part 的最小过期行数

该作业会逐个处理表。在每个表中，它会扫描 part，并从任何至少包含最小过期行数的 part 中删除数据。此阈值可平衡效率与彻底性：

• 过低：作业会扫描整个 part 来清除极少的数据（效率低下）。
• 过高：作业会跳过包含大量过期数据的 part。

queue:
  deployment:
    extraEnv:
      - name: "CLICKHOUSE_TTL_CRON_MIN_EXPIRED_ROWS_PER_PART"
        value: "100000" # 100k expired rows

检查过期行

运行以下查询以查看每个表 part 的过期行数，然后调整你的最小值：

-- Query for Runs table. For other tables, replace 'ttl_seconds' with 'trace_ttl_seconds'
SELECT
    _part,
    count() AS expired_rows
FROM runs
WHERE trace_first_received_at IS NOT NULL
AND ttl_seconds IS NOT NULL
AND toDateTime(assumeNotNull(trace_first_received_at) + toIntervalSecond(assumeNotNull(ttl_seconds))) < now()
GROUP BY _part
ORDER BY expired_rows DESC

配置最大活动 mutation 数

对于 100 GB 的 part，删除操作可能需要约 50 分钟。增加并发 mutation 数可加快清理速度：

queue:
  deployment:
    extraEnv:
      - name: "CLICKHOUSE_TTL_CRON_MAX_ACTIVE_MUTATIONS"
        value: "1"

WARNING

更多并发 DELETE 操作可能会显著减慢插入和读取。只有在你能容忍更高的插入和读取延迟时才增加此值，并在增加后监控系统。

紧急情况：停止正在运行的 mutation

如果你看到延迟飙升并需要停止正在运行的 mutation：

1. 查找活动 mutation：

   SELECT * FROM system.mutations WHERE is_done = 0;

   找到 command 列包含 DELETE 语句的 mutation_id。

2. 终止 mutation：

   KILL MUTATION WHERE mutation_id = '<mutation_id>';

备份和数据保留

如果作业运行后磁盘空间没有减少，或持续增长，备份可能是原因。备份过程会创建文件系统硬链接，阻止 ClickHouse 释放数据。

检查 ClickHouse pod 中的以下目录：

• /var/lib/clickhouse/backup
• /var/lib/clickhouse/shadow

如果存在备份，请将其复制到外部存储（例如 S3），然后清空这些目录。磁盘空间应在几分钟内开始释放。

---