forked from open-telemetry/opentelemetry-specification
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Fixes open-telemetry#1016: Define RPC semantic conventions for metrics.
- Loading branch information
Showing
1 changed file
with
77 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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/ |