> ES 9.1 引入 Failure Store，把 ingest 失败或 mapping 冲突的文档存下来，9.2 起对日志流默认开启。本文讲怎么开、怎么查，以及升级后写坏文档的响应码从 400 变成 201 这个大坑。

## **说明**

本文描述问题及解决方法同样适用于 [腾讯云 Elasticsearch Service（ES）](https://cloud.tencent.com/document/product/845)。

## 先说痛点

做过日志接入的人大概都遇到过这种情况：一批文档写进去，bulk 响应里带着一堆 ingest 报错或字段类型冲突，然后这些文档就没了——很多客户端根本处理不了这些错误，拿不到能重试的"坏文档"，只能丢掉。

偏偏对可观测性、安全这类场景来说，写不进去的文档往往恰恰是最该看的信号。9.1 引入的 **failure store** 就是接这个的。

## 官方怎么描述这个痛点

9.1 highlights 里这段话写得很清楚（[1548–1625 行 @ v9.3.0](https://github.com/elastic/elasticsearch/blob/v9.3.0/docs/release-notes/index.md#L1548-L1625)）：

> Documents that encountered ingest pipeline failures or mapping conflicts would previously be returned to the client as errors in the bulk and index operations. Many client applications are not equipped to respond to these failures. This leads to the failed documents often being dropped by the client which cannot hold the broken documents indefinitely. In many end user workloads, these failed documents represent events that could be critical signals for observability or security use cases.

简单说：客户端扛不住这些错误 → 坏文档被丢 → 但那些坏文档可能正是关键信号。

failure store 的做法是：data stream 额外维护一套"失败存储"，接收因为**可预防的配置错误**而写不进去的文档，连同**失败时间、错误信息、原始文档**一起存下来。它有自己的 mapping 和访问方式，本质上是一组独立的 backing index。

## 怎么开

新建 data stream 时，在模板里配 `data_stream_options`：

```console
PUT _index_template/my-template
{
  "index_patterns": ["logs-test-*"],
  "data_stream": {},
  "template": {
    "data_stream_options": {
      "failure_store": {
        "enabled": true
      }
    }
  }
}
```

已有的 data stream 用 `_options` 端点开：

```console
PUT _data_stream/logs-test-apache/_options
{
  "failure_store": {
    "enabled": "true"
  }
}
```

（两个示例都来自官方 9.1 highlights。）

## 怎么查

用一个新语法，选择器 **`::failures`**：

```console
POST logs-test-apache::failures/_search
```

这个选择器可以跟普通索引模式混着用，官方给了几种写法：

```console
POST logs-*::failures/_search
POST logs-*,logs-*::failures/_search
POST *::failures/_search
```

ES|QL 里也能用：

```esql
FROM my_data_stream*::failures
```

要注意：**失败文档默认不会出现在正常查询里**，因为它们存在不同的索引上，得显式用 `::failures` 去查。

## 9.2 起对日志流默认开启，这里有个大坑

9.2 把 failure store 变成了默认：**匹配 `logs-*-*` 的新 logs data stream 默认开启**（[9.2.0 highlights @ v9.3.0](https://github.com/elastic/elasticsearch/blob/v9.3.0/docs/release-notes/index.md#L472-L476)）。

真正要命的是下面这句：

> Note: With the failure store enabled, the http response code clients receive when indexing invalid documents will change from `400 Bad Request` to `201 Created`, with an additional response attribute `"failure_store" : "used"`.

**写入非法文档时，HTTP 响应码从 400 变成 201，多一个 `"failure_store": "used"` 属性。**

如果你的客户端、采集端或者监控是靠 HTTP 状态码判断"写成功/写失败"的，升级之后它会认为这些坏文档**写成功了**。错误率会突然变得很好看，实际上数据都进了 failure store。

这一点必须提前改：判断逻辑要去看响应体里的 `"failure_store": "used"`，不能只看状态码。

顺带一提，9.2 里 OTel 和 APM 的 data stream 也默认开启了 failure store（PR [#131395](https://github.com/elastic/elasticsearch/pull/131395)、[#131296](https://github.com/elastic/elasticsearch/pull/131296)）。

## 9.4：跨集群搜索也支持了

9.4 补了一条：**Failure Stores in Cross Cluster Search**（PR [#139316](https://github.com/elastic/elasticsearch/pull/139316)，[9.4.0 features @ v9.5.0](https://github.com/elastic/elasticsearch/blob/v9.5.0/docs/release-notes/index.md#L654)）。

也就是说，跨集群查询现在能一并查到 failure store 里的数据了。

## 不是什么错误都收

有个边界要说清楚。在 9.3.5 和 9.4.1 的修复里有一条："Update failure store redirect logic to exclude backpressure exceptions"（PR [#148154](https://github.com/elastic/elasticsearch/pull/148154)，见 [9.3.5](https://github.com/elastic/elasticsearch/blob/v9.5.0/docs/release-notes/index.md#L323) 和 [9.4.1](https://github.com/elastic/elasticsearch/blob/v9.5.0/docs/release-notes/index.md#L415) 的发布说明）。

**反压（backpressure）导致的异常不再被重定向到 failure store。** 这是对的——集群忙不过来不是"文档有问题"，把这种失败存进 failure store 只会越堆越多。

所以 failure store 收的是**可预防的配置类错误**：ingest pipeline 异常、mapping 冲突这类。

## 小结

| 项 | 结论 |
|---|---|
| 版本 | 9.1 引入；9.2 对 `logs-*-*` 默认开启 |
| 存什么 | ingest 失败或 mapping 冲突的文档 + 失败时间 + 错误信息 + 原始文档 |
| 怎么查 | `::failures` 选择器，支持与普通索引模式混用，ES\|QL 也支持 |
| **响应码变化** | 9.2 起写坏文档返回 **201 而不是 400**，带 `"failure_store": "used"` |
| 跨集群 | 9.4 起支持 CCS 查询 failure store |
| 不收什么 | 反压类异常（9.3.5 / 9.4.1 起） |

## 写在最后

我的建议：如果你是 9.2 之后升上来的，可以去查一遍现有的 failure store 有没有东西——`POST logs-*::failures/_search`。有些系统之前就有偶发的 ingest 错误或 mapping 冲突，这时候能看到。第二件事是检查写入端的成功判定逻辑。

## 参考

- [9.1.0 highlights @ v9.3.0](https://github.com/elastic/elasticsearch/blob/v9.3.0/docs/release-notes/index.md#L1548-L1625)
- [9.2.0 highlights @ v9.3.0](https://github.com/elastic/elasticsearch/blob/v9.3.0/docs/release-notes/index.md#L472-L476)
- [9.4.0 features（CCS 支持）@ v9.5.0](https://github.com/elastic/elasticsearch/blob/v9.5.0/docs/release-notes/index.md#L654)
- PR [#148154](https://github.com/elastic/elasticsearch/pull/148154)（反压异常不重定向）

> 本文对照 Elasticsearch `v9.3.0`、`v9.5.0` 标签的官方发布说明核对，示例取自官方 highlights 原文。撰写时未启动集群、未运行测试。


ES 9.1 引入 Failure Store，把 ingest 失败或 mapping 冲突的文档存下来，9.2 起对日志流默认开启。本文讲怎么开、怎么查，以及升级后写坏文档的响应码从 400 变成 201 这个大坑。

写不进去的文档，别再悄悄丢了：Failure Store

ES 9.1 引入 Failure Store，把 ingest 失败或 mapping 冲突的文档存下来，9.2 起对日志流默认开启。

官方产研

云计算

后端

大数据

ES 9.1引入FailureStore存储ingest失败或mapping冲突文档，9.2起对日志流默认开启。本文详解开启方法、::failures查询语法，重点警示升级后坏文档响应码从400变201，客户端须检查"failure_store":"used"属性避免误判。适用腾讯云ES，跨集群查询9.4起支持。

代码解释

2026上云采购 | AI焕新·智启新局

bigdata-class

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

写不进去的文档，别再悄悄丢了：Failure Store-腾讯云开发者社区-腾讯云

写不进去的文档，别再悄悄丢了：Failure Store

写不进去的文档，别再悄悄丢了：Failure Store

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐