Skip to content

[FEATURE] Improve observability and error semantics for application-level metadata / 增强应用级 metadata 链路观测与错误语义 #3356

Closed

Description

@Alanxtl

上下文请参考 #3188 (comment)

Background

The application-level metadata path after #2534 includes local MetadataInfo, revision calculation, metadata report publishing/loading, service-app mapping, and RPC MetadataService. When service discovery fails, it is currently difficult to identify which stage caused the failure. This issue only focuses on observability for the application-level metadata path.

Related code:

  • metadata/report_instance.go
  • metadata/mapping/metadata/service_name_mapping.go
  • metadata/client.go
  • registry/servicediscovery/service_instances_changed_listener_impl.go

Current Problems

Current observability is not enough to diagnose application-level metadata failures.

Specific problems:

  • Mapping register, get, listen, and remove operations do not have unified metrics or structured logs.
  • Revision calculation and metadata cache hit/miss are hard to observe.
  • Errors from metadata report loading, RPC metadata loading, URL construction, and mapping are not clearly categorized.
  • When consumers cannot discover services, it is hard to tell whether the root cause is mapping, metadata report, RPC metadata service, revision, or cache.

Suggestions

  • Add metrics and structured logs for mapping register, get, listen, and remove operations.
  • Expose metadata source, storage type, revision, and cache hit/miss where appropriate.
  • Use clear error categories for metadata report failure, RPC metadata failure, URL construction failure, revision mismatch, and mapping failure.
  • Include useful context such as app, revision, service key, registry id, and storage type.
  • Add failure-path tests that verify error messages or categories.

背景

#2534 之后的应用级 metadata 链路包括本地 MetadataInfo、revision 计算、metadata report 发布/获取、service-app mapping 以及 RPC MetadataService。当服务发现失败时,目前较难判断具体失败阶段。本 issue 只关注应用级 metadata 链路的可观测性。

相关代码:

  • metadata/report_instance.go
  • metadata/mapping/metadata/service_name_mapping.go
  • metadata/client.go
  • registry/servicediscovery/service_instances_changed_listener_impl.go

当前问题

当前可观测性不足以诊断应用级 metadata 失败。

具体问题:

  • mapping register、get、listen、remove 缺少统一指标或结构化日志。
  • revision 计算和 metadata cache hit/miss 难以观测。
  • metadata report 获取、RPC metadata 获取、URL 构造和 mapping 相关错误没有清晰分类。
  • consumer 订阅不到服务时,难以判断根因是 mapping、metadata report、RPC metadata service、revision 还是 cache。

建议

  • 为 mapping register、get、listen、remove 增加指标和结构化日志。
  • 在适当位置暴露 metadata source、storage type、revision、cache hit/miss。
  • 为 metadata report failure、RPC metadata failure、URL construction failure、revision mismatch、mapping failure 使用清晰错误分类。
  • 增加 app、revision、service key、registry id、storage type 等有用上下文。
  • 增加失败路径测试,验证错误信息或错误分类。

Activity

  1. added theissue type on May 30, 2026
  2. changed the title [-][metadata] 增强应用级 metadata 链路观测与错误语义[/-] [+][FEATURE] Improve observability and error semantics for application-level metadata / 增强应用级 metadata 链路观测与错误语义[/+] on May 30, 2026
  3. Oxidaner commented on Jun 1, 2026

    @Oxidaner
    Contributor

    please assign to me

  4. Rachit-Gandhi commented on Jun 13, 2026

    @Rachit-Gandhi

    @Alanxtl is this issue still active, I can take it up?

  5. Alanxtl commented on Jun 14, 2026

    @Alanxtl
    MemberAuthor

    @Alanxtl is this issue still active, I can take it up?

    this issue have been assigned to @Oxidaner , if you are insterested in contributing to dubbo-go you can refer to the latest issues, which have not been assigned

  6. Alanxtl commented on Jun 14, 2026

    @Alanxtl
    MemberAuthor

    @Alanxtl is this issue still active, I can take it up?

    after discussion with @Oxidaner , u can take up this issue, I assign it to you

  7. Rachit-Gandhi commented on Jun 14, 2026

    @Rachit-Gandhi

    thanks @Alanxtl

  8. linked a pull request that will close this issuefeat: improve metadata observability #3463on Jun 30, 2026
  9. Modo-me commented on Jul 23, 2026

    @Modo-me
    Contributor

    I'm interested in this observability issue and would like to help move it forward. Could I continue working on it?

  10. Rachit-Gandhi commented on Jul 23, 2026

    @Rachit-Gandhi

    @Modo-me I am almost done with the code on this PR I have just been busy due to a personal emergency I will be able to close the issue with pr over weekend

  11. 1 remaining item

  12. Alanxtl commented on Jul 27, 2026

    @Alanxtl
    MemberAuthor

    @Rachit-Gandhi are you still working on it?

  13. Modo-me commented on Aug 5, 2026

    @Modo-me
    Contributor

    @Alanxtl Could I take over this issue? It looks like there hasn’t been much activity recently. I d like to work on it and plan to split the larger change into several smaller PRs so each part can be reviewed incrementally.

  14. Alanxtl commented on Aug 5, 2026

    @Alanxtl
    MemberAuthor

    @Alanxtl Could I take over this issue? It looks like there hasn’t been much activity recently. I d like to work on it and plan to split the larger change into several smaller PRs so each part can be reviewed incrementally.

    sure

  15. Modo-me commented on Aug 5, 2026

    @Modo-me
    Contributor

    Current plan divides the required PRs into two dimensions Observability and Error semantics.

    Observability:
    • PR1: Complete observability for mapping operations — unified metrics and structured logs for register, get, listen, and remove
    • PR2: Expose observability for metadata source, storage type, revision, and cache hit/miss along the metadata path
    Error semantics:
    • PR3: Classify errors, enrich them with useful context, and add failure-path tests
  16. Alanxtl commented on Aug 6, 2026

    @Alanxtl
    MemberAuthor

    Current plan divides the required PRs into two dimensions Observability and Error semantics.

    Observability:
    • PR1: Complete observability for mapping operations — unified metrics and structured logs for register, get, listen, and remove
    • PR2: Expose observability for metadata source, storage type, revision, and cache hit/miss along the metadata path
    Error semantics:
    • PR3: Classify errors, enrich them with useful context, and add failure-path tests

    注意一下别和这个的职责划分冲突了#3562

  17. added
    3.3.3version 3.3.3
    and removed
    3.3.2version 3.3.2
    on Aug 6, 2026
  18. Modo-me commented on Aug 6, 2026

    @Modo-me
    Contributor

    Current plan divides the required PRs into two dimensions Observability and Error semantics.目前的计划将所需的 PR 分为两个维度:可观测性和错误语义。

    Observability:  可观测性:
    • PR1: Complete observability for mapping operations — unified metrics and structured logs for register, get, listen, and removePR1:映射操作的完全可观测性——统一的指标和结构化日志,用于注册、获取、监听和删除操作。
    • PR2: Expose observability for metadata source, storage type, revision, and cache hit/miss along the metadata pathPR2:公开元数据路径上的元数据来源、存储类型、版本和缓存命中/未命中情况的可观测性
    Error semantics:  错误语义:
    • PR3: Classify errors, enrich them with useful context, and add failure-path testsPR3:对错误进行分类,添加有用的上下文信息,并添加故障路径测试

    注意一下别和这个的职责划分冲突了#3562

    已查看 与现有工作不产生冲突

  19. Modo-me commented on Aug 6, 2026

    @Modo-me
    Contributor

    @Alanxtl 关于增加结构化日志这里,可能需要进一步讨论。目前没看到仓库里有现成的结构化日志标准,仓库内logger给的是Debug/Info/Warn/Error + f 的方法,并不是结构化日志。PR #3605 暂时先采用了logger的那一套日志方法

  20. linked a pull request that will close this issueFeat: enhance mapping observability #3605on Aug 11, 2026
  21. Alanxtl commented on Aug 11, 2026

    @Alanxtl
    MemberAuthor

    logger

    我就是这个意思 使用gost的logger

  22. Modo-me commented on Sep 9, 2026

    @Modo-me
    Contributor

    @Alanxtl 这个issue应该都解决了,可以close了

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions