ES 的 Behavioral Analytics 9.0 起整块弃用，用到的要规划替代方案

ES 的 Behavioral Analytics（行为分析）从 9.0 起标记弃用，将在未来版本移除。API 目前还能用，但会返回警告头。这是个"整块功能下线"的弃用，比单个参数弃用影响大——如果你在用，需要规划替代方案。

说明

来源和边界先交代：本文的依据出自 v9.4.2 标签下的官方文件（9.0.0.yml、search_application.put_behavioral_analytics.json、search_application.post_behavioral_analytics_event.json），文中引用的原文均来自这些文件。我没有启动集群、也没有跑测试，示例取自官方示例；哪些是文档写明、哪些是我的推断，正文里逐处标注。

图 1：官方文件 9.0.0.yml（v9.4.2 标签）。来源：GitHub elastic/elasticsearch v9.4.2 9.0.0.yml

官方条目

9.0 的 changelog 标为 deprecation（9.0.0.yml 第 2163–2173 行 @ v9.4.2），area: Search，PR 123010。

details：

Behavioral Analytics has been deprecated as of 9.0.0 and will be removed in a future release. The APIs will still work for now, but will emit warning headers that the API has been deprecated.

impact 是同一句的前半段：

Behavioral Analytics has been deprecated as of 9.0.0 and will be removed in a future release.

关键信息三条：

• 从 9.0.0 起弃用；
• 将在未来版本移除（没说具体版本）；
• API 目前仍可用，但会返回警告头。

图 2：官方文件 search_application.put_behavioral_analytics.json（v9.4.2 标签）。来源：GitHub elastic/elasticsearch v9.4.2 search_application.put_behavioral_analytics.json

这个功能是什么

Behavioral Analytics 是一套收集和分析用户搜索行为的能力。

从 API 定义能看出它的形态——相关接口在 search_application 下（@ v9.4.2）：

• PUT _application/analytics/<name>——创建行为分析集合；
• GET _application/analytics/<name>——读取；
• DELETE _application/analytics/<name>——删除；
• POST _application/analytics/<name>/event/<event_type>——上报事件。

最后那个是核心：上报用户的搜索、点击等行为事件，然后 ES 提供基于这些事件的聚合分析（比如哪些查询没有点击、哪些结果被点了）。这属于搜索质量优化的范畴——用真实用户行为来发现搜索的问题。

它的定位是搜索质量优化——通过分析"用户搜了什么、点了什么"来改进搜索体验。

图 3：官方文件 search_application.post_behavioral_analytics_event.json（v9.4.2 标签）。来源：GitHub elastic/elasticsearch v9.4.2 search_application.post_behavioral_analytics_event.json

API 路径的变化

查 API 定义时注意到一个细节：这些接口的路径前缀是 _application，归类在 search_application 下。

这说明 Behavioral Analytics 在架构上是归属于 Search Application 体系的，不是一个完全独立的功能。

理解这一点对判断"该往哪迁移"有帮助——既然它属于 Search Application 体系，那替代方案大概率也在那个体系里，或者是那套体系本身的演进。

（说明：这个"归属于 Search Application"的判断，是从 API 路径和文件归类得出的，未找到官方的架构说明佐证。我的建议是：如果要据此做迁移决策，再核实一次。）

当前的实际影响很小

按官方说法，API 现在还能用，只是响应里多了警告头。

所以当前的影响是：

• 功能不受影响；
• 调用方的日志里会出现警告——如果你们有监控 HTTP 响应头的机制，会看到；
• 弃用日志里也会有记录。

没有报错、没有功能降级。 这是典型的 deprecation 而非 breaking，两者的处置节奏完全不同。

但"未来版本会移除"这句是重点——它是"会移除"，不是"可能移除"。所以这是个有明确期限的任务，只是期限没公布。

为什么这比参数弃用影响大

把它和其它弃用对比一下：

前两条是"改配置"，第三条是"改方案"。

差别在于：参数弃用有明确的替代做法，而整个功能下线意味着你要重新实现它提供的能力——行为数据的采集、存储、分析这一整套。

所以判断是：这条要尽早评估，但不用立刻动手。评估的核心是“到底在不在用它、用它做什么”——这两问题的答案决定了它是个紧急任务还是可以直接记入待办。

先确认用没用

一，看有没有创建过 analytics 集合。

curl -s 'localhost:9200/_application/analytics' | python3 -m json.tool

能列出已有的集合。空的话说明没在用（或者已经清理过了）。这是最快的一条路径——一个请求就能有结论。

二，看代码里有没有上报事件的调用。

grep -rn "_application/analytics\|behavioral_analytics" --include=*.py --include=*.go --include=*.js --include=*.json .

三，看 Kibana 里有没有相关的行为分析配置。 这个功能可能通过界面使用，代码里 grep 不到。

建议是三条都做，尤其是第三条——这类分析功能常在界面上配置，不看界面会漏。而且三条的结果要互相印证：如果 API 里有集合但代码里没找到调用，那多半是界面在用。

如果确实在用，怎么办

官方没给替代方案（details 里只说"会移除"）。所以下面是能想到的方向，不是官方建议：

一，自己在外部实现行为采集。 把搜索、点击事件写到自己的系统里（比如另一个 ES 索引、或者专门的 analytics 服务）。这是最直接的替代——反正行为数据本来也是你的业务数据。

二，看 Search Application 体系有没有新的能力。 既然 Behavioral Analytics 属于那个体系，后续可能有演进。关注后续版本的 changelog。

三，评估这些分析结论的实际价值。 这是个务实的角度：如果那些分析报表其实没人看，那功能下线正好省事，不用迁移。

倾向是先做第三条评估。 因为迁移这类功能的成本不低（要重新采集、重新算指标），而很多团队的实际使用情况是"当初配了，后来没人看"。先确认价值，再决定要不要迁移，比直接动手划算。

判断"有没有人在看"的办法也简单：看相关看板的访问记录，或者直接问一圈用搜索的同事。这类问题的答案通常比想象的清楚——要么立刻有人说“天天看”，要么没人说得上来。

警告头长什么样

details 里说"会返回警告头"（emit warning headers）。ES 的 REST 响应警告头是标准的 Warning 头，格式一般是：

Warning: 299 Elasticsearch-9.0.0-... "this API is deprecated"

（上面是示意格式，实际内容未抓取过，这里只是说明它出现在 HTTP 响应头里，不在响应体中。）

这一点对排查有实际意义：

• 如果你只看响应体，看不到弃用提示；
• 要看响应头，或者看服务端日志。

大多数 HTTP 客户端默认不打印响应头，所以很多人"用了很久也没看到警告"——是没往那个地方看，不是没有警告。

建议升级后显式检查一次响应头，尤其是依赖这类 API 的链路。做法很简单，curl -i 就能看到。

和 Kibana 的关系

既然这是个偏"分析"的功能，很可能通过 Kibana 界面使用。这意味着代码里 grep 不到，但功能确实在用。

前面把"看 Kibana"列为第三条排查路径，这里再强调一下为什么它重要：

• 代码 grep 只能找到程序化调用；
• 界面配置、看板、报表这类用法不在代码里；
• 而分析类功能恰恰多为界面使用。

所以如果前两条排查都没结果，不要急着下“没在用”的结论，再看一眼 Kibana。这个检查花不了几分钟，但能避免误判——而误判的代价是到了移除那天才发现有东西挂了。

Behavioral Analytics 的聚合提供了什么

写这篇时想确认 Behavioral Analytics 的聚合分析能力具体提供了什么（比如有哪些指标）。

未能在 v9.4.2 的文档里找到这一块的完整说明（可能是搜的关键词不对，也可能文档确实已经弱化——毕竟功能已弃用）。

所以本篇对"它提供什么分析"只做了基于 API 形态的描述（采集事件 + 基于事件的分析），没有列出具体指标。如果你要评估替代方案需要这个清单，得去查 8.x 的文档或者 PR 123010。

和别的"整块功能下线"放一起看

ES 9.x 有几条都属于"功能级弃用"，共同模式值得总结：

• 官方会明确说"将在未来版本移除"（不是"可能"）；
• 当前版本仍可用，只是有警告；
• 通常不给替代方案——因为它本身可能是被更新的方案取代了，或者用的人太少。

对这类条目，处理顺序是固定的：

1. 先确认用没用（这一步最重要，多数情况是没用）；
2. 用了的话，评估它的实际价值；
3. 有价值的再找替代或自行实现。

跳到第 3 步是常见的浪费——花很多精力迁移一个其实没人用的功能。最坏的情况是，迁移做了两周，做完发现新的报表同样没人看。

弃用的两种粒度

写到这里想到一个区分，对读 changelog 有用：ES 的弃用有两种粒度。

粒度的第一种：参数/设置级。 比如 force_source、enable_for_single_data_node、远程集群证书模式。特征是——功能还在，只是某个用法不能用了。处置是改配置。

粒度的第二种：功能/API 级。 比如本篇的 Behavioral Analytics，以及前面写过的 rollup（Rollup 弃用）。特征是——整块能力要没了。处置是重新规划。

分辨两者看 details 的措辞：

• 说"某个参数/设置被弃用" → 第一种；
• 说"某个功能/API 被弃用、将在未来版本移除" → 第二种。

这个分辨影响排期。第一种可以攒着一起改，第二种要单独评估——因为它可能牵出一整块改造。

排期上的做法是：功能级弃用单独建条目跟踪，不和参数清理混在一起。后者量大但不难，前者量少但可能很重，混在一起会让重的那条被淹没。

写在最后

这条 deprecation 当前不影响任何东西——API 照常工作。

这条值得写是因为它属于"整块功能下线"，和大多数"参数弃用"性质不同。这类条目的处置是重新规划一块能力，不是改配置，工作量大得多。

一，先确认用没用。 三条排查路径都要做（API、代码、Kibana 界面）。别漏了 Kibana——分析类功能常通过界面使用，只看代码会误判成"没在用"。

二，用了的话先评估价值，再决定要不要迁移。 直接动手迁移是常见浪费——先确认那些分析结论有没有人在看。

三，"将在未来版本移除"是有期限的任务。 记进待办，在下个主版本前处理掉，并且单独跟踪，不要和参数清理混在一起。

参考

• changelog 9.0.0：Deprecate Behavioral Analytics CRUD apis（第 2163–2173 行）@ v9.4.2
• search_application.put_behavioral_analytics.json：创建接口定义 @ v9.4.2
• search_application.post_behavioral_analytics_event.json：事件上报接口定义 @ v9.4.2
• PR 123010

本文对照 Elasticsearch v9.4.2 标签的 changelog 与 REST API 规范核对，引文逐字取自原文。"Behavioral Analytics 归属于 Search Application 体系"的判断来自 API 路径归类，未找到官方架构说明佐证；"它提供哪些分析指标"本文未找到完整文档，已在正文标注。文中替代方向是建议，非官方方案。撰写时未启动集群、未运行测试。