Extend semantic conventions for RPC and allow non-gRPC calls (open-te…

…lemetry#604) * Generalize RPC semantic conventions to allow non-gRPC spans * Add method name to attributes * Require specifying `net.transport` for non-IP connections * Do not require providing the port when it's not available * Add package name to rpc.service and make it optional when not applicable or unknown * Add note and example distinguishing the service.name resource attribute from rpc.service * Distinguish RPC spans from HTTP spans * Improve wording Co-authored-by: Christian Neumüller <christian+github@neumueller.me> * Improve wording * Improve wording even more Co-authored-by: Christian Neumüller <christian+github@neumueller.me> * Clarify span name format * Update changelog * rpc.method: required -> recommended * rpc.service: required -> recommended Co-authored-by: Christian Neumüller <christian+github@neumueller.me>
carlosalberto · Jun 17, 2020 · b257dc5 · b257dc5
1 parent 91c07c9
commit b257dc5
Show file tree

Hide file tree

Showing 2 changed files with 60 additions and 14 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,7 @@ the release.
 
 ## Unreleased
 
+- Extend semantic conventions for RPC and allow non-gRPC calls ([#604](https://github.com/open-telemetry/opentelemetry-specification/pull/604))
 - Add span attribute to indicate cold starts of Function as a Service executions ([#650](https://github.com/open-telemetry/opentelemetry-specification/pull/650))
 - Added conventions for naming of exporter packages
 - Clarify Tracer vs TracerProvider in tracing API and SDK spec. Most importantly:

diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md
@@ -7,41 +7,86 @@ This document defines how to describe remote procedure calls
 
 <!-- toc -->
 
-- [gRPC](#grpc)
+- [Common remote procedure call conventions](#common-remote-procedure-call-conventions)
+  * [Span name](#span-name)
   * [Attributes](#attributes)
+    + [Service name](#service-name)
+  * [Distinction from HTTP spans](#distinction-from-http-spans)
+- [gRPC](#grpc)
   * [Status](#status)
   * [Events](#events)
 
 <!-- tocstop -->
 
-## gRPC
+## Common remote procedure call conventions
+
+A remote procedure calls is described by two separate spans, one on the client-side and one on the server-side.
+
+For outgoing requests, the `SpanKind` MUST be set to `CLIENT` and for incoming requests to `SERVER`.
 
-Implementations MUST create a span, when the gRPC call starts, one for
-client-side and one for server-side. Outgoing requests should be a span `kind`
-of `CLIENT` and incoming requests should be a span `kind` of `SERVER`.
+Remote procedure calls can only be represented with these semantic conventions, when the names of the called service and method are known and available.
 
-Span `name` MUST be full gRPC method name formatted as:
+### Span name
+
+The _span name_ MUST be the full RPC method name formatted as:
 
 ```
 $package.$service/$method
 ```
 
-Examples of span name: `grpc.test.EchoService/Echo`.
+(where $service must not contain dots and $method must not contain slashes)
+
+If there is no package name or if it is unknown, the `$package.` part (including the period) is omitted.
+
+Examples of span names:
+
+- `grpc.test.EchoService/Echo`
+- `com.example.ExampleRmiService/exampleMethod`
+- `MyCalcService.Calculator/Add` reported by the server and  
+  `MyServiceReference.ICalculator/Add` reported by the client for .NET WCF calls
+- `MyServiceWithNoPackage/theMethod`
 
 ### Attributes
 
-| Attribute name | Notes and examples                                           | Required? |
-| -------------- | ------------------------------------------------------------ | --------- |
-| `rpc.service`  | The service name, must be equal to the $service part in the span name. | Yes |
-| `net.peer.ip`  | See [network attributes][]. | See below |
-| `net.peer.name`  | See [network attributes][]. | See below |
-| `net.peer.port`  | See [network attributes][]. | See below |
+| Attribute name |                          Notes and examples                            | Required? |
+| -------------- | ---------------------------------------------------------------------- | --------- |
+| `rpc.system`   | A string identifying the remoting system, e.g., `"grpc"`, `"java_rmi"` or `"wcf"`.       | Yes |
+| `rpc.service`  | The full name of the service being called, including its package name, if applicable.    | No, but recommended |
+| `rpc.method`   | The name of the method being called, must be equal to the $method part in the span name. | No, but recommended |
+| `net.peer.ip`   | See [network attributes][]. | See below |
+| `net.peer.name` | See [network attributes][]. | See below |
+| `net.peer.port` | See [network attributes][]. | See below |
+| `net.transport` | See [network attributes][]. | See below |
 
 At least one of [network attributes][] `net.peer.name` or `net.peer.ip` is required.
-For client-side spans `net.peer.port` is required (it describes the server port they are connecting to).
+For client-side spans `net.peer.port` is required if the connection is IP-based and the port is available (it describes the server port they are connecting to).
 For server-side spans `net.peer.port` is optional (it describes the port the client is connecting from).
+Furthermore, setting [net.transport][] is required for non-IP connection like named pipe bindings.
+
+#### 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`.
+
+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`).
 
 [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
+
+### Distinction from HTTP spans
+
+HTTP calls can generally be represented using just [HTTP spans](./http.md).
+If they address a particular remote service and method known to the caller, i.e., when it is a remote procedure call transported over HTTP, the `rpc.*` attributes might be added additionally on that span, or in a separate RPC span that is a parent of the transporting HTTP call.
+Note that _method_ in this context is about the called remote procedure and _not_ the HTTP verb (GET, POST, etc.).
+
+## gRPC
+
+For remote procedure calls via [gRPC][], additional conventions are described in this section.
+
+`rpc.system` MUST be set to `"grpc"`.
+
+[gRPC]: https://grpc.io/
 
 ### Status