Dubbo-Go 可观测字段梳理

[AsperforMias]

For #3720. This audit uses develop@9af40a2b; the source and test links use the same revision.

Metric interface and OTel rpc.service both use URL.Service(). The main differences are in generic-call method names, error fields and log correlation.

RPC fields

Field	Metrics	OTel
Application	application_name from URL application	Resource service.name from application name
Application version	application_version from URL app.version	Resource service.version from application version
Interface	interface = URL.Service()	rpc.service = URL.Service()
Method	method = MethodName()	rpc.method = MethodName(); span name = ActualMethodName()
Group / service version	URL group / version	dubbo.group / dubbo.version, when non-empty
Calling side	dubbo_provider_* / dubbo_consumer_* names	SERVER / CLIENT span kind
Protocol	Absent	Absent; rpc.system is apache_dubbo
Instance	ip, hostname	No host/IP field in these spans or their configured resource

Sources: RPC labels, metric families, OTel filter, resource setup, application configuration. Tests: labels, span attributes.

RPC failures use separate timeout, limit, unavailable, business and unknown counter families, with no error_type label. The classifier handles Triple/gRPC codes; Dubbo-protocol errors fall into unknown. Network and codec categories are declared but not produced. The collector updates the counters. The OTel filter records an error status and err.Error() as its description, without calling RecordError on that path.

Logs

Trace integration defaults to false. With the context-aware Zap or Logrus adapter, a Ctx* call adds trace_id, span_id and trace_flags from a valid span context. Ordinary calls and contexts without a valid span omit those fields. Service, method, protocol, side and error category are not added automatically. CtxError* can record errors on a recording span when configured. See the extractor, Zap tests and Logrus tests.

AccessLog copies a fixed set of attachments: interface (with path fallback), method, version, group, timestamp, local-addr and remote-addr. It derives types and arguments from invocation.Arguments(). Its builder and formatter ignore trace_id, span_id and traceparent, even when those keys are attached.

Metadata

The catalog stores the application in MetadataInfo.App. ServiceInfo contains name, group, service version, protocol, port, path and params; method names are in the methods parameter. It has no calling-side or error-category field.

Mapping metrics use application tags plus interface and group from attachments. A non-empty attachment application overrides application_name; otherwise the application-level value is retained. There is no method or service-version label.

Register/remove use Succ to count success. Get/listen use Succ && !Partial, so partial success increments the failed counter. Each operation also records its total count and RT. Fetch adds provider_app, result, source and storage_type; cache adds provider_app with hit/miss counters. See definitions and tests.

Compatibility and follow-ups

Keep existing metric names/labels and the registration/routing meaning of ServiceKey(). That key has the form group/interface:version and omits version 0.0.0; the telemetry version fields retain the raw value. Trace/span IDs, revisions, URLs, payloads and error messages should stay out of default metric labels.

Difference	Code	Related work / owner	Check
Error fields differ across signals	Classifier, OTel, log adapters	#3337 — Saramanda9988; #3338 — jiaming2li / Oxidaner	Compare wrapped Triple and Dubbo errors across counters, spans and logs
Generic-call span name can differ from rpc.method	OTel, invocation	#3338 — jiaming2li / Oxidaner	Compare $invoke with its actual method name
AccessLog has no trace correlation	Builder and formatter	No implementation owner recorded	Attach trace IDs and inspect the emitted log

#3551 proposes span-name and attribute changes; those are not present at this pin. Update, 2026-10-16: #3743 and #3744 merged after the audited revision, adding Path-fallback and dynamic logger regression tests. #3763 proposes further logger assertions.

Verification

The nine packages below passed on 2026-10-16 with Go 1.25.0 / darwin/arm64. The audit branch changes documentation only; its runtime/test code remains at the audited revision.

GOTOOLCHAIN=go1.25.0 go test -mod=readonly -count=1 \
  ./metrics/rpc ./filter/otel/trace ./filter/metrics \
  ./logger ./logger/core/zap ./logger/core/logrus \
  ./filter/accesslog ./metadata/info ./metrics/metadata

[Tsukikage7]

Thanks for revising the audit and moving it here. I rechecked the current text against the pinned 9af40a2b835b5176be453b5f3936b1fc53a7ead4 source. My earlier review points are resolved:

• AccessLog now correctly describes the fixed attachment whitelist, interface/path fallback and argument-derived fields. Attached trace_id, span_id and traceparent are ignored by the builder/formatter; attaching them does not enable correlation.
• Metadata mapping labels now correctly distinguish application-level tags from attachment-derived interface/group, including the non-empty application override. There is no method or service-version label. Register/remove use Succ; get/listen use Succ && !Partial, so partial success counts as failure.
• The log section correctly states that trace integration is disabled by default, and automatic correlation requires the trace-aware adapter, a Ctx* call and a valid span context. The three emitted correlation fields and the configurable CtxError* behavior match the implementation.
• The pinned behavior remains separate from later merged tests (fix: keep group and version out of OTel rpc.service #3743/test(logger): add dynamic log-level regression for Zap and Logrus #3744) and proposed changes (feat(otel): standardize trace span names and semantic attributes #3551/test: complete dynamic logger acceptance coverage #3763). RPC fields, error handling, metadata representation and the compatibility/follow-up notes are consistent with the cited revision.

I independently reran the nine packages listed in Verification from a clean archive of that exact commit, with Go 1.25.0 on darwin/arm64 and -mod=readonly -count=1: all passed.

I have no remaining blocking comments on this documentation audit. This satisfies the documentation deliverable in #3720; the runtime gaps listed in the follow-up matrix remain separate implementation work.