Vector Loki Sink 健康检查端点定制指南healthcheck.uri配置深度解析【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector导读本文围绕 Vector 的 Loki sink 新增的healthcheck.uri配置字段展开说明如何自定义 Loki 健康检查healthcheck的探测端点。文中将从配置写法、底层实现、认证继承规则与回退机制入手结合本仓库 src/sinks/loki/healthcheck.rs 的源码与 src/sinks/loki/tests.rs 的测试用例帮助你理解这一增强项并正确应用到真实生产环境中。读完本文你将能精确控制 Vector 启动时对 Loki 实例的探测路径绕开默认/ready端点无法访问或返回非 200 状态导致启动失败的场景。变更背景与核心价值该增强项记录在 changelog.d/23000_loki_sink_healthcheck_uri.enhancement.md 中核心内容是Thelokisink now supports thehealthcheck.urifield to customize the healthcheck endpoint.在此之前Vector 的 loki sink 启动健康检查时只能依赖固定的端点推导逻辑默认在配置的endpoint后追加/ready。而现实中的 Loki 部署形态多种多样部分 Loki 服务并不暴露/ready路径返回 404使用反向代理、网关或负载均衡时/ready会被拦截或重写自定义部署的 Loki 需要检查与推送地址不同的就绪接口高可用集群中希望探测某个具体的健康检查端点而非默认路径。healthcheck.uri提供了一种显式覆盖手段用户直接在 sink 配置里声明要探测的完整 URIVector 将逐字verbatim访问该地址完全绕开默认的路径推导。从源码结构看该字段并非 loki sink 独有而是作为所有 HTTP 类 sink 的通用能力定义在 src/config/sink.rs 的SinkHealthcheckOptions中loki sink 只是将其接入并实现了完整的解析逻辑。prometheus remote_writesrc/sinks/prometheus/remote_write/config.rs、httpsrc/sinks/http/config.rs、vectorsrc/sinks/vector/config.rs等 sink 也使用同一套配置结构。healthcheck.uri配置字段说明字段定义与位置healthcheck.uri位于 sink 的healthcheck配置块下属于通用 sink 配置见 src/config/sink.rs 中SinkHealthcheckOptions的定义。该配置块包含三个字段字段类型默认值说明enabledbooltrue是否在 Vector 启动时执行健康检查timeoutfloat秒10秒健康检查请求的超时时间见 default_healthcheck_timeouturistringURInull不设置自定义健康检查的完整 URI本文主角其中uri的校验规则为uri格式见 src/config/sink.rs 的#[configurable(validation(format uri))]必须是一个合法 URI至少包含 scheme 与 host端口、路径等其他组成部分均可选。配置示例以下是一个在 loki sink 中启用自定义健康检查端点的完整示例sinks: my_loki_sink: type: loki inputs: [my_logs] endpoint: http://loki.internal:3100 labels: service: vector encoding: codec: json healthcheck: enabled: true timeout: 5.0 uri: http://loki.internal:3100/healthz配置要点uri必须是完整 URI含 scheme 与 host而不是相对路径例如http://loki.internal:3100/healthz不能只写/healthz该字段不设置时Vector 走默认的端点推导逻辑见下文默认探测逻辑一节enabled与timeout为可选字段仅在你需要关闭健康检查或调整超时时间时显式设置。与旧字段healthcheck_uri的关系值得注意的是仓库中还保留了一个顶层非healthcheck块内的旧字段healthcheck_uri。从 src/config/sink.rs 可以看到该字段已被标记为deprecated废弃。在SinkOuter::healthcheck()方法src/config/sink.rs中实现了合并逻辑若同时设置了healthcheck.uri与healthcheck_uri会打印警告并优先采用healthcheck.uri的值若只设置了旧的healthcheck_uri会打印弃用警告并将其值兼容迁移到healthcheck.uri语义下使用。也就是说新配置一律推荐使用healthcheck.uri旧字段仅保留向后兼容。底层实现剖析healthcheck 如何被构建与执行从配置到健康检查的调用链loki sink 的配置编译入口在 src/sinks/loki/config.rs 的ValidatedSink::build方法src/sinks/loki/config.rsasync fn build( self, validated: ValidatedLokiSink, cx: SinkContext, ) - crate::Result(VectorSink, crate::sinks::Healthcheck) { let healthcheck_uri cx.healthcheck.uri.clone(); let client self.build_client(cx)?; let sink LokiSink::from_validated(self, validated.clone(), client.clone())?; let healthcheck healthcheck( validated.base_endpoint.clone(), validated.auth.clone(), healthcheck_uri, client, ) .boxed(); Ok((VectorSink::from_event_streamsink(sink), healthcheck)) }调用链可以概括为配置编译阶段将healthcheck.uri解析进SinkContextcx.healthcheck.uribuild方法取出该值连同base_endpoint不含凭据的配置端点保留用户自定义 base path、auth认证信息与HttpClient一起传给healthcheck()函数healthcheck()返回一个Healthcheck即BoxFuture由拓扑在 Vector 启动时执行。关键点在于第 2 步中的base_endpoint在 src/sinks/loki/config.rs 的validate阶段loki sink 会先通过extract_basic_auth()从 endpoint 中剥离内嵌的基本认证凭据得到一个无凭据的 base endpoint推送 URL 由base_endpoint path默认/loki/api/v1/push见 default_loki_path构成而健康检查则在 base endpoint 基础上推导追加ready或/。当配置了healthcheck.uri时这个推导过程被整体跳过。自定义 URI 的执行逻辑核心实现位于 src/sinks/loki/healthcheck.rs。当healthcheck_uri被显式配置时执行逻辑非常直接if let Some(uri) healthcheck_uri { let auth uri.auth.or(auth); let status fetch_status(uri.uri, auth.as_ref(), client).await?; return match status { http::StatusCode::OK Ok(()), _ Err(format!(A non-successful status returned: {status}).into()), }; }行为要点URI 逐字使用配置的 URI 会原样作为探测目标不再追加任何路径仅接受 200只有当探测响应状态码为200 OK时健康检查才通过其他任何状态码包括 3xx 重定向都会被视为失败并返回错误认证优先级URI 中内嵌的凭据userinfo形如http://user:passhost/...优先于 sink 级配置的auth这一规则由uri.auth.or(auth)保证——URI 自带凭据时使用 URI 的否则回退到 sink 的认证配置。fetch_status的实现src/sinks/loki/healthcheck.rs只是构造一个 GET 请求并发送若存在认证信息则通过auth.apply(mut req)写入请求头通常为Authorization。默认探测逻辑与回退机制未配置healthcheck.uri时当未配置healthcheck.uri时Vector 的默认行为是在 base endpoint 上追加ready路径进行探测如http://loki.internal:3100/ready若返回404 Not Found则改为探测带尾部斜杠的规范化 base path如http://loki.internal:3100/loki/而非/loki并打印 debug 日志Endpoint /ready not found. Retrying healthcheck with top level query.src/sinks/loki/healthcheck.rs。这个回退设计参考了 issue 6463 的实践经验反向代理通常会把/loki重定向到/loki/而健康检查不跟随重定向、只接受 200因此回退探测带斜杠的路径是必要的。测试用例healthcheck_fallback_requests_base_path_with_trailing_slashsrc/sinks/loki/tests.rs专门验证了这一点/ready返回 404 后成功回退请求的路径必须是/loki/。源码验证测试用例如何保障该特性仓库中的单元测试从多个角度锁定了healthcheck.uri的行为这些测试既是该特性的验收标准也是理解语义的最佳注释。自定义 URI 逐字使用与认证优先级测试healthcheck_uses_configured_uri_with_uri_auth_precedencesrc/sinks/loki/tests.rs验证了配置自定义 URIhttp://user:pass{addr}/health后实际探测路径为/health而非默认的/ready断言assert_ne!(parts.uri.path(), /ready)URI 中内嵌凭据user:pass生成的Authorization头优先于 sink 配置的username:some_password断言 Basic 认证值为dXNlcjpwYXNz即user:pass的 base64。认证随健康检查请求发出测试healthcheck_includes_authsrc/sinks/loki/tests.rs验证了当只配置 sink 级authbasic 策略而不配置healthcheck.uri时健康检查请求同样携带Authorization: Basic ...头证明认证信息在默认与自定义两种路径下都会被正确传递。Grafana Cloud 实测测试healthcheck_grafana_cloudsrc/sinks/loki/tests.rs针对真实域名logs-prod-us-central1.grafana.net执行健康检查验证默认端点推导对托管的 Grafana Cloud Loki 同样适用该测试在 CI 网络可达时运行。实战场景与注意事项适用场景Loki 部署在反向代理之后代理只暴露特定的健康检查路径如/healthz此时用healthcheck.uri精确指定Loki 未提供/ready端点避免每次都触发 404 回退探测直接指向可用的就绪接口减少一次多余请求多租户/网关场景希望探测一个与推送 endpoint 无关的独立健康检查地址需要为健康检查单独设置凭据把凭据内嵌进healthcheck.uri如http://user:passloki:3100/ready会覆盖 sink 级auth适合健康检查与推送使用不同凭据的场景。注意事项uri 必须是合法完整 URI至少包含 scheme 与 host否则配置校验失败见 src/config/sink.rs只接受 200探测端点若返回重定向301/302或其他非 200 状态健康检查会失败Vector 启动时会报A non-successful status returned: {status}错误并中止启动流程取决于你的启动策略优先使用healthcheck.uri旧的顶层healthcheck_uri字段已废弃两者同时配置时以healthcheck.uri为准src/config/sink.rstimeout单位为秒支持小数如timeout: 5.0默认 10 秒default_healthcheck_timeout健康检查仅发生在启动阶段它负责在 Vector 启动时验证目标 sink 可达运行期故障由重试与缓冲机制处理与本特性无关。延伸阅读loki sink 主模块与路径拼接逻辑src/sinks/loki/mod.rsloki sink 配置结构endpoint、labels、out_of_order_action 等src/sinks/loki/config.rs通用 sink 健康检查配置SinkHealthcheckOptionssrc/config/sink.rs健康检查单元测试src/sinks/loki/tests.rs组件元数据确认 loki sink 健康检查启用且使用 URIwebsite/cue/reference/components/sinks/loki.cue该增强项的变更记录changelog.d/23000_loki_sink_healthcheck_uri.enhancement.md综上healthcheck.uri是一个轻量但实用的配置增强它以最小的配置代价把 loki sink 启动健康检查的探测端点控制权交还给用户配合仓库内置的认证继承与 404 回退逻辑可以覆盖绝大多数 Loki 部署形态下的健康检查需求。【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考