Add peer.service semantic convention to indicate the name of a target…

CHANGELOG.md

@@ -15,6 +15,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)
 

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
 

specification/trace/semantic_conventions/span-general.md

@@ -67,6 +67,19 @@ 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
+
+These attributes 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.
+Instrumentation is expected to 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.