diff --git a/CHANGELOG.md b/CHANGELOG.md index 58cd0428856..8e64dd46573 100644 --- 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 index a77966b4362..7c326184a96 100644 --- 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 -- [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) -## 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