Add peer.service semantic convention to indicate the name of a target… (open-telemetry#652)

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

* Apply suggestions from code review

Co-authored-by: Armin Ruech <[email protected]>

* Simplify

* Remove fallback wording

* Needs to be configured using instrumentation

* CHANGELOG

* Clarify relationship with rpc.service and peer.service and some examples

* Clarify example

* Move peer.service / rpc.service relationship explanation to rpc doc.

* Apply suggestions from code review

Co-authored-by: Christian Neumüller <[email protected]>

* Update specification/trace/semantic_conventions/span-general.md

Co-authored-by: Christian Neumüller <[email protected]>

* Cleanup

* Tweak

* Update specification/trace/semantic_conventions/rpc.md

Co-authored-by: Armin Ruech <[email protected]>

* Update CHANGELOG.md

Co-authored-by: Armin Ruech <[email protected]>

* Apply suggestions from code review

Co-authored-by: Armin Ruech <[email protected]>

* Update specification/trace/semantic_conventions/span-general.md

Co-authored-by: Armin Ruech <[email protected]>

* TOC

* Apply suggestions from code review

Co-authored-by: Armin Ruech <[email protected]>

Co-authored-by: Armin Ruech <[email protected]>
Co-authored-by: Christian Neumüller <[email protected]>

Author: 3 people

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)
 

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

@@ -9,6 +9,9 @@ Particular operations may refer to or require some of these attributes.
 <!-- toc -->
 
 - [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)
 
 <!-- tocstop -->
@@ -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.