diff --git a/CHANGELOG.md b/CHANGELOG.md index d730854571b..9dc0a47c52d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ the release. * Configuration should be stored not per Tracer but in the TracerProvider. * Active spans are not per Tracer. - Add semantic conventions for process resource. +- Add peer.service to provide a user-configured name for a remote service ## v0.5.0 (06-02-2020) diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 7c326184a96..62df39f334e 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -65,14 +65,19 @@ Furthermore, setting [net.transport][] is required for non-IP connection like na #### 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`. +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. [network attributes]: span-general.md#general-network-connection-attributes [net.transport]: span-general.md#nettransport-attribute -[`service.name` resource attribute]: ../../resource/semantic_conventions/README.md#service +[`service.name`]: ../../resource/semantic_conventions/README.md#service +[`peer.service`]: span-general.md#general-remote-service-attributes ### Distinction from HTTP spans diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index 48db19a55d9..618b725a63b 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -9,6 +9,9 @@ Particular operations may refer to or require some of these attributes. - [General network connection attributes](#general-network-connection-attributes) + * [`net.transport` attribute](#nettransport-attribute) + * [`net.*.name` attributes](#netname-attributes) +- [General remote service attributes](#general-remote-service-attributes) - [General identity attributes](#general-identity-attributes) @@ -67,6 +70,20 @@ If `net.transport` is `"unix"` or `"pipe"`, the absolute path to the file repres If there is no such file (e.g., anonymous pipe), the name should explicitly be set to the empty string to distinguish it from the case where the name is just unknown or not covered by the instrumentation. +## General remote service attributes + +This attribute may be used for any operation that accesses some remote service. +Users can define what the name of a service is based on their particular semantics in their distributed system. +Instrumentations SHOULD provide a way for users to configure this name. + +| Attribute name | Notes and examples | +| :-------------- | :-------------------------------------------------------------------------------- | +| `peer.service` | The [`service.name`](../../resource/semantic_conventions/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. | + +Examples of `peer.service` that users may specify: +- A Redis cache of auth tokens as `peer.service="AuthTokenCache"`. +- A gRPC service `rpc.service="io.opentelemetry.AuthService"` may be hosted in both a gateway, `peer.service="ExternalApiService"` and a backend, `peer.service="AuthService"`. + ## General identity attributes These attributes may be used for any operation with an authenticated and/or authorized enduser.