diff --git a/specification/metrics/semantic_conventions/rpc.md b/specification/metrics/semantic_conventions/rpc.md new file mode 100644 index 00000000000..141b53e4cba --- /dev/null +++ b/specification/metrics/semantic_conventions/rpc.md @@ -0,0 +1,77 @@ +# General + +The conventions described in this section are RPC specific. When RPC operations +occur, metric events about those operations will be generated and reported to +provide insight into those operations. By adding RPC labels to metric events +it allows for finely tuned filtering. + +**Disclaimer:** THese are initial RPC metric instruments and labels but more may +be added in the future. + +## Metric instruments + +The following metric instruments MUST be used to describe RPC operations. They +MUST be of the specified type and units. + +*Note: RPC server and client metrics are split to allow correlation across client/server boundaries, e.g. Lining up an RPC method latency to determine if the server is responsible for latency the client is seeing.* + +### RPC Server + +Below is a table of RPC server metric instruments. + +| Name | Instrument | Units | Description | Status | +|----------------------------|---------------|--------------|-------------|--------| +| `rpc.server.duration` | ValueRecorder | milliseconds | measures duration of inbound RPC | Recommended | +| `rpc.server.request.size` | ValueRecorder | bytes | measures size of RPC request messages | Optional | +| `rpc.server.response.size` | ValueRecorder | bytes | measures size of RPC response messages | Optional | + +### RPC Client + +Below is a table of RPC client metric instruments. + +| Name | Instrument | Units | Description | Status | +|----------------------------|---------------|--------------|-------------|--------| +| `rpc.client.duration` | ValueRecorder | milliseconds | measures duration of outbound RPC | Recommended | +| `rpc.client.request.size` | ValueRecorder | bytes | measures size of RPC request messages | Optional | +| `rpc.client.response.size` | ValueRecorder | bytes | measures size of RPC response messages | Optional | + +## Labels +Below is a table of labels that SHOULD be included on metric events and whether +or not they should be on the server, client or both. + + +| Name | Type | Status | Notes and examples | +|-----------------|--------|-------------|--------------------| +| `rpc.system` | both | Required | A string identifying the remoting system, e.g. `grpc`, `java_rmi`, `wcf` | +| `rpc.service` | both | Recommended | The full name of the service being called, including its package name if applicable. | `myservice.EchoService` | +| `rpc.method` | both | Recommended | The name of the method being called, e.g. `exampleMethod` | +| `net.peer.ip` | both | *See below | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6). e.g. `127.0.0.1` | +| `net.peer.name` | both | *See below | Remote hastname or similar, e.g. `example.com` | +| `net.peer.port` | client | *See below | Remote port number, e.g. `80`, `8080`, `24050` | +| `net.transport` | both | *See below | Transport protocol used, e.g. `IP.TCP` | + +**Additional attribute requirements:** At least one of the following sets of attributes is required: + +* [`net.peer.ip`](span-general.md) +* [`net.peer.name`](span-general.md) + + +For client-side metrics `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`. + +[`service.name`]: ../../resource/semantic_conventions/README.md#service + + +## 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/ \ No newline at end of file