Issue 623854: Support unit annotations in ts_mon metrics

infra_libs/ts_mon/common/metrics.py

 # Copyright 2015 The Chromium Authors. All rights reserved.
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
 """Classes representing individual metrics that can be sent."""
 
 import copy
 
 from infra_libs.ts_mon.protos import metrics_pb2
 
@@ skipping 13 matching lines @@
   process may keep track of many metrics.
 
   Note that Metric objects may be initialized at any time (for example, at the
   top of a library), but cannot be sent until the underlying Monitor object
   has been set up (usually by the top-level process parsing the command line).
 
   A Metric can actually store multiple values that are identified by a set of
   fields (which are themselves key-value pairs).  Fields can be passed to the
   set() or increment() methods to modify a particular value, or passed to the
   constructor in which case they will be used as the defaults for this Metric.
 

[agable, 2016/06/29 18:25:23]

Please update this docstring to reference units as well.

[ddoman, 2016/07/06 03:35:37]

Done.

   Do not directly instantiate an object of this class.
   Use the concrete child classes instead:
   * StringMetric for metrics with string value
   * BooleanMetric for metrics with boolean values
   * CounterMetric for metrics with monotonically increasing integer values
   * GaugeMetric for metrics with arbitrarily varying integer values
   * CumulativeMetric for metrics with monotonically increasing float values
   * FloatMetric for metrics with arbitrarily varying float values
 
   See http://go/inframon-doc for help designing and using your metrics.
   """
 
-  def __init__(self, name, fields=None, description=None):
+  def __init__(self, name, fields=None, description=None, units=None):
     """Create an instance of a Metric.
 
     Args:
       name (str): the file-like name of this metric
       fields (dict): a set of key-value pairs to be set as default metric fields
       description (string): help string for the metric. Should be enough to
                             know what the metric is about.
+      units (int): the unit used to measure data for given
+                   metric. Please use the attributes of MetricDataUnit to find
+                   valid integer values for this argument.
     """
     self._name = name.lstrip('/')
     self._start_time = None
     fields = fields or {}
     if len(fields) > 7:
       raise errors.MonitoringTooManyFieldsError(self._name, fields)
     self._fields = fields
     self._normalized_fields = self._normalize_fields(self._fields)
     self._description = description
+    self._units = units
 
     interface.register(self)
 
   @property
   def name(self):
     return self._name
 
   @property
   def start_time(self):
     return self._start_time
@@ skipping 17 matching lines @@
         to add the current metric values.
       start_time (int): timestamp in microseconds since UNIX epoch.
       target (Target): a Target to use.
     """
 
     metric_pb = collection_pb.data.add()
     metric_pb.metric_name_prefix = '/chrome/infra/'
     metric_pb.name = self._name
     if self._description is not None:
       metric_pb.description = self._description
+    if self._units is not None:
+      metric_pb.units = self._units
 
     self._populate_value(metric_pb, value, start_time)
     self._populate_fields(metric_pb, fields)
 
     target._populate_target_pb(metric_pb)
 
   def _populate_fields(self, metric, fields):
     """Fill in the fields attribute of a metric protocol buffer.
 
     Args:
@@ skipping 129 matching lines @@
   def increment(self, fields=None, target_fields=None):
     self._incr(fields, target_fields, 1)
 
   def increment_by(self, step, fields=None, target_fields=None):
     self._incr(fields, target_fields, step)
 
 
 class CounterMetric(NumericMetric):
   """A metric whose value type is a monotonically increasing integer."""
 
-  def __init__(self, name, fields=None, start_time=None, description=None):
+  def __init__(self, name, fields=None, start_time=None, description=None,
+               units=None):
     super(CounterMetric, self).__init__(
-        name, fields=fields, description=description)
+        name, fields=fields, description=description, units=units)
     self._start_time = start_time
 
   def _populate_value(self, metric, value, start_time):
     metric.counter = value
     metric.start_timestamp_us = int(start_time * MICROSECONDS_PER_SECOND)
 
   def set(self, value, fields=None, target_fields=None):
     if not isinstance(value, (int, long)):
       raise errors.MonitoringInvalidValueTypeError(self._name, value)
     self._set(fields, target_fields, value, enforce_ge=True)
@@ skipping 18 matching lines @@
       raise errors.MonitoringInvalidValueTypeError(self._name, value)
     self._set(fields, target_fields, value)
 
   def is_cumulative(self):
     return False
 
 
 class CumulativeMetric(NumericMetric):
   """A metric whose value type is a monotonically increasing float."""
 
-  def __init__(self, name, fields=None, start_time=None, description=None):
+  def __init__(self, name, fields=None, start_time=None, description=None,
+               units=None):
     super(CumulativeMetric, self).__init__(
-        name, fields=fields, description=description)
+        name, fields=fields, description=description, units=units)
     self._start_time = start_time
 
   def _populate_value(self, metric, value, start_time):
     metric.cumulative_double_value = value
     metric.start_timestamp_us = int(start_time * MICROSECONDS_PER_SECOND)
 
   def set(self, value, fields=None, target_fields=None):
     if not isinstance(value, (float, int)):
       raise errors.MonitoringInvalidValueTypeError(self._name, value)
     self._set(fields, target_fields, float(value), enforce_ge=True)
@@ skipping 25 matching lines @@
   for many kinds of data, but you may want to provide a FixedWidthBucketer or
   GeometricBucketer with different parameters."""
 
   CANONICAL_SPEC_TYPES = {
       2: metrics_pb2.PrecomputedDistribution.CANONICAL_POWERS_OF_2,
       10**0.2: metrics_pb2.PrecomputedDistribution.CANONICAL_POWERS_OF_10_P_0_2,
       10: metrics_pb2.PrecomputedDistribution.CANONICAL_POWERS_OF_10,
   }
 
   def __init__(self, name, is_cumulative=True, bucketer=None, fields=None,
-               start_time=None, description=None):
+               start_time=None, description=None, units=None):
     super(DistributionMetric, self).__init__(
-        name, fields=fields, description=description)
+        name, fields=fields, description=description, units=units)
     self._start_time = start_time
 
     if bucketer is None:
       bucketer = distribution.GeometricBucketer()
 
     self._is_cumulative = is_cumulative
     self.bucketer = bucketer
 
   def _populate_value(self, metric, value, start_time):
     pb = metric.distribution
@@ skipping 73 matching lines @@
     self._set(fields, target_fields, value)
 
   def is_cumulative(self):
     raise NotImplementedError()  # Keep this class abstract.
 
 
 class CumulativeDistributionMetric(DistributionMetric):
   """A DistributionMetric with is_cumulative set to True."""
 
   def __init__(self, name, bucketer=None, fields=None,
-               description=None):
+               description=None, units=None):
     super(CumulativeDistributionMetric, self).__init__(
         name,
         is_cumulative=True,
         bucketer=bucketer,
         fields=fields,
-        description=description)
+        description=description,
+        units=units)
 
   def is_cumulative(self):
     return True
 
 
 class NonCumulativeDistributionMetric(DistributionMetric):
   """A DistributionMetric with is_cumulative set to False."""
 
   def __init__(self, name, bucketer=None, fields=None,
-               description=None):
+               description=None, units=None):
     super(NonCumulativeDistributionMetric, self).__init__(
         name,
         is_cumulative=False,
         bucketer=bucketer,
         fields=fields,
-        description=description)
+        description=description,
+        units=units)
 
   def is_cumulative(self):
     return False
+
+
+class MetaMetricsDataUnits(type):
+  """Metaclass to populate the enum values of metrics_pb2.MetricsData.Units

[agable, 2016/06/29 18:25:23]

nit: all our docstrings start with a single sentence that fits on a single line,
followed by a paragraph is more description is necessary.

[ddoman, 2016/07/06 03:35:37]

Done.

+  as class-level attributes.
+  """
+  def __new__(mcs, name, bases, attrs):
+    attrs.update(metrics_pb2.MetricsData.Units.items())
+    return super(MetaMetricsDataUnits, mcs).__new__(mcs, name, bases, attrs)
+
+
+class MetricsDataUnits(object):
+  """Wrapper class for MetricsData.Units. Providing this wrapper class,
+  applications that use ts_mon.metrics don't need to import
+  metrics_pb2.MetricsData.
+
+  See infra_libs/ts_mon/protos/metrics.proto for a list of supported units.
+  """
+  __metaclass__ = MetaMetricsDataUnits