Vector elasticsearch Sink 配置字段弃用迁移指南从 mode normal 到 bulk 及源码实现对照【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vectorVector 的elasticsearchsink 在 0.18.0 版本中对顶层配置字段做了一次结构性调整一批历史字段被标记为弃用并计划于 0.19.0 移除取而代之的是分组更清晰的bulk与request子配置块。本篇基于该弃用公告的字段映射表结合当前仓库 elasticsearch sink 源码 的实际实现完整给出每个旧字段的迁移方式、新字段默认值与取值范围以及后续版本中endpoint等字段被进一步弃用的演进脉络帮助你在升级 Vector 时平滑改写 Elasticsearch 输出配置。弃用背景0.18.0 的字段重组0.18.0 的官方弃用公告2021-10-19-elasticsearch-config-deprecations.md声明部分elasticsearchsink 配置字段被弃用并计划在 0.19.0 中移除。公告给出的完整映射表如下本文完整继承该表被弃用字段新字段mode normalmode bulkhostendpointbulk_actionbulk.actionindexbulk.indexheadersrequest.headers这次调整的核心思路是把散落在顶层的写入参数收敛到bulk子块描述如何调用 Bulk API把 HTTP 层参数收敛到request子块描述如何发出 HTTP 请求与 sink 的mode概念对齐。下文逐字段说明迁移方式并用当前仓库源码佐证每个新字段的解析位置、默认值与行为。逐字段迁移说明1.mode normal→mode bulk写入模式字段mode的取值在 0.18.0 起由normal更名为bulk。当前源码中该枚举定义在 ElasticsearchModepub enum ElasticsearchMode { /// Ingests documents in bulk, using the bulk API index action. #[serde(alias normal)] #[default] Bulk, /// Ingests documents in bulk, using the bulk API create action. DataStream, }#[serde(alias normal)]表明源码在反序列化时保留了normal作为bulk的别名即旧配置中的mode: normal仍可被解析但新配置应统一写mode: bulk或省略因为bulk就是默认模式。另一个取值data_stream面向 Elasticsearch Data Streams固定使用create动作从源码结构看Data Stream 模式还会自动把事件中的timestamp字段重命名为 Elastic Common Schema 要求的timestamp见 config.rs 中 DATA_STREAM_TIMESTAMP_KEY 及DataStreamMode::remap_timestamp。2.host→endpoint并进一步演进为endpoints连接地址字段从host更名为endpoint。在 0.18.0/0.19.0 之后当前仓库又完成了一轮演进endpoint单地址本身也被标记为弃用推荐改用可写多个地址的endpoints列表。这一点在 ElasticsearchConfig 上有明确的deprecated元数据/// The Elasticsearch endpoint to send logs to. #[serde(default)] #[configurable( deprecated This option has been deprecated, the endpoints option should be used instead. )] #[configurable(required_one_of endpoint)] pub endpoint: OptionHttpEndpoint, /// A list of Elasticsearch endpoints to send logs to. #[serde(default)] #[configurable(required_one_of endpoint)] pub endpoints: VecHttpEndpoint,两个约束值得注意endpoint与endpoints是必选其一required_one_of关系两者都缺失会在验证阶段报Endpoints option must be specified两者同时出现则报互斥错误。对应的验证逻辑见 validate()并有单元测试 validate_rejects_endpoint_and_endpoints 覆盖。endpoints支持在 URL 中内嵌 Basic 认证凭据如https://user:passwordexample.com若同时配置了auth且 URL 内含凭据会触发配置错误源码见 ElasticsearchConfig 注释。运行时如果检测到旧式endpoint字段ElasticsearchCommon::parse_many 会打印弃用告警DEPRECATION, use of deprecated option endpoint. Please use endpoints option instead.common.rs 第 279-281 行。因此从 0.18.0 时代迁移过来的endpoint配置在当前版本建议直接改写为endpoints列表。3.bulk_action→bulk.actionBulk API 的动作字段从顶层bulk_action移入bulk子块。当前实现见 BulkConfigpub struct BulkConfig { /// Action to use when making requests to the Elasticsearch Bulk API. /// Only index, create and update actions are supported. #[serde(default default_bulk_action)] pub action: UnconfinedTemplate, /// The name of the index to write events to. #[serde(default default_index)] pub index: Template, /// The default index to write events to if the template in bulk.index cannot be resolved pub template_fallback_index: OptionString, pub version: OptionUnconfinedTemplate, pub version_type: VersionType, }关键点取值范围为index、create、update三者之一默认值是index见 default_bulk_action()解析逻辑由 BulkAction::try_from 完成非法取值会报Invalid bulk action。bulk.action的类型是UnconfinedTemplate即支持按事件做模板渲染如action: {{ action }}在运行期由 ElasticsearchCommonMode::bulk_action 逐事件求值后再转成BulkActiondata_stream模式则固定为create。实际写入 Bulk 请求体的编解码在 encoder.rs 中完成每个事件的 action 行由write_bulk_action生成。另外顶层的bulk配置块本身也保留了历史别名——config.rs 第 192 行 的#[serde(alias normal, default)]表明旧版以normal命名的顶层块同样能映射到bulk这是为旧配置平滑过渡留下的兼容入口。4.index→bulk.index索引名从顶层index移入bulk.index。默认值为vector-%Y.%m.%d按天滚动索引见 default_index()支持模板化官方文档示例为application-{{ application_id }}-%Y-%m-%d。当前实现比 0.18.0 时期更精细有三个值得了解的机制见 ElasticsearchCommonMode::index模板失败回退可配置bulk.template_fallback_index指定模板渲染失败时使用的兜底索引confinement 安全约束bulk.index属于路由字段会先经过 common_mode() 的模板 confinement 检查再渲染。若渲染因安全约束而非普通渲染错误失败事件会被直接丢弃且不会回退到兜底索引——源码注释明确说明这是有意设计避免静默接受一个攻击性事件请求路由所有 bulk 请求最终发往{base_url}/_bulk?{query}端点由 ElasticsearchCommon::parse_config 拼接pipeline等查询参数也会附加在该 URI 上。5.headers→request.headersHTTP 请求头从顶层headers移入request子块。该结构定义在 sink 通用的 RequestConfig/// Outbound HTTP request settings. pub struct RequestConfig { #[serde(flatten)] pub tower: TowerRequestConfig, /// Additional HTTP headers to add to every HTTP request. pub headers: BTreeMapString, String, }要点request是扁平化嵌入的#[serde(flatten)]展开 tower 配置所以除headers外request子块下还能写max_retries、timeout等请求层参数头部名称与值均支持事件模板渲染如X-Event-Level: {{level}}、X-Event-Timestamp: {{timestamp}}源码通过 split_headers() 把头部拆分为静态头与模板头两类分别处理避免为纯静态头做逐事件渲染request.headers作用于每一个发往 Elasticsearch 的 HTTP 请求包括健康检查请求——get() 在构造 GET 请求时会遍历request.headers逐一附加。迁移前后配置对照结合上述映射一个典型的旧版0.18.0 之前配置sinks: es: type: elasticsearch inputs: [my_source] mode: normal host: http://10.24.32.122:9000 bulk_action: create index: application-%Y.%m.%d headers: X-My-Custom-Header: A-Value按 0.18.0 的弃用表迁移后为sinks: es: type: elasticsearch inputs: [my_source] mode: bulk # 默认值可省略 endpoint: http://10.24.32.122:9000 bulk: action: create # 默认 index index: application-%Y.%m.%d request: headers: X-My-Custom-Header: A-Value若进一步适配当前仓库对应的版本endpoint已弃用则推荐最终形态sinks: es: type: elasticsearch inputs: [my_source] endpoints: # 取代已弃用的单数 endpoint - http://10.24.32.122:9000 - http://10.24.32.123:9000 api_version: auto # 默认 auto启动时自动探测 bulk: action: create index: application-%Y.%m.%d request: headers: X-My-Custom-Header: A-Value后续版本中同样重要的弃用项除 0.18.0 这批字段外当前源码中还能看到两项仍在生效的弃用建议在改写配置时一并处理被弃用字段替代字段源码依据endpoint单地址endpoints地址列表config.rs 第 78-80 行 的deprecated元数据common.rs 第 279-281 行 的运行期告警suppress_type_nameapi_versionconfig.rs 第 122-125 行 的deprecated元数据common.rs 第 194-201 行 的运行期告警suppress_type_name与api_version的关系可以从源码推断type字段在 Elasticsearch 7.x 弃用、8.x 移除api_versionauto/v6/v7/v8取代了它的作用。当api_version: auto时Vector 在构建期向集群根路径发起 GET 请求读取主版本号get_version()若探测失败源码会降级为启发式假设——如果旧配置设置了suppress_type_name则假定 v6否则假定 v8common.rs 第 166-185 行并建议显式设置api_version。运行时行为与验证要点改写配置后几个可以在实际部署中验证的行为均有源码依据端点校验前移endpoint(s)必须包含 http/https 协议且带主机名否则在反序列化阶段即失败测试 validate_rejects_non_http_endpoint 断言错误信息含must be an absolute http(s) URL。版本号约束校验bulk.version与bulk.version_type的组合在 validate() 中会被静态校验例如version_type: external未配bulk.version会报ExternalVersioningWithoutVersion配了version却没配id_key会报ExternalVersioningWithoutDocumentID——这两类配置错误在构建期即可发现而不会拖到运行时。健康检查sink 通过GET /_cluster/health探活healthcheck()request.headers中配置的头部会随该请求发出Amazon OpenSearch Serverless 场景会跳过健康检查并强制api_version: autovalidate()。多端点容错endpoints列表中的每个地址各自构建一个 service经 build() 装配为分布式服务配合重试与健康逻辑在端点间调度健康检查采用select_ok语义任一端点可达即通过。部分失败重试request_retry_partial默认关闭若开启以重试含部分失败的批量请求源码注释提醒应配合id_key去重config.rs 第 127-131 行。小结迁移检查清单mode: normal改为mode: bulk或省略bulk为默认host改为endpoint并在当前版本进一步改为endpoints列表注意与auth的互斥规则——URL 内嵌凭据与显式auth二选一bulk_action改为bulk.action取值限index/create/update默认index支持按事件模板化index改为bulk.index默认vector-%Y.%m.%d可配bulk.template_fallback_index做渲染失败回退headers改为request.headers键值均支持事件模板渲染顺带审视suppress_type_name改为显式api_version避免探测失败时的启发式版本假设。以上每一项均能在 src/sinks/elasticsearch/ 模块内找到对应的解析、校验与渲染代码路径改写后可用vector validate在部署前捕获端点互斥、版本号组合等静态配置错误再借助/_cluster/health健康检查确认目标集群连通。【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考