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