apache / apache/dubbo-go

[FEATURE] Improve Metrics coverage and standardization / 提升 Metrics 覆盖度与标准化

Open
#3,337 7 comments 0 reactions 1 assignee Claimed by @Saramanda9988 View on GitHub
✏️ Feature 3.3.3
Dominant language
Go
Stars
5k
Forks
1k
Avg merge
3d 6h
Merged PRs (30d)
29

Description

## Background / 背景

Dubbo-go already has a working metrics pipeline based on the metrics event bus, Prometheus registry/exporter, RPC metrics, registry metrics, metadata metrics, config-center metrics, and application info metrics. The next step is to make these metrics more complete, more stable, and easier to consume in production dashboards and alerts.

Dubbo-go 目前已经具备基于 metrics event bus 的指标链路,并支持 Prometheus registry/exporter、RPC 指标、注册中心指标、元数据指标、配置中心指标以及应用信息指标。下一步可以继续提升指标覆盖度、稳定性和生产环境中的 dashboard/alert 可消费性。

## Goals / 目标

Improve metrics coverage and standardization so users can rely on a stable RED-style observability model across provider, consumer, registry, metadata, and config-center scenarios.

提升指标覆盖度与标准化程度,让用户可以在 provider、consumer、registry、metadata、config-center 等场景下依赖稳定的 RED 风格可观测模型。

## Proposed Scope / 建议范围

### 1. Standardize metric names and labels / 标准化指标名和标签

- Define a documented label contract for built-in metrics.
- Clarify stable labels such as `side`, `protocol`, `interface`, `method`, `group`, `version`, `error_code`, and `error_type`.
- Review high-cardinality labels and avoid exposing unstable values by default.
- Ensure provider and consumer metrics use symmetric naming where possible.

- 为内置指标定义并文档化 label 契约。
- 明确稳定 label,例如 `side`、`protocol`、`interface`、`method`、`group`、`version`、`error_code`、`error_type`。
- 评估高基数 label,默认避免暴露不稳定取值。
- 尽可能保证 provider 和 consumer 指标命名对称。

### 2. Complete RPC error classification / 完善 RPC 错误分类

Current RPC metrics already include granular counters for timeout, limit, service unavailable, business failure, and unknown failure. This can be improved further:

当前 RPC metrics 已经包含 timeout、limit、service unavailable、business failure、unknown failure 等细粒度计数,后续可以继续增强:

- Extend error classification beyond Triple/gRPC error codes where possible.
- Add coverage for Dubbo protocol errors.
- Distinguish network failure and codec/serialization failure when the runtime exposes enough information.
- Ensure the same error taxonomy is reusable by tracing and logging.

- 在可行时将错误分类扩展到 Triple/gRPC 错误码之外。
- 补充 Dubbo protocol 错误覆盖。
- 当运行时暴露足够信息时,区分网络错误和 codec/序列化错误。
- 确保同一套错误分类可以被 tracing 和 logging 复用。

### 3. Clarify RED metrics support / 明确 RED 指标支持

Provide a clear out-of-the-box model for:

提供清晰的开箱即用模型:

- Rate: request QPS and total request counters.
- Errors: total failures and categorized failures.
- Duration: RT, aggregated RT, and quantile metrics.

- Rate:请求 QPS 和请求总数。
- Errors:总失败数和分类失败数。
- Duration:RT、聚合 RT 和分位数指标。

This should be reflected in code comments, docs, and sample dashboards.

这些内容应体现在代码注释、文档和示例 dashboard 中。

### 4. Improve component-level metrics layering / 改进组件级指标分层

Review registry, metadata, and config-center metrics and classify them into:

梳理 registry、metadata、config-center 指标,并将其分为:

- Basic metrics enabled by default when metrics are enabled.
- Detailed metrics that may be enabled explicitly to reduce noise.

- metrics 开启后默认启用的基础指标。
- 需要显式开启的细粒度指标,以减少噪音。

Candidate areas:

候选范围:

- Registry register/subscribe/notify/directory metrics.
- Metadata push/subscribe/store metrics.
- Config-center change metrics.

- 注册中心 register/subscribe/notify/directory 指标。
- 元数据 push/subscribe/store 指标。
- 配置中心变更指标。

### 5. Align samples and dashboard queries / 对齐示例和 dashboard 查询

Update or verify the Prometheus/Grafana sample to use the standardized names and labels:

更新或确认 Prometheus/Grafana 示例使用标准化后的指标名和 label:

- `dubbo-go-samples/metrics/prometheus_grafana`
- Grafana panels for QPS, success rate, error rate, P99 latency, timeout rate, limit rate, and service unavailable rate.
- Prometheus query examples in docs.

- `dubbo-go-samples/metrics/prometheus_grafana`
- Grafana 面板覆盖 QPS、成功率、错误率、P99 延迟、超时率、限流率、服务不可用率。
- 文档中补充 Prometheus 查询示例。

## Acceptance Criteria / 验收标准

- Built-in metrics have documented names, labels, and cardinality guidance.
- RPC failure metrics have a consistent taxonomy shared across provider and consumer sides.
- Existing Prometheus/Grafana sample dashboards continue to work or are updated with the new metric contract.
- Tests cover the standardized metric names/labels and error classification behavior.
- Backward compatibility impact is documented if any metric is renamed or deprecated.

- 内置指标具备文档化的指标名、label 和基数控制建议。
- RPC 失败指标在 provider 和 consumer 两侧使用一致的错误分类体系。
- 现有 Prometheus/Grafana 示例 dashboard 可继续工作,或已按新的指标契约更新。
- 测试覆盖标准化后的指标名/label 和错误分类行为。
- 如果存在指标重命名或废弃,需要明确说明兼容性影响。

## Related Context / 相关上下文

- Existing metrics implementation: `metrics/*`, `filter/metrics`, `metrics/prometheus`
- Existing sample: https://github.com/apache/dubbo-go-samples/tree/main/metrics/prometheus_grafana

- 现有 metrics 实现:`metrics/*`、`filter/metrics`、`metrics/prometheus`
- 现有示例:https://github.com/apache/dubbo-go-samples/tree/main/metrics/prometheus_grafana

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.