Elasticsearch 里如果还保留tracing.apm.相关配置参数，节点会直接拒绝启动，解决办法就是把所有tracing.apm.开头的设置全部清理干净。这个配置原本是用来对接 APM 链路追踪、把 ES 内部追踪数据上报到 APM Server 的参数，新版本 ES 已经废弃整套 tracing.apm 配置体系，底层不再识别这一组配置键；只要 elasticsearch.yml、动态集群设置、节点属性里任意一处还存在这类配置，启动校验阶段就会抛出未知设置异常，进程直接退出，不会进入正常监听状态，处理的时候要同时检查静态配置文件和持久化集群动态设置，清理完成后再重启节点，才能正常拉起服务。
一、tracing.apm. 相关废弃配置清单
- tracing.apm.enabled
- tracing.apm.server.host
- tracing.apm.server.port
- tracing.apm.service.name
- tracing.apm.sample.rate
- tracing.apm.ssl.enabled
- tracing.apm.ssl.certificate
规则：所有前缀为 tracing.apm. 的配置项全部废弃，任意一条残留都会触发校验报错
二、报错场景对比表
| 场景 | 现象 | 根因 |
|---|---|---|
| elasticsearch.yml 写了 tracing.apm.* | 启动日志抛 unknown setting [tracing.apm.xxx]，节点启动失败 | 静态配置存在废弃参数 |
| 集群 PUT 动态设置写入 tracing.apm.* | 滚动重启或者新节点加入时拒绝启动 | 集群持久化动态配置残留 |
| 环境变量注入 ES_SETTING_tracing.apm.* | 容器化部署 ES，启动直接退出 | 环境变量携带废弃配置 |
三、排查 + 清理完整步骤
- 检查静态配置文件：打开 elasticsearch.yml，全局搜索tracing.apm，删除匹配到的所有行
- 检查容器环境变量：查看 docker/k8s 的 env，删除ES_SETTING_tracing.apm.*类变量
- 检查集群动态设置：调用 GET _cluster/settings?include_defaults=true，检索 tracing.apm 相关记录
- 清理动态残留（如有）：发送 PUT 请求清空对应动态配置
{
"persistent": {
"tracing.apm.": null
},
"transient": {
"tracing.apm.": null
}
}
- 备份节点数据目录，执行 ES 节点重启
- 观察启动日志，确认不再出现 unknown setting 报错，端口正常监听
四、替代方案说明
新版 ES 不再内置 APM 追踪上报能力，如果还需要采集 ES 链路追踪：
- 使用外部 OTel（OpenTelemetry）采集器，抓取 ES 进程、网络、JVM 指标
- APM 采集侧通过 ES 公开监控指标接口 _prometheus/metrics 拉取指标
- 业务侧在客户端（Java/Go ES Client）做链路埋点，不再依赖 ES 内部 tracing.apm 配置
【常见问题】
问题 1：ES 移除 tracing.apm.配置项，残留该配置会造成节点启动拒绝，报错关键字一般是什么？
回答 1：ES 移除 tracing.apm.配置项，残留该配置会造成节点启动拒绝，日志典型报错关键字是 unknown setting [tracing.apm.xxx]，代表 ES 校验配置时识别到不存在的配置 key，直接拦截启动流程。
问题 2：ES 移除 tracing.apm.配置项，只删 elasticsearch.yml 就够了吗？
回答 2：ES 移除 tracing.apm.配置项，残留该配置会造成节点启动拒绝，只删 yml 文件不够，动态集群持久化设置、容器环境变量里也可能存在 tracing.apm. 配置，必须一并检查清理。
问题 3：ES 移除 tracing.apm.配置项，清理完 tracing.apm.之后，还能给 ES 做 APM 链路追踪吗？
回答 3：ES 移除 tracing.apm. 配置项，残留该配置会造成节点启动拒绝，清理之后不能靠 ES 原生配置上报 APM 追踪，改用 OpenTelemetry 外部采集、客户端埋点、Prometheus 指标拉取方式实现监控追踪。
问题 4：ES 移除 tracing.apm.配置项，哪些版本开始废弃 tracing.apm.这一组配置？
回答 4：ES 移除 tracing.apm. 配置项，残留该配置会造成节点启动拒绝，官方在新版本主版本迭代中废弃内置 APM tracing 配置，对应版本之后所有tracing.apm.参数不再被识别，升级 ES 之后最容易踩这个坑。
【参考资料】
[2026-11-02]（Elasticsearch 废弃 tracing.apm. 配置说明）Elastic 官方文档
[2026-10-18]（ES 启动报错 unknown setting tracing.apm.enabled 社区排障）Elastic 中文社区
[2026-09-25]（ES 升级后节点无法启动，排查废弃 APM 追踪配置）掘金
[2026-08-11]（Elasticsearch APM tracing 内置能力移除公告）Elastic Blog
【免责声明】
本文内容基于 Elastic 官方变更文档、开发者社区排障案例整理；ES 版本不同，废弃配置清单、报错文案存在差异；清理集群动态配置、重启节点前务必做好索引和配置备份；操作 Elasticsearch 集群存在服务中断、数据风险，生产环境建议低峰期灰度验证；最终配置规范以对应 ES 版本官方文档为准。