1/*
2 * Copyright 2020 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17// The protobuf messages for lab host to export metadata and reosurce metrics.
18syntax = "proto3";
19
20package dual_home_lab.monitoring_agent.resource_monitoring;
21
22import "google/protobuf/timestamp.proto";
23
24option java_package = "com.google.dualhomelab.monitoringagent.resourcemonitoring";
25option java_multiple_files = true;
26option java_generic_services = true;
27
28// A tag-value pair message represents the metric value.
29// For example:
30// To represent device disk used percentage.
31// metric {
32//   tag: "/data"
33//   value: 20.5
34// }
35message Metric {
36  // A string tag associates to the value.
37  string tag = 1;
38  // A float value represents the resource value.
39  float value = 2;
40}
41
42// A message that describes the resource and its metrics.
43// For example:
44// To represent disk space usage values at certain moment.
45// resource {
46//   resource_name: "disk_space"
47//   resource_instance: "/data"
48//   timestamp {
49//     seconds: 1589342214
50//   }
51//   metric: {
52//     tag: "avail"
53//     value: 20.5
54//   }
55//   metric: {
56//     tag: "used"
57//     value: 18.7
58//   }
59//   metric: {
60//     tag: "reserved for root"
61//     value: 16.2
62//   }
63// }
64message Resource {
65  // A string resource name. ex. "cpu", "memory", "disk_space".
66  string resource_name = 1;
67  // A string reperesent the sub resource name.
68  string resource_instance = 2;
69  // The Metric describe the host or device resource usages.
70  repeated Metric metric = 3;
71  // The collecting timestamp.
72  google.protobuf.Timestamp timestamp = 4;
73}
74
75// A name-value message to represent the metadata attribute.
76// For example:
77// To represent the run target.
78// attribute {
79//   name: "run_target"
80//   value: "atom-userdebug"
81// }
82// To reperent the pools.
83// attribute {
84//   name: "pool"
85//   value: "asit"
86// }
87// attribute {
88//   name: "pool"
89//   value: "apct"
90// }
91message Attribute {
92  string name = 1;
93  string value = 2;
94}
95
96// A message that describes the device state and resource usages.
97// For example:
98// To represent a monitored host
99// host {
100//   identifier: {
101//     key: "lab_name"
102//     value: "us-mtv43"
103//   }
104//   identifier: {
105//     key: "host_name"
106//     value: "foo.bar.com"
107//   }
108//   identifier: {
109//     key: "test_harness"
110//     value: "tradefed"
111//   }
112//   attribute: {... check the attribute example above ...}
113//   resource: {... check the resource example abobe ...}
114// }
115// To represent a monitored device
116// device {
117//   identifier: {
118//     key: "device_serial"
119//     value: "VVEG-GIDSAN"
120//   }
121//   attribute: {... check the attribute example above ...}
122//   resource: {... check the resource example abobe ...}
123// }
124message MonitoredEntity {
125  // The string map that helps identify the monitored entity
126  map<string, string> identifier = 1;
127  // The attribute messages that describe the device metadata.
128  repeated Attribute attribute = 2;
129  // The resource messages that describe the device state and resource metrics.
130  repeated Resource resource = 3;
131}
132
133// A message that describe the state and resource usages for a lab host and its
134// connected devices.
135message LabResource {
136  MonitoredEntity host = 1;
137  repeated MonitoredEntity device = 2;
138}
139
140// The request message to query the LabResource.
141message LabResourceRequest {}
142
143// The service which is intend to export device metrics and metadata to the host
144// monitoring agent. The host monitoring agent is responsible for
145// collecting host/device metrics and exporting the metrics to user defined
146// cloud PubSub topics.
147service LabResourceService {
148  // Queries lab resource message.
149  rpc GetLabResource(LabResourceRequest) returns (LabResource) {
150    // The http equivalent is curl http://ADDRESS/v1/lab_resource_message
151    // (Assuming your service is hosted at the given 'ADDRESS')
152  }
153}
154