启用 TTL 与数据保留

LangSmith 自托管版本支持启用自动 TTL 和数据保留策略来管理追踪记录。如果您需要遵守数据隐私法规，或者希望更高效地利用存储空间并自动清理追踪记录，此功能将非常有用。此外，追踪记录的数据保留期限会根据特定操作或运行规则的应用而自动延长。

自托管 企业版 客户： 您现在可以通过 UI 在工作区级别配置扩展的数据保留策略，从而获得更精细的控制，而无需更改环境变量。更多信息，请参阅自定义扩展保留策略。本文档中记录的系统级 TTL 配置仍然受支持。

要求

您可以通过 Helm 或环境变量设置来配置保留策略。有以下可配置选项：

• 启用状态： 数据保留功能是启用还是禁用。如果启用，您可以通过 UI 设置默认组织和项目的 TTL 层级以应用于追踪记录（详情请参阅数据保留指南）。
• 保留期限： 您可以配置系统级的短期和长期追踪记录的保留期限。配置完成后，您可以在每个项目中管理保留级别，并为新项目设置组织范围的默认值。

Helm

config:
  ttl:
    enabled: true
    ttl_period_seconds:
      # -- 400 天长期和 14 天短期
      longlived: "34560000"
      shortlived: "1209600"

ClickHouse TTL 清理任务

自 0.11 版本起，系统会在周末运行一个定时任务，以协助删除可能未被 ClickHouse 内置 TTL 机制清理的过期数据。

此任务使用可能长时间运行的变更操作（ALTER TABLE DELETE），这是昂贵的操作，可能会影响 ClickHouse 的性能。我们建议仅在非高峰时段（夜间和周末）运行这些操作。在测试中，使用 1 个并发活动变更（默认值）时，我们没有观察到显著的 CPU、内存或延迟增加。

默认计划

默认情况下，清理任务在以下时间运行：

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

禁用任务

要完全禁用清理任务：

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

配置计划

您可以通过修改 cron 表达式来自定义清理任务的运行时间：

queue:
  deployment:
    extraEnv:
      # UTC: 周日 凌晨12点/2点/4点
      - name: "CLICKHOUSE_TTL_CLEANUP_CRON_WEEKEND_MORNING"
        value: "0 0,2,4 * * 0"
      # UTC: 周六 晚上8点/10点
      - name: "CLICKHOUSE_TTL_CLEANUP_CRON_WEEKEND_EVENING"
        value: "0 20,22 * * 6"

要在单个 cron 计划上运行任务，请将 CLICKHOUSE_TTL_CLEANUP_CRON_WEEKEND_EVENING 和 CLICKHOUSE_TTL_CLEANUP_CRON_WEEKEND_MORNING 设置为相同的值。任务锁定机制会防止执行重叠。

配置每个数据块的最小过期行数

该任务逐个表进行，扫描数据块并删除那些包含最少过期行数的数据块中的数据。此阈值在效率和彻底性之间取得平衡：

• 过低： 任务扫描整个数据块仅清除少量数据（效率低下）
• 过高： 任务会错过包含大量过期数据的数据块

queue:
  deployment:
    extraEnv:
      - name: "CLICKHOUSE_TTL_CRON_MIN_EXPIRED_ROWS_PER_PART"
        value: "100000" # 10 万过期行

检查过期行数

使用此查询分析表中的过期行数，并相应调整您的最小值：

-- 针对 Runs 表的查询。对于其他表，将 'ttl_seconds' 替换为 '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

配置最大活动变更数

删除操作可能非常耗时（对于一个 100GB 的数据块大约需要 50 分钟）。您可以增加并发变更数以加快处理速度：

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

增加并发的 DELETE 操作可能会严重影响系统性能。请仔细监控您的系统，并且仅在能够容忍可能出现的插入和读取延迟变慢的情况下才增加此值。

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

如果您遇到延迟激增并需要终止正在运行的变更：

1. 查找活动中的变更：

   SELECT * FROM system.mutations WHERE is_done = 0;
   

   在 command 列包含 DELETE 语句的行中查找 mutation_id。

2. 终止变更：

   KILL MUTATION WHERE mutation_id = '<mutation_id>';
   

备份与数据保留

如果运行此任务后磁盘空间没有减少，或者持续增加，可能是备份通过创建文件系统硬链接导致了此问题。这些链接会阻止 ClickHouse 清理数据。

要验证这一点，请检查 ClickHouse Pod 内的以下目录：

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

如果存在备份，请将它们复制到外部文件系统或对象存储（例如 S3），然后清空这些目录。几分钟内，您将注意到磁盘空间被释放。

---

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.