Apache SkyWalking TTL 数据保留策略配置指南：recordDataTTL 与 metricsDataTTL 详解

• 可观测性
• 后端
• 微服务
• 云原生

TTL（Time To Live）是 SkyWalking OAP Server 控制可观测数据存储生命周期、自动清理过期数据、防止存储无限膨胀的核心机制。本指南以 ttl.md 为骨架，结合 OAP 源码（CoreModuleConfig、ConfigService、DataTTLKeeperTimer、IHistoryDeleteDAO）与真实配置示例，完整讲解两类数据（Records 与 Metrics）的 TTL 配置参数、默认值、环境变量覆盖方式以及底层删除驱动原理，帮助你在生产环境按数据特征精确设定保留天数。

一、背景：为什么需要区分两类数据设置 TTL

在 SkyWalking 中，可观测数据在存储层面被划分为两种类型，二者的数据量级、价值密度和保留需求差异巨大：

1. 记录型数据（Records）：包括调用链 Trace（segment）、日志 Log、TopN 采样语句（slow SQL/慢语句）和告警 Alarm。这类数据是"逐条原始记录"，数据量最大、增长最快，通常只需要短期保留用于排障与审计，过期后价值迅速衰减。recordDataTTL作用于这类数据。

2. 指标型数据（Metrics）：包括服务（Service）、实例（Instance）、端点（Endpoint）以及拓扑图相关的全部指标。元数据（服务、实例、端点的列表）也归属于 Metrics。这类数据是聚合后的统计数据，量级相对可控，且是趋势分析、告警规则和历史对比的基础，通常需要更长的保留周期。metricsDataTTL作用于这类数据。

之所以将 TTL 拆分成两个独立参数，正是为了适配这两类数据截然不同的生命周期诉求：让高频、高量的 Trace/Log 快速滚动清理，同时让指标和元数据留存更久，兼顾存储成本与查询能力。

二、核心配置参数与默认值

TTL 的配置位于 OAP Server 的core模块配置段中，默认配置文件为 oap-server/server-starter/src/main/resources/application.yml（打包后即application.yml）。完整配置如下：

core: default: # 记录型数据（Trace、Log、TopN、Alarm）的超时时间，超时后自动删除。单位为天 recordDataTTL: ${SW_CORE_RECORD_DATA_TTL:3} # Unit is day # 指标型数据（Service/Instance/Endpoint 指标、拓扑与元数据）的超时时间，超时后自动删除。单位为天 metricsDataTTL: ${SW_CORE_METRICS_DATA_TTL:7} # Unit is day

两个参数均为整数天数：

在源码中，这两个默认值定义在 CoreModuleConfig.java：

private int metricsDataTTL = 7; private int recordDataTTL = 3;

配置加载后，会被封装进 ConfigService.java，作为CoreModule对外提供的配置服务供其他模块读取：

private final int metricsDataTTL; private final int recordDataTTL; ... this.metricsDataTTL = moduleConfig.getMetricsDataTTL(); this.recordDataTTL = moduleConfig.getRecordDataTTL();

三、修改方式：配置文件与环境变量覆盖

TTL 有两条生效路径，优先级为环境变量 > 配置文件默认值：

• 直接编辑配置文件：修改oap-server/server-starter/src/main/resources/application.yml中core.default段下的recordDataTTL/metricsDataTTL值，或在部署目录下的config/application.yml中调整后重启 OAP Server。
• 通过环境变量覆盖（推荐用于容器化/K8s 部署，无需改动文件）：利用${SW_CORE_RECORD_DATA_TTL:3}语法，任何环境变量会覆盖 yaml 中的默认值。例如在docker-compose.yml或 K8s Deployment 中设置：

environment: - SW_CORE_RECORD_DATA_TTL=3 - SW_CORE_METRICS_DATA_TTL=14

上述示例将指标保留期延长至 14 天，记录数据保持默认 3 天。注意：TTL 值必须为正整数，单位为天，0或负数没有意义。

相关辅助配置：执行周期与开关

与 TTL 删除动作强相关的还有两个配置项（同位于core.default段，见 application.yml）：

# 关闭后自动指标数据删除将失效 enableDataKeeperExecutor: ${SW_CORE_ENABLE_DATA_KEEPER_EXECUTOR:true} # Data Keeper 执行器多久运行一次，单位为分钟 dataKeeperExecutePeriod: ${SW_CORE_DATA_KEEPER_EXECUTE_PERIOD:5}

• enableDataKeeperExecutor（默认true）：数据清理任务的全局开关，置为false则完全停止 TTL 自动删除；
• dataKeeperExecutePeriod（默认 5 分钟）：周期性扫描并执行过期数据删除的间隔。

四、底层实现：TTL 如何被驱动执行

理解 TTL 的执行机制有助于你判断"改完配置多久生效""谁来执行删除"。

4.1 核心驱动器：DataTTLKeeperTimer

删除动作由一个内部定时器 DataTTLKeeperTimer.java 驱动。它采用单线程调度，按dataKeeperExecutePeriod（默认 5 分钟）周期性执行delete()：

Executors.newSingleThreadScheduledExecutor() .scheduleAtFixedRate( new RunnableWithExceptionProtection(this::delete, t -> log.error("Remove data in background failure.", t)), moduleConfig.getDataKeeperExecutePeriod(), moduleConfig.getDataKeeperExecutePeriod(), TimeUnit.MINUTES);

每次执行时，delete()会遍历IModelManager中的全部存储模型（Model），对每个时序模型（model.isTimeSeries()为 true）调用存储层 DAO 执行历史删除，并按模型类型选择 TTL 值：

moduleManager.find(StorageModule.NAME) .provider() .getService(IHistoryDeleteDAO.class) .deleteHistory(model, Metrics.TIME_BUCKET, model.isRecord() ? moduleConfig.getRecordDataTTL() : moduleConfig.getMetricsDataTTL());

即：每个存储模型都会根据自身isRecord()属性自动归入recordDataTTL或metricsDataTTL的管理范围，这一判定逻辑在 DataTTLKeeperTimer.java 中。

4.2 集群环境下只由一个节点执行

DataTTLKeeperTimer在每个 OAP 节点上都会启动，但为避免多节点重复删除同一批数据，代码通过ClusterNodesQuery获取集群节点列表并排序，仅当本节点是列表中的第一个节点时才实际执行删除，其余节点直接跳过（源码注释见 DataTTLKeeperTimer.java）：

List<RemoteInstance> remoteInstances = clusterNodesQuery.queryRemoteNodes(); Collections.sort(remoteInstances); if (CollectionUtils.isNotEmpty(remoteInstances) && !remoteInstances.get(0).getAddress().isSelf()) { log.info("The selected first getAddress is {}. The remove stage is skipped.", ...); return; }

4.3 存储层实现：IHistoryDeleteDAO

删除动作最终委托给存储层的IHistoryDeleteDAO接口（见 IHistoryDeleteDAO.java）：

/** * Remove all expired data based on TTL configurations. * @param ttl the number of days should be kept */ void deleteHistory(Model model, String timeBucketColumnName, int ttl) throws IOException;

不同存储插件提供各自的实现，例如：

• Elasticsearch 插件：HistoryDeleteEsDAO.java；
• JDBC/H2/MySQL/PostgreSQL 插件：JDBCHistoryDeleteDAO.java，对应的集成测试见 JDBCHistoryDeleteDAOIT.java；
• BanyanDB 插件：BanyanDBHistoryDeleteDAO.java。

另外在指标写入路径上，MetricsPersistentWorker.java 还会借助IMetricsDAO.isExpiredCache()判断内存缓存中的指标是否已超过 TTL（见 IMetricsDAO.java），实现缓存层的过期淘汰：

default boolean isExpiredCache(Model model, Metrics cachedValue, long currentTimeMillis, int ttl) { long metricTimestamp = cachedValue.getTimeBucket(); // If the cached metric is older than the TTL indicated. return currentTimeMillis - metricTimestamp > TimeUnit.DAYS.toMillis(ttl); }

由此可见，TTL 不仅在"后台删除"环节生效，也参与写入期的缓存淘汰，两层配合共同约束数据生命周期。

五、注意事项与最佳实践

• 单位统一为天：两个 TTL 参数均以"天"为最小单位，最小粒度为 1 天，无法按小时配置。
• 区分两类数据再设定值：Trace/Log 建议 3 天左右（默认值即可），指标与元数据可放宽到 7～30 天，具体结合存储容量与查询窗口决定；元数据归属 Metrics 意味着即使只保留 Trace 3 天，服务/实例列表也会按metricsDataTTL保留更久，查询 UI 时历史服务仍可见。
• BanyanDB 分段间隔需小于 TTL：若使用 BanyanDB 存储，其segmentIntervalDays/superDatasetSegmentIntervalDays的取值应小于等于 TTL 相关设置（见 application.yml），否则会出现分段覆盖不到过期边界的问题。
• 集群部署无需重复配置：TTL 删除由集群中排序第一的节点统一执行，所有节点配置一致即可，不会发生重复删除。
• 改动即时性：TTL 值在 OAP 启动时加载，修改后需重启 OAP Server 生效；删除任务本身每dataKeeperExecutePeriod（默认 5 分钟）扫描一轮，因此数据过期后最迟会在一个执行周期内被清理。
• 关闭自动清理：如需自行管理数据归档，可将enableDataKeeperExecutor设为false（SW_CORE_ENABLE_DATA_KEEPER_EXECUTOR=false），此后过期数据将不再被自动删除。

六、小结

SkyWalking 的 TTL 机制通过recordDataTTL与metricsDataTTL两个参数，将记录型数据（Trace、Log、TopN、Alarm）与指标型数据（指标、拓扑、元数据）的保留策略解耦，配合DataTTLKeeperTimer定时器、集群单节点删除机制以及各存储插件实现的IHistoryDeleteDAO，实现了过期数据自动、精准、无重复地清理。生产实践中，按数据价值与存储成本分别设定两档 TTL，即可在查询能力与资源占用之间取得良好平衡。

• 可观测性
• 后端
• 微服务
• 云原生