# Semantic conventions for Apache Dubbo Site [llms.txt](/llms.txt) --- **Status**: [Stable][DocumentStatus], unless otherwise specified - [Spans](#spans) - [Client](#client) - [Server](#server) - [Metrics](#metrics) - [Metric: `rpc.server.call.duration` (Dubbo)](#metric-rpcservercallduration-dubbo) - [Metric: `rpc.client.call.duration` (Dubbo)](#metric-rpcclientcallduration-dubbo) The Semantic Conventions for [Apache Dubbo](https://dubbo.apache.org/) extend and override the [RPC Semantic Conventions](README.md). ## Spans ### Client **Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) This span represents an outgoing Remote Procedure Call (RPC). **Span name:** refer to the [Span Name](/docs/specs/semconv/rpc/rpc-spans.md#name) section. **Span kind** MUST be `CLIENT`. **Span status** Refer to the [Recording Errors](/docs/specs/semconv/general/recording-errors.md) document for details on how to record span status. See also `rpc.status_code` attribute for the details on which values classify as errors. **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`rpc.method`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | The fully-qualified logical name of the method from the RPC interface perspective. [1] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | | [`rpc.status_code`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | The string representation of the Dubbo response status code returned by the server or generated by the client. [2] | `OK`; `DEADLINE_EXCEEDED`; `SERVER_ERROR` | | [`rpc.system.name`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | The Remote Procedure Call (RPC) system. [3] | `dubbo` | | [`error.type`](/docs/specs/semconv/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [4] | `DEADLINE_EXCEEDED`; `SERVER_ERROR` | | [`rpc.method_original`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if it's different than `rpc.method`. | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | | [`server.address`](/docs/specs/semconv/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If available. | string | A string identifying a group of RPC server instances request is sent to. [5] | `192.168.1.100`; `api.example.com`; `zookeeper://127.0.0.1:2181/com.example.HelloService:1.0.0:testGroup` | | [`server.port`](/docs/specs/semconv/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [6] | int | Server port number. [7] | `20880`; `50051` | | [`network.peer.address`](/docs/specs/semconv/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or UNIX domain socket name. [8] | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/specs/semconv/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | | [`rpc.request.header.`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Opt-In` | string[] | Dubbo request attachments. [9] | `["1.2.3.4", "1.2.3.5"]` | | [`rpc.response.trailer.`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Opt-In` | string[] | Dubbo response attachments. [10] | `["attribute_value"]` | **[1] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such frameworks MUST set this attribute to the original method name only when the method is recognized by the framework or library. When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. **[2] `rpc.status_code`:** All status codes except `OK` SHOULD be considered errors. Status codes reference: - Dubbo2: [Dubbo2 Protocol Status Codes](https://dubbo.apache.org/en/overview/reference/protocols/tcp/#protocol-specification) - Dubbo3 Triple protocol: [Triple Protocol Error Codes](https://dubbo.apache.org/en/overview/reference/protocols/triple-spec/#311-request) Instrumentations MAY use additional context or provide configuration options to customize which status codes are considered errors. **[3] `rpc.system.name`:** MUST be set to `dubbo`. **[4] `error.type`:** If the RPC fails with an error before status code is returned, `error.type` SHOULD be set to the exception type (its fully-qualified class name, if applicable) or a component-specific, low cardinality error identifier. If a status code is returned and it indicates an error, `error.type` SHOULD be set to that status code. See the `rpc.status_code` attribute for the list of Dubbo status codes that are considered errors. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. **[5] `server.address`:** Instrumentations SHOULD populate `server.address` (and `server.port`, when applicable) based on the configuration used when creating the Dubbo client and SHOULD NOT use actual network-level connection information for this purpose to ensure low cardinality. For direct connection, when the consumer is configured with an explicit provider target URL, instrumentations SHOULD parse `server.address` and `server.port` from that URL. For service discovery through a registry, instrumentations SHOULD set `server.address` to the service-discovery target and SHOULD NOT set `server.port`. The service-discovery target is: `{registry-protocol}://{registry-host}:{registry-port}/{logical-service-target}` The `{registry-port}` component is part of the registry endpoint in the service-discovery target and SHOULD NOT be recorded as `server.port`, because it is not the network transport port used for Dubbo RPC communication. It is composed of two parts separated by the `/` between the registry endpoint and logical service target: - Registry endpoint: `{registry-protocol}://{registry-host}:{registry-port}` - Logical service target: `{interface}[:{version}][:{group}]`, derived from the consumer URL, where: - `{interface}` is the service interface name from the consumer URL. - `{version}` is the `version` URL parameter, if set. - `{group}` is the `group` URL parameter, if set. - When only `{group}` is set, the format is `{interface}::{group}`. Examples: Direct connection: - Given the target URL `dubbo://192.168.1.100:20880/com.example.DemoService`, expected attributes: - `server.address`: `"192.168.1.100"` - `server.port`: `20880` - Given the target URL `tri://api.example.com:50051/com.example.GreeterService`, expected attributes: - `server.address`: `"api.example.com"` - `server.port`: `50051` - Given the target URL `tri://api.example.com/com.example.GreeterService` (port not specified), expected attributes: - `server.address`: `"api.example.com"` - `server.port`: not set Service discovery (registry): - Given a consumer that discovers providers via ZooKeeper for `com.example.HelloService` with `version=1.0.0` and `group=testGroup`, expected attributes: - Service-discovery target: `"zookeeper://127.0.0.1:2181/com.example.HelloService:1.0.0:testGroup"` - `server.address`: `"zookeeper://127.0.0.1:2181/com.example.HelloService:1.0.0:testGroup"` - `server.port`: not set - Given a consumer that discovers providers via Nacos for `com.example.HelloService` with `group=gray` (no version), expected attributes: - Service-discovery target: `"nacos://127.0.0.1:8848/com.example.HelloService::gray"` - `server.address`: `"nacos://127.0.0.1:8848/com.example.HelloService::gray"` - `server.port`: not set When the address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the IP address provided. **[6] `server.port`:** If `server.address` is set and a port is specified in the direct provider target URL. **[7] `server.port`:** See the `server.address` for details on parsing the target string. **[8] `network.peer.address`:** If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used. **[9] `rpc.request.header.`:** `` is the normalized header name (lowercase), the value is the header values. Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Capturing all of them can be a security risk - explicit configuration helps avoid leaking sensitive information. For example, a header `my-custom-key` with value `["1.2.3.4", "1.2.3.5"]` SHOULD be recorded as the `rpc.request.header.my-custom-key` attribute with value `["1.2.3.4", "1.2.3.5"]`. The attribute value MUST consist of either multiple values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the RPC library provides access to headers. Depending on the protocol, this attribute SHOULD capture: - Triple: [Request attachments](https://dubbo.apache.org/en/overview/reference/protocols/triple-spec/#322-requests). Values associated with keys ending in [`-bin`](https://github.com/grpc/grpc/blob/v1.75.0/doc/PROTOCOL-HTTP2.md#requests) are binary and SHOULD be base64-encoded. - Dubbo2: None (the protocol does not support request headers). **[10] `rpc.response.trailer.`:** `` is the normalized trailer name (lowercase), the value is the trailer values. Instrumentations SHOULD require an explicit configuration of which trailers are to be captured. Capturing all of them can be a security risk - explicit configuration helps avoid leaking sensitive information. For example, a trailer `my-custom-key` with value `["attribute_value"]` SHOULD be recorded as the `rpc.response.trailer.my-custom-key` attribute with value `["attribute_value"]`. The attribute value MUST consist of either multiple values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the RPC library provides access to trailers. Depending on the protocol, this attribute SHOULD capture: - Triple: [Response attachments](https://dubbo.apache.org/en/overview/reference/protocols/triple-spec/#323-responses). Values associated with keys ending in [`-bin`](https://github.com/grpc/grpc/blob/v1.75.0/doc/PROTOCOL-HTTP2.md#requests) are binary and SHOULD be base64-encoded. - Dubbo2: None (the protocol does not support response trailers). The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): * [`rpc.method`](/docs/specs/semconv/registry/attributes/rpc.md) * [`rpc.system.name`](/docs/specs/semconv/registry/attributes/rpc.md) * [`server.address`](/docs/specs/semconv/registry/attributes/server.md) * [`server.port`](/docs/specs/semconv/registry/attributes/server.md) ### Server **Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) This span represents an incoming Remote Procedure Call (RPC). **Span name:** refer to the [Span Name](/docs/specs/semconv/rpc/rpc-spans.md#name) section. **Span kind** MUST be `SERVER`. **Span status** Refer to the [Recording Errors](/docs/specs/semconv/general/recording-errors.md) document for details on how to record span status. See also `rpc.status_code` attribute for the details on which values classify as errors. **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`rpc.status_code`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | The string representation of the Dubbo response status code returned by the server. [1] | `OK`; `SERVER_ERROR`; `SERVER_THREADPOOL_EXHAUSTED_ERROR` | | [`rpc.system.name`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | The Remote Procedure Call (RPC) system. [2] | `dubbo` | | [`error.type`](/docs/specs/semconv/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | `SERVER_ERROR`; `SERVER_THREADPOOL_EXHAUSTED_ERROR`; `SERVER_TIMEOUT`; `SERVICE_ERROR`; `DATA_LOSS`; `DEADLINE_EXCEEDED`; `INTERNAL`; `UNAVAILABLE`; `UNIMPLEMENTED`; `UNKNOWN` | | [`rpc.method`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | | [`rpc.method_original`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if it's different than `rpc.method`. | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | | [`server.port`](/docs/specs/semconv/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` if applicable and if `server.address` is set. | int | Server port number. [5] | `80`; `8080`; `443` | | [`network.peer.address`](/docs/specs/semconv/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or UNIX domain socket name. [6] | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/specs/semconv/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | | [`server.address`](/docs/specs/semconv/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` when available. | string | A string identifying a group of RPC server instances request is sent to. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`rpc.request.header.`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Opt-In` | string[] | Dubbo request attachments. [8] | `["1.2.3.4", "1.2.3.5"]` | | [`rpc.response.trailer.`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Opt-In` | string[] | Dubbo response attachments. [9] | `["attribute_value"]` | **[1] `rpc.status_code`:** For Dubbo2, the following status codes SHOULD be considered errors: - `SERVER_ERROR` - `SERVER_THREADPOOL_EXHAUSTED_ERROR` - `SERVER_TIMEOUT` - `SERVICE_ERROR` For Dubbo3 Triple protocol, the following status codes SHOULD be considered errors: - `DATA_LOSS` - `DEADLINE_EXCEEDED` - `INTERNAL` - `UNAVAILABLE` - `UNIMPLEMENTED` - `UNKNOWN` Status codes reference: - Dubbo2: [Dubbo2 Protocol Status Codes](https://dubbo.apache.org/en/overview/reference/protocols/tcp/#protocol-specification) - Dubbo3 Triple protocol: [Triple Protocol Error Codes](https://dubbo.apache.org/en/overview/reference/protocols/triple-spec/#311-request) Instrumentations MAY use additional context or provide configuration options to customize which status codes are considered errors. **[2] `rpc.system.name`:** MUST be set to `dubbo`. **[3] `error.type`:** If the RPC fails with an error before status code is returned, `error.type` SHOULD be set to the exception type (its fully-qualified class name, if applicable) or a component-specific, low cardinality error identifier. If a status code is returned and it indicates an error, `error.type` SHOULD be set to that status code. See the `rpc.status_code` attribute for the list of Dubbo status codes that are considered errors. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. **[4] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such frameworks MUST set this attribute to the original method name only when the method is recognized by the framework or library. When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. **[5] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[6] `network.peer.address`:** If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used. **[7] `server.address`:** `server.address` and `server.port` describe the address the client used to reach this server, as reported by the transport or RPC framework. Instrumentations SHOULD NOT use actual network-level connection information to populate these attributes. If the address used by the client is unavailable, instrumentations SHOULD NOT set these attributes. **[8] `rpc.request.header.`:** `` is the normalized header name (lowercase), the value is the header values. Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Capturing all of them can be a security risk - explicit configuration helps avoid leaking sensitive information. For example, a header `my-custom-key` with value `["1.2.3.4", "1.2.3.5"]` SHOULD be recorded as the `rpc.request.header.my-custom-key` attribute with value `["1.2.3.4", "1.2.3.5"]`. The attribute value MUST consist of either multiple values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the RPC library provides access to headers. Depending on the protocol, this attribute SHOULD capture: - Triple: [Request attachments](https://dubbo.apache.org/en/overview/reference/protocols/triple-spec/#322-requests). Values associated with keys ending in [`-bin`](https://github.com/grpc/grpc/blob/v1.75.0/doc/PROTOCOL-HTTP2.md#requests) are binary and SHOULD be base64-encoded. - Dubbo2: None (the protocol does not support request headers). **[9] `rpc.response.trailer.`:** `` is the normalized trailer name (lowercase), the value is the trailer values. Instrumentations SHOULD require an explicit configuration of which trailers are to be captured. Capturing all of them can be a security risk - explicit configuration helps avoid leaking sensitive information. For example, a trailer `my-custom-key` with value `["attribute_value"]` SHOULD be recorded as the `rpc.response.trailer.my-custom-key` attribute with value `["attribute_value"]`. The attribute value MUST consist of either multiple values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the RPC library provides access to trailers. Depending on the protocol, this attribute SHOULD capture: - Triple: [Response attachments](https://dubbo.apache.org/en/overview/reference/protocols/triple-spec/#323-responses). Values associated with keys ending in [`-bin`](https://github.com/grpc/grpc/blob/v1.75.0/doc/PROTOCOL-HTTP2.md#requests) are binary and SHOULD be base64-encoded. - Dubbo2: None (the protocol does not support response trailers). The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): * [`rpc.method`](/docs/specs/semconv/registry/attributes/rpc.md) * [`rpc.system.name`](/docs/specs/semconv/registry/attributes/rpc.md) * [`server.address`](/docs/specs/semconv/registry/attributes/server.md) * [`server.port`](/docs/specs/semconv/registry/attributes/server.md) ## Metrics Dubbo instrumentations SHOULD collect metrics according to the general [Semantic Conventions for RPC Metrics](/docs/specs/semconv/rpc/rpc-metrics.md). ### Metric: `rpc.server.call.duration` (Dubbo) This metric is [recommended][MetricRecommended]. This metric follows the common [`rpc.server.call.duration`](/docs/specs/semconv/rpc/rpc-metrics.md#metric-rpcservercallduration) definition. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `rpc.server.call.duration` | Histogram | `s` | Measures the duration of an incoming Dubbo call. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | **[1]:** When this metric is reported alongside an RPC server span, the metric value SHOULD be the same as the RPC server span duration. **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`rpc.status_code`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | The string representation of the Dubbo response status code returned by the server. [1] | `OK`; `SERVER_ERROR`; `SERVER_THREADPOOL_EXHAUSTED_ERROR` | | [`rpc.system.name`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | The Remote Procedure Call (RPC) system. [2] | `dubbo` | | [`error.type`](/docs/specs/semconv/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | `SERVER_ERROR`; `SERVER_THREADPOOL_EXHAUSTED_ERROR`; `SERVER_TIMEOUT`; `SERVICE_ERROR`; `DATA_LOSS`; `DEADLINE_EXCEEDED`; `INTERNAL`; `UNAVAILABLE`; `UNIMPLEMENTED`; `UNKNOWN` | | [`rpc.method`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [4] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | | [`server.address`](/docs/specs/semconv/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | string | A string identifying a group of RPC server instances request is sent to. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`server.port`](/docs/specs/semconv/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | int | Server port number. [6] | `80`; `8080`; `443` | **[1] `rpc.status_code`:** For Dubbo2, the following status codes SHOULD be considered errors: - `SERVER_ERROR` - `SERVER_THREADPOOL_EXHAUSTED_ERROR` - `SERVER_TIMEOUT` - `SERVICE_ERROR` For Dubbo3 Triple protocol, the following status codes SHOULD be considered errors: - `DATA_LOSS` - `DEADLINE_EXCEEDED` - `INTERNAL` - `UNAVAILABLE` - `UNIMPLEMENTED` - `UNKNOWN` Status codes reference: - Dubbo2: [Dubbo2 Protocol Status Codes](https://dubbo.apache.org/en/overview/reference/protocols/tcp/#protocol-specification) - Dubbo3 Triple protocol: [Triple Protocol Error Codes](https://dubbo.apache.org/en/overview/reference/protocols/triple-spec/#311-request) Instrumentations MAY use additional context or provide configuration options to customize which status codes are considered errors. **[2] `rpc.system.name`:** MUST be set to `dubbo`. **[3] `error.type`:** If the RPC fails with an error before status code is returned, `error.type` SHOULD be set to the exception type (its fully-qualified class name, if applicable) or a component-specific, low cardinality error identifier. If a status code is returned and it indicates an error, `error.type` SHOULD be set to that status code. See the `rpc.status_code` attribute for the list of Dubbo status codes that are considered errors. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. **[4] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such frameworks MUST set this attribute to the original method name only when the method is recognized by the framework or library. When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. **[5] `server.address`:** `server.address` and `server.port` describe the address the client used to reach this server, as reported by the transport or RPC framework. Instrumentations SHOULD NOT use actual network-level connection information to populate these attributes. If the address used by the client is unavailable, instrumentations SHOULD NOT set these attributes. **[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. ### Metric: `rpc.client.call.duration` (Dubbo) This metric is [recommended][MetricRecommended]. This metric follows the common [`rpc.client.call.duration`](/docs/specs/semconv/rpc/rpc-metrics.md#metric-rpcclientcallduration) definition. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `rpc.client.call.duration` | Histogram | `s` | Measures the duration of an outgoing Dubbo call. [1] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | **[1]:** When this metric is reported alongside an RPC client span, the metric value SHOULD be the same as the RPC client span duration. **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`rpc.method`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | The fully-qualified logical name of the method from the RPC interface perspective. [1] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | | [`rpc.status_code`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | The string representation of the Dubbo response status code returned by the server or generated by the client. [2] | `OK`; `DEADLINE_EXCEEDED`; `SERVER_ERROR` | | [`rpc.system.name`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | The Remote Procedure Call (RPC) system. [3] | `dubbo` | | [`error.type`](/docs/specs/semconv/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [4] | `DEADLINE_EXCEEDED`; `SERVER_ERROR` | | [`server.address`](/docs/specs/semconv/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If available. | string | A string identifying a group of RPC server instances request is sent to. [5] | `192.168.1.100`; `api.example.com`; `zookeeper://127.0.0.1:2181/com.example.HelloService:1.0.0:testGroup` | | [`server.port`](/docs/specs/semconv/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [6] | int | Server port number. [7] | `20880`; `50051` | **[1] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such frameworks MUST set this attribute to the original method name only when the method is recognized by the framework or library. When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to `_OTHER`. If the RPC instrumentation could end up converting valid RPC methods to `_OTHER`, then it SHOULD provide a way to configure the list of recognized RPC methods. The `rpc.method` can be different from the name of any implementing method/function. The `code.function.name` attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side. **[2] `rpc.status_code`:** All status codes except `OK` SHOULD be considered errors. Status codes reference: - Dubbo2: [Dubbo2 Protocol Status Codes](https://dubbo.apache.org/en/overview/reference/protocols/tcp/#protocol-specification) - Dubbo3 Triple protocol: [Triple Protocol Error Codes](https://dubbo.apache.org/en/overview/reference/protocols/triple-spec/#311-request) Instrumentations MAY use additional context or provide configuration options to customize which status codes are considered errors. **[3] `rpc.system.name`:** MUST be set to `dubbo`. **[4] `error.type`:** If the RPC fails with an error before status code is returned, `error.type` SHOULD be set to the exception type (its fully-qualified class name, if applicable) or a component-specific, low cardinality error identifier. If a status code is returned and it indicates an error, `error.type` SHOULD be set to that status code. See the `rpc.status_code` attribute for the list of Dubbo status codes that are considered errors. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. **[5] `server.address`:** Instrumentations SHOULD populate `server.address` (and `server.port`, when applicable) based on the configuration used when creating the Dubbo client and SHOULD NOT use actual network-level connection information for this purpose to ensure low cardinality. For direct connection, when the consumer is configured with an explicit provider target URL, instrumentations SHOULD parse `server.address` and `server.port` from that URL. For service discovery through a registry, instrumentations SHOULD set `server.address` to the service-discovery target and SHOULD NOT set `server.port`. The service-discovery target is: `{registry-protocol}://{registry-host}:{registry-port}/{logical-service-target}` The `{registry-port}` component is part of the registry endpoint in the service-discovery target and SHOULD NOT be recorded as `server.port`, because it is not the network transport port used for Dubbo RPC communication. It is composed of two parts separated by the `/` between the registry endpoint and logical service target: - Registry endpoint: `{registry-protocol}://{registry-host}:{registry-port}` - Logical service target: `{interface}[:{version}][:{group}]`, derived from the consumer URL, where: - `{interface}` is the service interface name from the consumer URL. - `{version}` is the `version` URL parameter, if set. - `{group}` is the `group` URL parameter, if set. - When only `{group}` is set, the format is `{interface}::{group}`. Examples: Direct connection: - Given the target URL `dubbo://192.168.1.100:20880/com.example.DemoService`, expected attributes: - `server.address`: `"192.168.1.100"` - `server.port`: `20880` - Given the target URL `tri://api.example.com:50051/com.example.GreeterService`, expected attributes: - `server.address`: `"api.example.com"` - `server.port`: `50051` - Given the target URL `tri://api.example.com/com.example.GreeterService` (port not specified), expected attributes: - `server.address`: `"api.example.com"` - `server.port`: not set Service discovery (registry): - Given a consumer that discovers providers via ZooKeeper for `com.example.HelloService` with `version=1.0.0` and `group=testGroup`, expected attributes: - Service-discovery target: `"zookeeper://127.0.0.1:2181/com.example.HelloService:1.0.0:testGroup"` - `server.address`: `"zookeeper://127.0.0.1:2181/com.example.HelloService:1.0.0:testGroup"` - `server.port`: not set - Given a consumer that discovers providers via Nacos for `com.example.HelloService` with `group=gray` (no version), expected attributes: - Service-discovery target: `"nacos://127.0.0.1:8848/com.example.HelloService::gray"` - `server.address`: `"nacos://127.0.0.1:8848/com.example.HelloService::gray"` - `server.port`: not set When the address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the IP address provided. **[6] `server.port`:** If `server.address` is set and a port is specified in the direct provider target URL. **[7] `server.port`:** See the `server.address` for details on parsing the target string. [DocumentStatus]: /docs/specs/otel/document-status/ [MetricRecommended]: /docs/specs/semconv/general/signal-requirement-level.md#recommended