启用 TTL 和数据保留 - 以编程方式使用文档

LangSmith 自托管版本支持启用跟踪的自动 TTL 和数据保留功能。如果您需要遵守数据隐私法规，或者希望更高效地利用空间并自动清理跟踪数据，这将非常有用。跟踪数据也会根据某些操作或运行规则应用自动延长其数据保留期限。

要求

您可以通过 helm 或环境变量设置来配置保留。有几个可配置的选项：

- *Enabled:* 数据保留是启用还是禁用。如果启用，通过 UI 您可以为跟踪应用默认组织和项目 TTL 层级（请参阅数据保留指南了解详情）。
- *保留期限：* 您可以为短期和长期跟踪配置系统级保留期限。配置后，您可以在每个项目中管理保留级别，也可以为新项目设置组织级默认设置。

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

# In your .env fileFF_TRACE_TIERS_ENABLED=trueTRACE_TIER_TTL_DURATION_SEC_MAP='{"longlived": 34560000, "shortlived": 1209600}'

ClickHouse TTL 清理任务

从版本 **0.11**开始，系统会在周末运行一个 cron 任务来协助删除 ClickHouse 内置 TTL 机制可能未清理掉的过期数据。

默认调度

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

周六：UTC 时间晚上 8 点和 10 点
周日：UTC 时间凌晨 0 点、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"

配置每个分区的最小过期行数

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

过低：任务扫描整个分区以清除少量数据（效率低下）
过高：任务会遗漏包含大量过期数据的分区

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

检查过期行数

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

-- 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

配置最大活动变更数

删除操作可能非常耗时（100GB 分区约需 50 分钟）。您可以增加并发变更数来加快此过程：

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

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

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

**查找活动变更**:

   SELECT * FROM system.mutations WHERE is_done = 0;

查找 mutation_id 其中 command 列包含 DELETE statement.

2. **终止变更**:

   KILL MUTATION WHERE mutation_id = '<mutation_id>';

备份和数据保留

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

要验证，请在 ClickHouse Pod 内检查以下目录：

- /var/lib/clickhouse/backup
- /var/lib/clickhouse/shadow