(chore) Remove common attributes from RPC documentation in favor of f… (#960)
This commit is contained in:
Josh Suereth
GitHub
parent
a28fa9e62e
commit
7c09a909b5
|
|
@ -15,8 +15,7 @@ This document defines how to describe remote procedure calls
|
|||
|
||||
- [Common remote procedure call conventions](#common-remote-procedure-call-conventions)
|
||||
- [Span name](#span-name)
|
||||
- [Common attributes](#common-attributes)
|
||||
- [Service name](#service-name)
|
||||
- [Service name](#service-name)
|
||||
- [Client attributes](#client-attributes)
|
||||
- [Server attributes](#server-attributes)
|
||||
- [Events](#events)
|
||||
|
|
@ -79,14 +78,30 @@ Examples of span names:
|
|||
`MyServiceReference.ICalculator/Add` reported by the client for .NET WCF calls
|
||||
- `MyServiceWithNoPackage/theMethod`
|
||||
|
||||
### Common attributes
|
||||
### Service name
|
||||
|
||||
<!-- semconv rpc(full) -->
|
||||
On the server process receiving and handling the remote procedure call, the service name provided in `rpc.service` does not necessarily have to match the [`service.name`][] resource attribute.
|
||||
One process can expose multiple RPC endpoints and thus have multiple RPC service names. From a deployment perspective, as expressed by the `service.*` resource attributes, it will be treated as one deployed service with one `service.name`.
|
||||
Likewise, on clients sending RPC requests to a server, the service name provided in `rpc.service` does not have to match the [`peer.service`][] span attribute.
|
||||
|
||||
As an example, given a process deployed as `QuoteService`, this would be the name that goes into the `service.name` resource attribute which applies to the entire process.
|
||||
This process could expose two RPC endpoints, one called `CurrencyQuotes` (= `rpc.service`) with a method called `getMeanRate` (= `rpc.method`) and the other endpoint called `StockQuotes` (= `rpc.service`) with two methods `getCurrentBid` and `getLastClose` (= `rpc.method`).
|
||||
In this example, spans representing client request should have their `peer.service` attribute set to `QuoteService` as well to match the server's `service.name` resource attribute.
|
||||
Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service name.
|
||||
|
||||
[`service.name`]: /docs/resource/README.md#service
|
||||
[`peer.service`]: /docs/general/attributes.md#general-remote-service-attributes
|
||||
|
||||
### Client attributes
|
||||
|
||||
<!-- semconv rpc.client(full) -->
|
||||
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|
||||
|---|---|---|---|---|---|
|
||||
| [`rpc.system`](../attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | `Required` |  |
|
||||
| [`server.address`](../attributes-registry/server.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` |  |
|
||||
| [`server.port`](../attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | `Conditionally Required` [3] |  |
|
||||
| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` If `network.peer.address` is set. |  |
|
||||
| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [4] | `tcp`; `udp` | `Recommended` |  |
|
||||
| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [5] | `ipv4`; `ipv6` | `Recommended` |  |
|
||||
| [`rpc.method`](../attributes-registry/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [6] | `exampleMethod` | `Recommended` |  |
|
||||
|
|
@ -137,52 +152,70 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
|
|||
| `ipv6` | IPv6 |  |
|
||||
<!-- endsemconv -->
|
||||
|
||||
#### Service name
|
||||
|
||||
On the server process receiving and handling the remote procedure call, the service name provided in `rpc.service` does not necessarily have to match the [`service.name`][] resource attribute.
|
||||
One process can expose multiple RPC endpoints and thus have multiple RPC service names. From a deployment perspective, as expressed by the `service.*` resource attributes, it will be treated as one deployed service with one `service.name`.
|
||||
Likewise, on clients sending RPC requests to a server, the service name provided in `rpc.service` does not have to match the [`peer.service`][] span attribute.
|
||||
|
||||
As an example, given a process deployed as `QuoteService`, this would be the name that goes into the `service.name` resource attribute which applies to the entire process.
|
||||
This process could expose two RPC endpoints, one called `CurrencyQuotes` (= `rpc.service`) with a method called `getMeanRate` (= `rpc.method`) and the other endpoint called `StockQuotes` (= `rpc.service`) with two methods `getCurrentBid` and `getLastClose` (= `rpc.method`).
|
||||
In this example, spans representing client request should have their `peer.service` attribute set to `QuoteService` as well to match the server's `service.name` resource attribute.
|
||||
Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service name.
|
||||
|
||||
[`service.name`]: /docs/resource/README.md#service
|
||||
[`peer.service`]: /docs/general/attributes.md#general-remote-service-attributes
|
||||
|
||||
### Client attributes
|
||||
|
||||
<!-- semconv rpc.client -->
|
||||
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|
||||
|---|---|---|---|---|---|
|
||||
| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` If `network.peer.address` is set. |  |
|
||||
<!-- endsemconv -->
|
||||
|
||||
### Server attributes
|
||||
|
||||
<!-- semconv rpc.server -->
|
||||
<!-- semconv rpc.server(full) -->
|
||||
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|
||||
|---|---|---|---|---|---|
|
||||
| [`client.address`](../attributes-registry/client.md) | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
| [`client.port`](../attributes-registry/client.md) | int | Client port number. [2] | `65123` | `Recommended` |  |
|
||||
| [`rpc.system`](../attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | `Required` |  |
|
||||
| [`server.address`](../attributes-registry/server.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Required` |  |
|
||||
| [`server.port`](../attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | `Conditionally Required` [3] |  |
|
||||
| [`client.address`](../attributes-registry/client.md) | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
| [`client.port`](../attributes-registry/client.md) | int | Client port number. [5] | `65123` | `Recommended` |  |
|
||||
| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` If `network.peer.address` is set. |  |
|
||||
| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` | `Recommended` |  |
|
||||
| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | `Recommended` |  |
|
||||
| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [6] | `tcp`; `udp` | `Recommended` |  |
|
||||
| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [7] | `ipv4`; `ipv6` | `Recommended` |  |
|
||||
| [`rpc.method`](../attributes-registry/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [8] | `exampleMethod` | `Recommended` |  |
|
||||
| [`rpc.service`](../attributes-registry/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [9] | `myservice.EchoService` | `Recommended` |  |
|
||||
|
||||
**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available.
|
||||
**[1]:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component.
|
||||
|
||||
**[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available.
|
||||
**[2]:** 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.
|
||||
|
||||
**[3]:** The value SHOULD be normalized to lowercase.
|
||||
**[3]:** if the port is supported by the network transport used for communication.
|
||||
|
||||
**[4]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available.
|
||||
|
||||
**[5]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available.
|
||||
|
||||
**[6]:** The value SHOULD be normalized to lowercase.
|
||||
|
||||
Consider always setting the transport when setting a port number, since
|
||||
a port number is ambiguous without knowing the transport. For example
|
||||
different processes could be listening on TCP port 12345 and UDP port 12345.
|
||||
|
||||
**[4]:** The value SHOULD be normalized to lowercase.
|
||||
**[7]:** The value SHOULD be normalized to lowercase.
|
||||
|
||||
**[8]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
|
||||
|
||||
**[9]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
|
||||
|
||||
`rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
|
||||
|
||||
| Value | Description | Stability |
|
||||
|---|---|---|
|
||||
| `grpc` | gRPC |  |
|
||||
| `java_rmi` | Java RMI |  |
|
||||
| `dotnet_wcf` | .NET WCF |  |
|
||||
| `apache_dubbo` | Apache Dubbo |  |
|
||||
| `connect_rpc` | Connect RPC |  |
|
||||
|
||||
`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
|
||||
|
||||
| Value | Description | Stability |
|
||||
|---|---|---|
|
||||
| `tcp` | TCP |  |
|
||||
| `udp` | UDP |  |
|
||||
| `pipe` | Named or anonymous pipe. |  |
|
||||
| `unix` | Unix domain socket |  |
|
||||
|
||||
`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
|
||||
|
||||
| Value | Description | Stability |
|
||||
|---|---|---|
|
||||
| `ipv4` | IPv4 |  |
|
||||
| `ipv6` | IPv6 |  |
|
||||
<!-- endsemconv -->
|
||||
|
||||
### Events
|
||||
|
|
|
|||
Loading…
Reference in New Issue