Skip to content

Commit

Permalink
Generate RPC metrics from YAML (open-telemetry#93)
Browse files Browse the repository at this point in the history
  • Loading branch information
joaopgrassi authored and rapphil committed Aug 14, 2023
1 parent 6561f68 commit a491f82
Show file tree
Hide file tree
Showing 2 changed files with 234 additions and 18 deletions.
137 changes: 119 additions & 18 deletions docs/rpc/rpc-metrics.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,17 @@ metrics can be filtered for finer grain analysis.

- [Metric instruments](#metric-instruments)
* [RPC Server](#rpc-server)
+ [Metric: `rpc.server.duration`](#metric-rpcserverduration)
+ [Metric: `rpc.server.request.size`](#metric-rpcserverrequestsize)
+ [Metric: `rpc.server.response.size`](#metric-rpcserverresponsesize)
+ [Metric: `rpc.server.requests_per_rpc`](#metric-rpcserverrequests_per_rpc)
+ [Metric: `rpc.server.responses_per_rpc`](#metric-rpcserverresponses_per_rpc)
* [RPC Client](#rpc-client)
+ [Metric: `rpc.client.duration`](#metric-rpcclientduration)
+ [Metric: `rpc.client.request.size`](#metric-rpcclientrequestsize)
+ [Metric: `rpc.client.response.size`](#metric-rpcclientresponsesize)
+ [Metric: `rpc.client.requests_per_rpc`](#metric-rpcclientrequests_per_rpc)
+ [Metric: `rpc.client.responses_per_rpc`](#metric-rpcclientresponses_per_rpc)
- [Attributes](#attributes)
* [Service name](#service-name)
- [Semantic Conventions for specific RPC technologies](#semantic-conventions-for-specific-rpc-technologies)
Expand Down Expand Up @@ -59,28 +69,118 @@ MUST be of the specified type and units.

### RPC Server

Below is a table of RPC server metric instruments.
Below is a list of RPC server metric instruments.

| Name | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | Status | Streaming |
|------|------------|------|-------------------------------------------|-------------|--------|-----------|
| `rpc.server.duration` | Histogram | milliseconds | `ms` | measures duration of inbound RPC | Recommended | N/A. While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. |
| `rpc.server.request.size` | Histogram | Bytes | `By` | measures size of RPC request messages (uncompressed) | Optional | Recorded per message in a streaming batch |
| `rpc.server.response.size` | Histogram | Bytes | `By` | measures size of RPC response messages (uncompressed) | Optional | Recorded per response in a streaming batch |
| `rpc.server.requests_per_rpc` | Histogram | count | `{count}` | measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs | Optional | Required |
| `rpc.server.responses_per_rpc` | Histogram | count | `{count}` | measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs | Optional | Required |
#### Metric: `rpc.server.duration`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.rpc.server.duration(metric_table) -->
| Name | Instrument Type | Unit (UCUM) | Description |
| -------- | --------------- | ----------- | -------------- |
| `rpc.server.duration` | Histogram | `ms` | Measures the duration of inbound RPC. **Streaming**: N/A. [1] |

**[1]:** While streaming RPCs may record this metric as start-of-batch
to end-of-batch, it's hard to interpret in practice.
<!-- endsemconv -->

#### Metric: `rpc.server.request.size`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.rpc.server.request.size(metric_table) -->
| Name | Instrument Type | Unit (UCUM) | Description |
| -------- | --------------- | ----------- | -------------- |
| `rpc.server.request.size` | Histogram | `By` | Measures the size of RPC request messages (uncompressed). **Streaming**: Recorded per message in a streaming batch |
<!-- endsemconv -->

#### Metric: `rpc.server.response.size`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.rpc.server.response.size(metric_table) -->
| Name | Instrument Type | Unit (UCUM) | Description |
| -------- | --------------- | ----------- | -------------- |
| `rpc.server.response.size` | Histogram | `By` | Measures the size of RPC response messages (uncompressed). **Streaming**: Recorded per response in a streaming batch |
<!-- endsemconv -->

#### Metric: `rpc.server.requests_per_rpc`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.rpc.server.requests_per_rpc(metric_table) -->
| Name | Instrument Type | Unit (UCUM) | Description |
| -------- | --------------- | ----------- | -------------- |
| `rpc.server.requests_per_rpc` | Histogram | `{count}` | Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs. **Streaming**: This metric is required for server and client streaming RPCs |
<!-- endsemconv -->

#### Metric: `rpc.server.responses_per_rpc`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.rpc.server.responses_per_rpc(metric_table) -->
| Name | Instrument Type | Unit (UCUM) | Description |
| -------- | --------------- | ----------- | -------------- |
| `rpc.server.responses_per_rpc` | Histogram | `{count}` | Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs. **Streaming**: This metric is required for server and client streaming RPCs |
<!-- endsemconv -->

### RPC Client

Below is a table of RPC client metric instruments. These apply to traditional
RPC usage, not streaming RPCs.
Below is a list of RPC client metric instruments.
These apply to traditional RPC usage, not streaming RPCs.

| Name | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | Status | Streaming |
|------|------------|------|-------------------------------------------|-------------|--------|-----------|
| `rpc.client.duration` | Histogram | milliseconds | `ms` | measures duration of outbound RPC | Recommended | N/A. While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. |
| `rpc.client.request.size` | Histogram | Bytes | `By` | measures size of RPC request messages (uncompressed) | Optional | Recorded per message in a streaming batch |
| `rpc.client.response.size` | Histogram | Bytes | `By` | measures size of RPC response messages (uncompressed) | Optional | Recorded per message in a streaming batch |
| `rpc.client.requests_per_rpc` | Histogram | count | `{count}` | measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs | Optional | Required |
| `rpc.client.responses_per_rpc` | Histogram | count | `{count}` | measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs | Optional | Required |
#### Metric: `rpc.client.duration`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.rpc.client.duration(metric_table) -->
| Name | Instrument Type | Unit (UCUM) | Description |
| -------- | --------------- | ----------- | -------------- |
| `rpc.client.duration` | Histogram | `ms` | Measures the duration of outbound RPC **Streaming**: N/A. [1] |

**[1]:** While streaming RPCs may record this metric as start-of-batch
to end-of-batch, it's hard to interpret in practice.
<!-- endsemconv -->

#### Metric: `rpc.client.request.size`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.rpc.client.request.size(metric_table) -->
| Name | Instrument Type | Unit (UCUM) | Description |
| -------- | --------------- | ----------- | -------------- |
| `rpc.client.request.size` | Histogram | `By` | Measures the size of RPC request messages (uncompressed). **Streaming**: Recorded per message in a streaming batch |
<!-- endsemconv -->

#### Metric: `rpc.client.response.size`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.rpc.client.response.size(metric_table) -->
| Name | Instrument Type | Unit (UCUM) | Description |
| -------- | --------------- | ----------- | -------------- |
| `rpc.client.response.size` | Histogram | `By` | Measures the size of RPC response messages (uncompressed). **Streaming**: Recorded per response in a streaming batch |
<!-- endsemconv -->

#### Metric: `rpc.client.requests_per_rpc`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.rpc.client.requests_per_rpc(metric_table) -->
| Name | Instrument Type | Unit (UCUM) | Description |
| -------- | --------------- | ----------- | -------------- |
| `rpc.client.requests_per_rpc` | Histogram | `{count}` | Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs. **Streaming**: This metric is required for server and client streaming RPCs |
<!-- endsemconv -->

#### Metric: `rpc.client.responses_per_rpc`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.rpc.client.responses_per_rpc(metric_table) -->
| Name | Instrument Type | Unit (UCUM) | Description |
| -------- | --------------- | ----------- | -------------- |
| `rpc.client.responses_per_rpc` | Histogram | `{count}` | Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs. **Streaming**: This metric is required for server and client streaming RPCs |
<!-- endsemconv -->

## Attributes

Expand Down Expand Up @@ -146,4 +246,5 @@ More specific Semantic Conventions are defined for the following RPC technologie
* [gRPC](grpc.md): Semantic Conventions for *gRPC*.
* [JSON-RPC](json-rpc.md): Semantic Conventions for *JSON-RPC*.

[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.22.0/specification/document-status.md
[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.22.0/specification/metrics/metric-requirement-level.md#recommended
115 changes: 115 additions & 0 deletions model/metrics/rpc-metrics.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
groups:
# TODO: Should we list the attributes on each metric
# OR leave a single table like it is today? Since all attributes are applied
# to all metrics, the repetition of them bloats the page
- id: attributes.metrics.rpc
type: attribute_group
brief: "Describes RPC metric attributes."
attributes:
- ref: rpc.system
- ref: rpc.service
- ref: rpc.method
- ref: network.transport
- ref: network.type
- ref: server.address
- ref: server.port
- ref: server.socket.address
- ref: server.socket.port

# RPC Server metrics
- id: metric.rpc.server.duration
type: metric
metric_name: rpc.server.duration
brief: >
Measures the duration of inbound RPC.
**Streaming**: N/A.
instrument: histogram
unit: "ms"
note: |
While streaming RPCs may record this metric as start-of-batch
to end-of-batch, it's hard to interpret in practice.
- id: metric.rpc.server.request.size
type: metric
metric_name: rpc.server.request.size
brief: >
Measures the size of RPC request messages (uncompressed).
**Streaming**: Recorded per message in a streaming batch
instrument: histogram
unit: "By"

- id: metric.rpc.server.response.size
type: metric
metric_name: rpc.server.response.size
brief: >
Measures the size of RPC response messages (uncompressed).
**Streaming**: Recorded per response in a streaming batch
instrument: histogram
unit: "By"

- id: metric.rpc.server.requests_per_rpc
type: metric
metric_name: rpc.server.requests_per_rpc
brief: >
Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs.
**Streaming**: This metric is required for server and client streaming RPCs
instrument: histogram
unit: "{count}"

- id: metric.rpc.server.responses_per_rpc
type: metric
metric_name: rpc.server.responses_per_rpc
brief: >
Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs.
**Streaming**: This metric is required for server and client streaming RPCs
instrument: histogram
unit: "{count}"

# RPC Client metrics
- id: metric.rpc.client.duration
type: metric
metric_name: rpc.client.duration
brief: >
Measures the duration of outbound RPC
**Streaming**: N/A.
instrument: histogram
unit: "ms"
note: |
While streaming RPCs may record this metric as start-of-batch
to end-of-batch, it's hard to interpret in practice.
- id: metric.rpc.client.request.size
type: metric
metric_name: rpc.client.request.size
brief: >
Measures the size of RPC request messages (uncompressed).
**Streaming**: Recorded per message in a streaming batch
instrument: histogram
unit: "By"

- id: metric.rpc.client.response.size
type: metric
metric_name: rpc.client.response.size
brief: >
Measures the size of RPC response messages (uncompressed).
**Streaming**: Recorded per response in a streaming batch
instrument: histogram
unit: "By"

- id: metric.rpc.client.requests_per_rpc
type: metric
metric_name: rpc.client.requests_per_rpc
brief: >
Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs.
**Streaming**: This metric is required for server and client streaming RPCs
instrument: histogram
unit: "{count}"

- id: metric.rpc.client.responses_per_rpc
type: metric
metric_name: rpc.client.responses_per_rpc
brief: >
Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs.
**Streaming**: This metric is required for server and client streaming RPCs
instrument: histogram
unit: "{count}"

0 comments on commit a491f82

Please sign in to comment.