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

# 启用 TTL 和数据保留

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

<Note>
  **自托管 [Enterprise](/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=true
  TRACE_TIER_TTL_DURATION_SEC_MAP='{"longlived": 34560000, "shortlived": 1209600}'
  ```
</CodeGroup>

## ClickHouse TTL 清理任务

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

<Warning>
  此任务使用可能长时间运行的 **mutations**（`ALTER TABLE DELETE`），这是开销较大的操作，可能会影响 ClickHouse 的性能。我们建议仅在非高峰时段（夜间和周末）运行这些操作。在使用 **1 个并发活动** mutation（默认值）进行测试时，我们未观察到 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>

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

该任务逐表进行，扫描 part 并从包含最少过期行数的 part 中删除数据。此阈值平衡了效率和彻底性：

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

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

### 配置最大活动 mutations 数

删除操作可能非常耗时（对于 100GB 的 part 约需 50 分钟）。您可以增加并发 mutations 数以加快此过程：

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

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

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

如果您遇到延迟尖峰并需要终止正在运行的 mutation：

1. **查找活动 mutations**：

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

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

2. **终止该 mutation**：
   ```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`

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

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档](/use-these-docs) 通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/self-host-ttl.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>