> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-zh.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 启用 TTL 与数据保留

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

<Note>
  **自托管 [企业版](/langsmith/pricing-plans) 客户：** 您现在可以通过 UI 在工作区级别配置扩展的数据保留策略，从而获得更精细的控制，而无需更改环境变量。更多信息，请参阅[自定义扩展保留策略](/langsmith/data-purging-compliance#customize-extended-retention-policy)。本文档中记录的系统级 TTL 配置仍然受支持。
</Note>

## 要求

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

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

<CodeGroup>
  ```yaml Helm theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  config:
    ttl:
      enabled: true
      ttl_period_seconds:
        # -- 400 天长期和 14 天短期
        longlived: "34560000"
        shortlived: "1209600"
  ```

  ```bash Docker theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # 在您的 .env 文件中FF_TRACE_TIERS_ENABLED=trueTRACE_TIER_TTL_DURATION_SEC_MAP='{"longlived": 34560000, "shortlived": 1209600}'
  ```
</CodeGroup>

## ClickHouse TTL 清理任务

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

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

### 默认计划

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

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

### 禁用任务

要完全禁用清理任务：

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
queue:
  deployment:
    extraEnv:
      - name: "ENABLE_CLICKHOUSE_TTL_CLEANUP_CRON"
        value: "false"
```

### 配置计划

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

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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"
```

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

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

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

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

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
queue:
  deployment:
    extraEnv:
      - name: "CLICKHOUSE_TTL_CRON_MIN_EXPIRED_ROWS_PER_PART"
        value: "100000" # 10 万过期行
```

#### 检查过期行数

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

```sql theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
-- 针对 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 分钟）。您可以增加并发变更数以加快处理速度：

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
queue:
  deployment:
    extraEnv:
      - name: "CLICKHOUSE_TTL_CRON_MAX_ACTIVE_MUTATIONS"
        value: "1"
```

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

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

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

1. **查找活动中的变更**：

   ```sql theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
   SELECT * FROM system.mutations WHERE is_done = 0;
   ```

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

2. **终止变更**：
   ```sql theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
   KILL MUTATION WHERE mutation_id = '<mutation_id>';
   ```

### 备份与数据保留

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

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

* `/var/lib/clickhouse/backup`
* `/var/lib/clickhouse/shadow`

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

***

<div className="source-links">
  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/i18n\zh-CN\langsmith\self-host-ttl.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>

  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>
</div>