Fixes open-telemetry#1016: Define RPC semantic conventions for metrics.

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)
+<!-- endsemconv -->
+
+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/