feat(probe): add Kubernetes probe support with liveness, readiness, and startup checks by Alanxtl · Pull Request #3213 · apache/dubbo-go

Alanxtl · 2026-02-13T08:31:52Z

This is the implemention of #2039
which is the rewritten of #3047
usage are demonstrated in apache/dubbo-go-samples#1033
docs are written in apache/dubbo-website#3193

Kubernetes 探针（Probe）功能说明

本模块提供独立的 HTTP 探针服务，面向 Kubernetes 的 liveness、readiness、startup 三类探针。
它支持用户自定义健康检查逻辑，并可选择性地与 Dubbo Server 生命周期进行内部状态对齐。

设计目标

可扩展：通过回调注册自定义检查逻辑。
可控风险：liveness 默认不带内部逻辑，避免不当重启。
生命周期对齐：readiness/startup 可选用内部状态。

默认 HTTP 路径

当启用 probe 后，默认在22222端口下暴露以下路径：

GET /live：liveness 探针
GET /ready：readiness 探针
GET /startup：startup 探针

响应规则：

所有检查通过：HTTP 200
任一检查失败：HTTP 503

new api 配置方式

通过 metrics.NewOptions(...) 传入以下 Option 配置：

ins, err := dubbo.NewInstance(
  dubbo.WithMetrics(
    metrics.WithProbeEnabled(),
    metrics.WithProbePort(22222),
    metrics.WithProbeLivenessPath("/live"),
    metrics.WithProbeReadinessPath("/ready"),
    metrics.WithProbeStartupPath("/startup"),
    metrics.WithProbeUseInternalState(true),
  ),
)

old api 配置方式

在 metrics 配置下新增 probe 子配置：

metrics:
  probe:
    enabled: true
    port: "22222"
    liveness-path: "/live"
    readiness-path: "/ready"
    startup-path: "/startup"
    use-internal-state: true

配置项说明：

enabled：是否开启 probe 服务
port：probe HTTP 端口
liveness-path：liveness 路径
readiness-path：readiness 路径
startup-path：startup 路径
use-internal-state：是否启用内部生命周期状态检查，默认启用

内部状态（UseInternalState）

当 use-internal-state: true 时，探针会附加内部状态检查：

readiness 依赖 probe.SetReady(true/false)
startup 依赖 probe.SetStartupComplete(true/false)

默认行为：

应用启动完成后（Server.Serve() 成功执行）会设置 ready=true、startup=true
应用优雅关闭时会将 ready=false

如果设置为 false，则完全由用户注册的回调决定探针结果。

自定义健康检查（推荐）

通过注册回调即可扩展探针逻辑：

import "dubbo.apache.org/dubbo-go/v3/metrics/probe"

// liveness 例子
probe.RegisterLiveness("db", func(ctx context.Context) error {
    // 检查数据库连接
    return nil
})

// readiness 例子
probe.RegisterReadiness("cache", func(ctx context.Context) error {
    // 检查缓存或依赖中间件
    return nil
})

// startup 例子
probe.RegisterStartup("warmup", func(ctx context.Context) error {
    // 检查预热逻辑是否完成
    return nil
})

注意事项

liveness 风险：liveness 失败会触发 Pod 重启，请谨慎设置，推荐仅用作进程/核心依赖检测。
readiness 适配：可以关联注册中心、数据库、缓存、下游依赖等健康状态。
startup 适配：建议用于冷启动、预热或依赖初始化场景。

Kubernetes 示例

livenessProbe:
  httpGet:
    path: /live
    port: 22222
  initialDelaySeconds: 5
  periodSeconds: 5
readinessProbe:
  httpGet:
    path: /ready
    port: 22222
  initialDelaySeconds: 5
  periodSeconds: 5
startupProbe:
  httpGet:
    path: /startup
    port: 22222
  failureThreshold: 30
  periodSeconds: 10

Description

Fixes # (issue)

Checklist

I confirm the target branch is develop
Code has passed local testing
I have added tests that prove my fix is effective or that my feature works

…nd startup checks

codecov-commenter · 2026-02-13T08:44:20Z

Codecov Report

❌ Patch coverage is 45.89372% with 112 lines in your changes missing coverage. Please review.
✅ Project coverage is 47.92%. Comparing base (60d1c2a) to head (ae06411).
⚠️ Report is 750 commits behind head on develop.

Files with missing lines	Patch %	Lines
metrics/probe/server.go	0.00%	64 Missing ⚠️
metrics/options.go	0.00%	19 Missing ⚠️
metrics/probe/http.go	66.66%	6 Missing and 3 partials ⚠️
global/metric_config.go	63.63%	5 Missing and 3 partials ⚠️
compat.go	81.81%	2 Missing and 2 partials ⚠️
metrics/probe/probe.go	88.23%	2 Missing and 2 partials ⚠️
server/options.go	33.33%	1 Missing and 1 partial ⚠️
server/server.go	0.00%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #3213      +/-   ##
===========================================
+ Coverage    46.76%   47.92%   +1.16%     
===========================================
  Files          295      467     +172     
  Lines        17172    34042   +16870     
===========================================
+ Hits          8031    16316    +8285     
- Misses        8287    16403    +8116     
- Partials       854     1323     +469

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

AlexStocks

需要调整初始化路径：probe 现在在 config/metric_config.go 和 server/options.go 两处都可能触发 Init。虽然有 sync.Once，但会带来隐式优先级（谁先初始化谁生效），容易导致配置行为不一致。建议收敛为单一入口，另一处只做参数构造或删除。

metrics/probe/probe.go

metrics/probe/http.go

metrics/probe/server.go

config/metric_config.go

metrics/probe/server.go

server/server.go

Alanxtl · 2026-03-09T02:56:16Z

@CAICAIIs @zbchi @nanjiek

Alanxtl · 2026-03-09T08:22:08Z

需要调整初始化路径：probe 现在在 config/metric_config.go 和 server/options.go 两处都可能触发 Init。虽然有 sync.Once，但会带来隐式优先级（谁先初始化谁生效），容易导致配置行为不一致。建议收敛为单一入口，另一处只做参数构造或删除。

all done

sonarqubecloud · 2026-03-09T09:19:16Z

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

CAICAIIs

lgtm

my test result：
Commands executed

Core verification:
- go test ./metrics/probe/...
- go test -race ./metrics/probe/...
- go test ./server/...
Sample linkage/build:
- go mod edit -replace=dubbo.apache.org/dubbo-go/v3=（******）
- go mod tidy
- go build ./metrics/probe/go-server/cmd
- go build ./metrics/probe/go-client/cmd
End-to-end run:
- go run ./metrics/probe/go-server/cmd/main.go
- go run ./metrics/probe/go-client/cmd/main.go
  Verified results
Core tests
- metrics/probe tests: pass
- metrics/probe race tests: pass
- server tests: pass
Runtime behavior
- Server startup log confirms probe server is listening on :22222 and Triple service on :20000
- Client integration log confirms probe endpoints and RPC all pass
  Key log excerpts
  Server startup
/tmp/review-2039-server.log

2026-03-09 17:48:08 INFO probe/server.go:101 [kubernetes probe] probe server listening on :22222
2026-03-09 17:48:08 INFO cmd/main.go:136 Probe sample server started, triple=20000 probe=22222
2026-03-09 17:48:23 INFO cmd/main.go:78 Warmup completed, readiness/startup should be healthy

Client integration

/tmp/review-2039-client.log

2026-03-09 17:48:15 INFO /live is healthy
2026-03-09 17:48:23 INFO /ready is healthy
2026-03-09 17:48:23 INFO /startup is healthy
2026-03-09 17:48:23 INFO greet rpc succeeded: hello probe-check
2026-03-09 17:48:23 INFO probe sample integration checks passed

Warm-up phase probe behavior

/tmp/review-2039-precheck.log

HTTP/1.1 200 OK
...
ok
HTTP/1.1 503 Service Unavailable
...
probe warmup: warmup not complete
HTTP/1.1 503 Service Unavailable
...
probe warmup: startup warmup not complete

Post warm-up probe behavior

/tmp/review-2039-postcheck.log

HTTP/1.1 200 OK
...
ok
HTTP/1.1 200 OK
...
ok
HTTP/1.1 200 OK
...
ok

No-SilverBullet

LGTM

Alanxtl added 2 commits February 13, 2026 16:27

feat(probe): add Kubernetes probe support with liveness, readiness, a…

9f37c8d

…nd startup checks

import format

cb2cdae

Alanxtl requested a review from No-SilverBullet February 13, 2026 08:35

Alanxtl added ✏️ Feature 3.3.2 version 3.3.2 labels Feb 13, 2026

Alanxtl linked an issue Feb 13, 2026 that may be closed by this pull request

Expose readiness and liveness apis so the process's status can be detected by the scheduling cluster like K8S. #2039

Closed

Alanxtl added 2 commits February 13, 2026 16:39

delete useless test

62f7127

import format

53a5f19

Alanxtl mentioned this pull request Mar 6, 2026

feat: samples for k8s probe apache/dubbo-go-samples#1033

Merged

AlexStocks requested changes Mar 7, 2026

View reviewed changes