third_party/pigweed/repo/pw_metric/pw_metric_proto/metric_service.proto

   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.
  14 syntax = "proto3";
  15
  16 package 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.
  23 message 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
  52 message 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
  64 message MetricResponse {
  65   repeated Metric metrics = 1;
  66 }
  67
  68 service MetricService {
  69   // Returns metrics or groups matching the requested paths.
  70   rpc Get(MetricRequest) returns (stream MetricResponse) {}
  71 }