1 /* Copyright 2016 The TensorFlow Authors. All Rights Reserved.
2 
3 Licensed under the Apache License, Version 2.0 (the "License");
4 you may not use this file except in compliance with the License.
5 You may obtain a copy of the License at
6 
7     http://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,
11 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 See the License for the specific language governing permissions and
13 limitations under the License.
14 ==============================================================================*/
15 
16 // Standard format in which the metrics are collected, before being exported.
17 // These are to be used only by the CollectionRegistry and exporters which
18 // collect metrics using the CollectionRegistry.
19 
20 #ifndef TENSORFLOW_CORE_LIB_MONITORING_COLLECTED_METRICS_H_
21 #define TENSORFLOW_CORE_LIB_MONITORING_COLLECTED_METRICS_H_
22 
23 #include <map>
24 #include <memory>
25 #include <string>
26 #include <vector>
27 
28 #include "tensorflow/core/framework/summary.pb.h"
29 #include "tensorflow/core/lib/monitoring/metric_def.h"
30 #include "tensorflow/core/lib/monitoring/types.h"
31 
32 namespace tensorflow {
33 namespace monitoring {
34 
35 // A metric is a statistic about a monitorable entity.
36 //
37 // Metrics are named with path-like strings, which must conform to the regular
38 // expression (/[a-zA-Z0-9_-]+)+.  For example:
39 //
40 //     /proc/cpu_usage
41 //     /rpc/client/count
42 //
43 // Metrics may optionally have labels, which are additional dimensions used to
44 // identify the metric's values.  For example, the metric /rpc/client/count
45 // might have two labels named "rpc_service" and "rpc_method".
46 //
47 // A label name must be an identifier, which conform to the regular expression
48 // [a-zA-Z_][a-zA-Z_0-9]*, and is only unique within the context of the metric
49 // it is a label for.
50 //
51 // MetricDescriptor defines the structure of the metric (e.g. the fact that it's
52 // a counter and that it has two labels named "rpc_service" and "rpc_method").
53 // Individual points will provide a value for the metric (e.g. the counter
54 // value) and specific values for each of the labels.
55 //
56 // There's no scoping relationship between metrics and monitorable entities: the
57 // metric /rpc/client/count should be defined the same way no matter which
58 // monitorable entity is exporting it.
59 struct MetricDescriptor {
60   // Metric names are path-like.  E.g., "/mycomponent/mymetric".
61   string name;
62 
63   // A human-readable description of what this metric measures.
64   string description;
65 
66   // Label names for the metric.
67   // See the example in the top level comment for MetricDescriptor.
68   std::vector<string> label_names;
69 
70   MetricKind metric_kind;
71 
72   ValueType value_type;
73 };
74 
75 struct Point {
76   // Usually a Point should provide a |label| field for each of the labels
77   // defined in the corresponding MetricDescriptor.  During transitions in
78   // metric definitions, however, there may be times when a Point provides more
79   // or fewer labels than those that appear in the MetricDescriptor.
80   struct Label {
81     // The |name| field must match the |label_name| field in the
82     // MetricDescriptor for this Point.
83     string name;
84     string value;
85   };
86   std::vector<Label> labels;
87 
88   // The actual metric value, dependent on the value_type enum.
89   ValueType value_type;
90   int64 int64_value;
91   string string_value;
92   bool bool_value;
93   HistogramProto histogram_value;
94   Percentiles percentiles_value;
95 
96   // start_timestamp and end_timestamp indicate the time period over which this
97   // point's value measurement applies.
98   //
99   // A cumulative metric like /rpc/client/count typically has runs of
100   // consecutive points that share a common start_timestamp, which is often
101   // the time at which the exporting process started.  For example:
102   //
103   //   value:  3  start_timestamp: 1000  end_timestamp: 1234
104   //   value:  7  start_timestamp: 1000  end_timestamp: 1245
105   //   value: 10  start_timestamp: 1000  end_timestamp: 1256
106   //   value: 15  start_timestamp: 1000  end_timestamp: 1267
107   //   value: 21  start_timestamp: 1000  end_timestamp: 1278
108   //   value:  4  start_timestamp: 1300  end_timestamp: 1400
109   //
110   // The meaning of each point is: "Over the time period from
111   // 'start_timestamp' to 'end_timestamp', 'value' client RPCs finished."
112   //
113   // Note the changed start_timestamp and the decrease in 'value' in the
114   // last line; those are the effects of the process restarting.
115   //
116   // Delta metrics have the same interpretation of the timestamps and values,
117   // but the time ranges of two points do not overlap.  The delta form of the
118   // above sequence would be:
119   //
120   //   value:  3  start_timestamp: 1000  end_timestamp: 1234
121   //   value:  4  start_timestamp: 1235  end_timestamp: 1245
122   //   value:  3  start_timestamp: 1246  end_timestamp: 1256
123   //   value:  5  start_timestamp: 1257  end_timestamp: 1267
124   //   value:  6  start_timestamp: 1268  end_timestamp: 1278
125   //   value:  4  start_timestamp: 1300  end_timestamp: 1400
126   //
127   // For gauge metrics whose values are instantaneous measurements,
128   // start_timestamp and end_timestamp may be identical.  I.e., there is no need
129   // to strictly measure the time period during which the value measurement was
130   // made.
131   //
132   // start_timestamp must not be younger than end_timestamp.
133   uint64 start_timestamp_millis;
134   uint64 end_timestamp_millis;
135 };
136 
137 // A set of points belonging to a metric.
138 struct PointSet {
139   // This must match a name defined by a MetricDescriptor message.
140   string metric_name;
141 
142   // No two Points in the same PointSet should have the same set of labels.
143   std::vector<std::unique_ptr<Point>> points;
144 };
145 
146 // Standard format in which the metrics are collected, before being exported.
147 struct CollectedMetrics {
148   // The keys are the metric-names.
149   std::map<string, std::unique_ptr<MetricDescriptor>> metric_descriptor_map;
150   std::map<string, std::unique_ptr<PointSet>> point_set_map;
151 };
152 
153 }  // namespace monitoring
154 }  // namespace tensorflow
155 
156 #endif  // TENSORFLOW_CORE_LIB_MONITORING_COLLECTED_METRICS_H_
157