1// Copyright 2020 The Pigweed Authors
2//
3// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4// use this file except in compliance with the License. You may obtain a copy of
5// the License at
6//
7//     https://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12// License for the specific language governing permissions and limitations under
13// the License.
14syntax = "proto3";
15
16package pw.metric;
17
18// A metric, described by the name (path + name), and the value.
19//
20// This flattened representation, while more complicated than the obvious tree
21// structure alternative, enables streaming metrics from the device in low
22// memory or low compute situations.
23message Metric {
24  // The token path from the root. The last token is the metric name, and
25  // previous tokens are the parent group names. This could be converted from
26  // the tokens into a string; for example the token path {0xfaff, 0xabcd}:
27  //
28  //  - The group is 0xfaff (root, parent)
29  //  - The metric is 0xabcd
30  //
31  // Given the token database, this might be converted into:
32  //
33  //   /i2c_bus_1/failed_transactions
34  //
35  // Note: This uses a repeated fixed32 instead of a "Oneof" with the string
36  // path to reduce the encoded size. Using a repeated Oneof name { str,
37  // fixed32 } would cost approximately 6N bytes for N path elements, vs 2 + 4N
38  // bytes in the packed case.
39  repeated fixed32 token_path = 1;
40
41  // The string path from the root. Similar to token path, but with strings.
42  // Note: This is currently unsupported.
43  repeated string string_path = 2;
44
45  // The metric value. This field should be omitted when used as a query.
46  oneof value {
47    float as_float = 3;
48    uint32 as_int = 4;
49  };
50}
51
52message MetricRequest {
53  // Metrics or the groups matched to the given paths are returned.  The intent
54  // is to support matching semantics, with at least subsetting to e.g. collect
55  // all the metrics in a group and its children. We may also implement
56  // wildcard matchers.
57  //
58  // Value fields in the metrics will be ignored, since this is a query.
59  //
60  // Note: This is currently unsupported.
61  repeated Metric metrics = 1;
62}
63
64message MetricResponse {
65  repeated Metric metrics = 1;
66}
67
68service MetricService {
69  // Returns metrics or groups matching the requested paths.
70  rpc Get(MetricRequest) returns (stream MetricResponse) {}
71}
72