Semantic conventions for Connect RPC
Status: Development
The Semantic Conventions for Connect extend and override the RPC Semantic Conventions.
Spans
Client
Status:
This span represents an outgoing Remote Procedure Call (RPC).
Span name: refer to the Span Name section.
Span kind MUST be CLIENT.
Span status: refer to the Recording Errors document for details on how to record span status.
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
rpc.system.name |  | Required | string | The Remote Procedure Call (RPC) system. [1] | connectrpc |
server.address | | Required | string | The domain name or address of the Connect RPC server. [2] | example.com; 10.1.2.80; /tmp/my.sock |
error.type | | Conditionally Required If and only if the operation failed. | string | Describes a class of error the operation ended with. [3] | DEADLINE_EXCEEDED; java.net.UnknownHostException; -32602 |
rpc.method | | 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 | | 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 |
rpc.status_code | | Conditionally Required if available. | string | The error code of the Connect response. [5] | OK; DEADLINE_EXCEEDED; -32602 |
server.port | | Conditionally Required if available. | int | Server port number. [6] | 80; 8080; 443 |
network.peer.address | | Recommended | string | Peer address of the network connection - IP address or UNIX domain socket name. [7] | 10.1.2.80; /tmp/my.sock |
network.peer.port | | Recommended If network.peer.address is set. | int | Peer port number of the network connection. | 65123 |
rpc.request.header.<key> |  | Opt-In | string[] | Connect RPC request headers. [8] | ["1.2.3.4", "1.2.3.5"] |
rpc.response.header.<key> | | Opt-In | string[] | Connect RPC response headers, sent before the response payload. [9] | ["attribute_value"] |
rpc.response.trailer.<key> | | Opt-In | string[] | Connect RPC response trailers, sent after the response payload. [10] | ["attribute_value"] |
[1] rpc.system.name: MUST be set to connectrpc.
[2] server.address: When an IP address is provided instead of a domain name, instrumentations SHOULD NOT do a reverse DNS lookup to obtain DNS name and SHOULD set server.address to the provided IP address.
[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. Check system-specific conventions
for the details on which values of rpc.status_code 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] rpc.status_code: All status codes except OK SHOULD be considered errors.
Instrumentations MAY use additional context or provide configuration options to customize which status codes are considered errors.
[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.
[7] network.peer.address: If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used.
[8] rpc.request.header.<key>: <key> 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.
Connect RPC libraries provide APIs to retrieve headers and trailers, but the way they are transmitted over the wire depends on the underlying protocol (Connect, gRPC, or gRPC-Web). Instrumentations SHOULD obtain them from the corresponding Connect RPC library API.
Values under keys ending in -bin are binary and SHOULD be
base64-encoded when recorded.
[9] rpc.response.header.<key>: <key> 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 ["attribute_value"] SHOULD be recorded
as the rpc.response.header.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 headers.
Connect RPC libraries provide APIs to retrieve headers and trailers, but the way they are transmitted over the wire depends on the underlying protocol (Connect, gRPC, or gRPC-Web). Instrumentations SHOULD obtain them from the corresponding Connect RPC library API.
Values under keys ending in -bin are binary and SHOULD be
base64-encoded when recorded.
[10] rpc.response.trailer.<key>: <key> 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.
Connect RPC libraries provide APIs to retrieve headers and trailers, but the way they are transmitted over the wire depends on the underlying protocol (Connect, gRPC, or gRPC-Web). Instrumentations SHOULD obtain them from the corresponding Connect RPC library API and SHOULD NOT rely on the underlying protocol details.
Values under keys ending in -bin are binary and SHOULD be
base64-encoded when recorded.
The following attributes can be important for making sampling decisions and SHOULD be provided at span creation time (if provided at all):
Server
Status:
This span represents an incoming Remote Procedure Call (RPC).
Span name: refer to the Span Name section.
Span kind MUST be SERVER.
Span status: refer to the Recording Errors document for details on how to record span status.
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
rpc.system.name | | Required | string | The Remote Procedure Call (RPC) system. [1] | connectrpc |
error.type | | Conditionally Required If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | DEADLINE_EXCEEDED; java.net.UnknownHostException; -32602 |
rpc.method | | Conditionally Required if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | com.example.ExampleService/exampleMethod; EchoService/Echo; _OTHER |
rpc.method_original | | 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 |
rpc.status_code | | Conditionally Required if available. | string | The error code of the Connect response. [4] | OK; DEADLINE_EXCEEDED; -32602 |
server.port | | Conditionally Required if applicable and if server.address is set. | int | Server port number. [5] | 80; 8080; 443 |
network.peer.address | | 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 | | Recommended If network.peer.address is set. | int | Peer port number of the network connection. | 65123 |
server.address | | 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.<key> | | Opt-In | string[] | Connect RPC request headers. [8] | ["1.2.3.4", "1.2.3.5"] |
rpc.response.header.<key> | | Opt-In | string[] | Connect RPC response headers, sent before the response payload. [9] | ["attribute_value"] |
rpc.response.trailer.<key> | | Opt-In | string[] | Connect RPC response trailers, sent after the response payload. [10] | ["attribute_value"] |
[1] rpc.system.name: MUST be set to connectrpc.
[2] 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. Check system-specific conventions
for the details on which values of rpc.status_code 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.
[3] 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.
[4] rpc.status_code: The following error codes SHOULD be considered errors:
unknowndeadline_exceededunimplementedinternalunavailabledata_loss
Instrumentations MAY use additional context or provide configuration options to customize which error codes are considered errors.
[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.<key>: <key> 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.
Connect RPC libraries provide APIs to retrieve headers and trailers, but the way they are transmitted over the wire depends on the underlying protocol (Connect, gRPC, or gRPC-Web). Instrumentations SHOULD obtain them from the corresponding Connect RPC library API.
Values under keys ending in -bin are binary and SHOULD be
base64-encoded when recorded.
[9] rpc.response.header.<key>: <key> 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 ["attribute_value"] SHOULD be recorded
as the rpc.response.header.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 headers.
Connect RPC libraries provide APIs to retrieve headers and trailers, but the way they are transmitted over the wire depends on the underlying protocol (Connect, gRPC, or gRPC-Web). Instrumentations SHOULD obtain them from the corresponding Connect RPC library API.
Values under keys ending in -bin are binary and SHOULD be
base64-encoded when recorded.
[10] rpc.response.trailer.<key>: <key> 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.
Connect RPC libraries provide APIs to retrieve headers and trailers, but the way they are transmitted over the wire depends on the underlying protocol (Connect, gRPC, or gRPC-Web). Instrumentations SHOULD obtain them from the corresponding Connect RPC library API and SHOULD NOT rely on the underlying protocol details.
Values under keys ending in -bin are binary and SHOULD be
base64-encoded when recorded.
The following attributes can be important for making sampling decisions and SHOULD be provided at span creation time (if provided at all):
Metrics
Connect RPC instrumentations SHOULD collect metrics according to the general Semantic Conventions for RPC Metrics.
rpc.system.name MUST be set to "connectrpc".
Feedback
Was this page helpful?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!