Skip to content
This repository was archived by the owner on Oct 3, 2023. It is now read-only.

Commit afbb088

Browse files
author
Bogdan Drutu
authored
Add specs for gRPC stats. (#78)
* Add specs for gRPC stats. * Add link in the readme.md * Respond to comments.
1 parent c3d6df5 commit afbb088

2 files changed

Lines changed: 127 additions & 1 deletion

File tree

‎stats/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,4 +15,5 @@ data aggregation.
1515
Prometheus, Stackdriver, SignalFx).
1616

1717
## Utils
18-
* [HTTP integration](HTTP.md): document about how to instrument http frameworks.
18+
* [HTTP integration](HTTP.md): document about how to instrument http frameworks.
19+
* [gRPC integration](gRPC.md): document about how to instrument gRPC framework.

‎stats/gRPC.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# gRPC Stats
2+
3+
Any particular library might provide only a subset of these measures/views/tags.
4+
Check the language-specific documentation for the list of supported values.
5+
6+
## Units
7+
8+
Units are encoded according to the case-sensitive abbreviations from the [Unified Code for Units of Measure](http://unitsofmeasure.org/ucum.html):
9+
10+
* Latencies are measures in float64 milliseconds, denoted "ms"
11+
* Sizes are measured in bytes, denoted "By"
12+
* Dimensionless values have unit "1"
13+
14+
Buckets for distributions in default views are as follows:
15+
16+
* Size in bytes: 0, 1024, 2048, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864, 268435456, 1073741824, 4294967296
17+
* Latency in ms: 0, 0.01, 0.05, 0.1, 0.3, 0.6, 0.8, 1, 2, 3, 4, 5, 6, 8, 10, 13, 16, 20, 25, 30, 40, 50, 65, 80, 100, 130, 160, 200, 250, 300, 400, 500, 650, 800, 1000, 2000, 5000, 10000, 20000, 50000, 100000
18+
* Counts (no unit): 0, 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768, 65536
19+
20+
## Client
21+
22+
### Measures
23+
24+
Client stats are recorded for each individual gRPC request. All measurements except `grpc.io/client/started_count` must be recorded at the end of each gRPC request.
25+
26+
| Measure name | Unit | Description |
27+
|--------------------------------------------|------|-----------------------------------------------------------------------------------------------|
28+
| grpc.io/client/started_count | 1 | Number of all client requests started. Records "1" at the beginning of each gRPC request. |
29+
| grpc.io/client/request_messages_count | 1 | Number of request messages sent in a gRPC request. Has value "1" for non-streaming RPCs. |
30+
| grpc.io/client/request_bytes | By | Total compressed bytes sent in total across all request messages in a gRPC request. |
31+
| grpc.io/client/uncompressed_request_bytes | By | Total uncompressed bytes sent in total across all request messages in a gRPC request. |
32+
| grpc.io/client/response_messages_count | 1 | Number of response messages received in a gRPC request. Has value "1" for non-streaming RPCs. |
33+
| grpc.io/client/response_bytes | By | Total compressed bytes received in total across all response messages in a gRPC request. |
34+
| grpc.io/client/uncompressed_response_bytes | By | Total uncompressed bytes received in total across all response messages in a gRPC request. |
35+
| grpc.io/client/latency | ms | Time between first byte of request sent to last byte of response received, or terminal error. |
36+
| grpc.io/client/server_latency | ms | Propagated from the server and should have the same value as "grpc.io/server/latency". |
37+
38+
### Tags
39+
40+
All client metrics should be tagged with the following. Some tags are not available for measurements recorded at the beginning of the gRPC request (e.g. `grpc.canonical_status`).
41+
42+
| Tag name | Description |
43+
|--------------------|---------------------------------------------------------------|
44+
| grpc.client_method | Full gRPC method name, including package, service and method. |
45+
| grpc.client_status | gRPC client status code. |
46+
47+
### Default views
48+
49+
The following set of views are considered minimum required to monitor client side performance:
50+
51+
| View name | Measure suffix | Aggregation | Tags suffix |
52+
|---------------------------------------------|-----------------------------|--------------|------------------------------|
53+
| grpc.io/client/started_count | started_count | count | client_method |
54+
| grpc.io/client/request_bytes | request_bytes | distribution | client_method |
55+
| grpc.io/client/response_bytes | response_bytes | distribution | client_method |
56+
| grpc.io/client/latency | latency | distribution | client_method |
57+
| grpc.io/client/finished_count | latency | count | client_method, client_status |
58+
59+
### Extra views
60+
61+
The following set of views are considered useful but not mandatory to monitor client side performance:
62+
63+
| View name | Measure suffix | Aggregation | Tags suffix |
64+
|---------------------------------------------|-----------------------------|--------------|------------------------------|
65+
| grpc.io/client/request_messages_count | request_messages_count | distribution | client_method |
66+
| grpc.io/client/uncompressed_request_bytes | uncompressed_request_bytes | distribution | client_method |
67+
| grpc.io/client/response_messages_count | response_messages_count | distribution | client_method |
68+
| grpc.io/client/uncompressed_response_bytes | uncompressed_response_bytes | distribution | client_method |
69+
| grpc.io/client/server_latency | server_latency | distribution | client_method |
70+
71+
## Server
72+
73+
Server stats are recorded for each individual gRPC request. All measurements except `grpc.io/server/started_count` must be recorded at the end of each gRPC request.
74+
75+
| Measure name | Unit | Description |
76+
|--------------------------------------------|------|-----------------------------------------------------------------------------------------------|
77+
| grpc.io/server/started_count | 1 | Number of all server requests started. Records "1" at the beginning of each gRPC request. |
78+
| grpc.io/server/request_messages_count | 1 | Number of request messages received in a gRPC request. Has value "1" for non-streaming RPCs. |
79+
| grpc.io/server/request_bytes | By | Total compressed bytes received in total across all request messages in a gRPC request. |
80+
| grpc.io/server/uncompressed_request_bytes | By | Total uncompressed bytes received in total across all request messages in a gRPC request. |
81+
| grpc.io/server/response_messages_count | 1 | Number of response messages sent in a gRPC request. Has value "1" for non-streaming RPCs. |
82+
| grpc.io/server/response_bytes | By | Total compressed bytes sent in total across all response messages in a gRPC request. |
83+
| grpc.io/server/uncompressed_response_bytes | By | Total uncompressed bytes sent in total across all response messages in a gRPC request. |
84+
| grpc.io/server/latency | ms | Time between first byte of request received to last byte of response sent, or terminal error. |
85+
86+
### Tags
87+
88+
All server metrics should be tagged with the following. Some tags are not available for measurements recorded at the beginning of the gRPC request (e.g. `grpc.canonical_status`).
89+
90+
| Tag name | Description |
91+
|--------------------|---------------------------------------------------------------|
92+
| grpc.server_method | Full gRPC method name, including package, service and method. |
93+
| grpc.server_status | gRPC server status code. |
94+
95+
### Default views
96+
97+
The following set of views are considered minimum required to monitor server side performance:
98+
99+
| View name | Measure suffix | Aggregation | Tags suffix |
100+
|---------------------------------------------|-----------------------------|--------------|------------------------------|
101+
| grpc.io/server/started_count | started_count | count | server_method |
102+
| grpc.io/server/request_bytes | request_bytes | distribution | server_method |
103+
| grpc.io/server/response_bytes | response_bytes | distribution | server_method |
104+
| grpc.io/server/latency | latency | distribution | server_method |
105+
| grpc.io/server/finished_count | latency | count | server_method, server_status |
106+
107+
### Extra views
108+
109+
The following set of views are considered useful but not mandatory to monitor server side performance:
110+
111+
| View name | Measure suffix | Aggregation | Tags suffix |
112+
|---------------------------------------------|-----------------------------|--------------|------------------------------|
113+
| grpc.io/server/request_messages_count | request_messages_count | distribution | server_method |
114+
| grpc.io/server/uncompressed_request_bytes | uncompressed_request_bytes | distribution | server_method |
115+
| grpc.io/server/response_messages_count | response_messages_count | distribution | server_method |
116+
| grpc.io/server/uncompressed_response_bytes | uncompressed_response_bytes | distribution | server_method |
117+
118+
## FAQ
119+
120+
### Why different tag name for server/client method?
121+
This way users can configure views to correlate incoming with outgoing requests. A view example:
122+
123+
| View name | Measure suffix | Aggregation | Tags suffix |
124+
|---------------------------------------------|-----------------------------|--------------|------------------------------|
125+
| grpc.io/client/latency_by_server_method | latency | distribution | client_method, server_method |

0 commit comments

Comments
 (0)