telemetry.value | index telemetry/value/__init__.py

`The Value hierarchy provides a way of representing the values measurements
produce such that they can be merged across runs, grouped by page, and output
to different targets.
The core Value concept provides the basic functionality:
- association with a page, may be none
- naming and units
- importance tracking [whether a value will show up on a waterfall or output
file by default]
- other metadata, such as a description of what was measured
- default conversion to scalar and string
- merging properties
A page may actually run a few times during a single telemetry session.
Downstream consumers of test results typically want to group these runs
together, then compute summary statistics across runs. Value provides the
Merge* family of methods for this kind of aggregation.`

Package Contents
`` |  |

failure failure_unittest histogram histogram_unittest histogram_util
histogram_util_unittest
improvement_direction
list_of_scalar_values
list_of_scalar_values_unittest
list_of_string_values
list_of_string_values_unittest
merge_values
merge_values_unittest
none_values
scalar
scalar_unittest
skip
skip_unittest
string
string_unittest
summarizable
summary
summary_unittest
trace
trace_unittest
value_unittest

Classes
`` |  |

__builtin__.object
  Value

class Value(__builtin__.object)
`` | `An abstract value produced by a telemetry page test.`
| Methods defined here:

AsDict(self)
  `Pre-serializes a value to a dict for output as JSON.`

AsDictWithoutBaseClassEntries(self)

GetBuildbotDataType(self, output_context)
  `Returns the buildbot's equivalent data_type.
  This should be one of the values accepted by perf_tests_results_helper.py.`

GetBuildbotValue(self)
  `Returns the buildbot's equivalent value.`

GetChartAndTraceNameForComputedSummaryResult(self, trace_tag)

GetChartAndTraceNameForPerPageResult(self)

GetRepresentativeNumber(self)
  `Gets a single scalar value that best-represents this value.
  Returns None if not possible.`

GetRepresentativeString(self)
  `Gets a string value that best-represents this value.
  Returns None if not possible.`

IsMergableWith(self, that)

__eq__(self, other)

__hash__(self)

__init__(self, page, name, units, important, description, tir_label)
  `A generic Value object.
  Args:
  page: A Page object, may be given as None to indicate that the value
  represents results for multiple pages.
  name: A value name string, may contain a dot. Values from the same test
  with the same prefix before the dot may be considered to belong to
  the same chart.
  units: A units string.
  important: Whether the value is "important". Causes the value to appear
  by default in downstream UIs.
  description: A string explaining in human-understandable terms what this
  value represents.
  tir_label: The string label of the TimelineInteractionRecord with
  which this value is associated.`

Class methods defined here:

MergeLikeValuesFromDifferentPages(cls, values) from __builtin__.type
  `Combines the provided values into a single compound value.
  When a full pageset runs, a single value_name will usually end up getting
  collected for multiple pages. For instance, we may end up with
  [ScalarValue(page1, 'a', 1),
  ScalarValue(page2, 'a', 2)]
  This function takes in the values of the same name, but across multiple
  pages, and produces a single summary result value. In this instance, it
  could produce a ScalarValue(None, 'a', 1.5) to indicate averaging, or even
  ListOfScalarValues(None, 'a', [1, 2]) if concatenated output was desired.
  Some results are so specific to a page that they make no sense when
  aggregated across pages. If merging values of this type across pages is
  non-sensical, this method may return None.`

MergeLikeValuesFromSamePage(cls, values) from __builtin__.type
  `Combines the provided list of values into a single compound value.
  When a page runs multiple times, it may produce multiple values. This
  function is given the same-named values across the multiple runs, and has
  the responsibility of producing a single result.
  It must return a single Value. If merging does not make sense, the
  implementation must pick a representative value from one of the runs.
  For instance, it may be given
  [ScalarValue(page, 'a', 1), ScalarValue(page, 'a', 2)]
  and it might produce
  ListOfScalarValues(page, 'a', [1, 2])`

Static methods defined here:

FromDict(value_dict, page_dict)
  `Produces a value from a value dict and a page dict.
  Value dicts are produced by serialization to JSON, and must be accompanied
  by a dict mapping page IDs to pages, also produced by serialization, in
  order to be completely deserialized. If deserializing multiple values, use
  ListOfValuesFromListOfDicts instead.
  value_dict: a dictionary produced by AsDict() on a value subclass.
  page_dict: a dictionary mapping IDs to page objects.`

GetConstructorKwArgs(value_dict, page_dict)
  `Produces constructor arguments from a value dict and a page dict.
  Takes a dict parsed from JSON and an index of pages and recovers the
  keyword arguments to be passed to the constructor for deserializing the
  dict.
  value_dict: a dictionary produced by AsDict() on a value subclass.
  page_dict: a dictionary mapping IDs to page objects.`

GetJSONTypeName()
  `Gets the typename for serialization to JSON using AsDict.`

ListOfValuesFromListOfDicts(value_dicts, page_dict)
  `Takes a list of value dicts to values.
  Given a list of value dicts produced by AsDict, this method
  deserializes the dicts given a dict mapping page IDs to pages.
  This method performs memoization for deserializing a list of values
  efficiently, where FromDict is meant to handle one-offs.
  values: a list of value dicts produced by AsDict() on a value subclass.
  page_dict: a dictionary mapping IDs to page objects.`

Data descriptors defined here:

__dict__
  `dictionary for instance variables (if defined)`

__weakref__
  `list of weak references to the object (if defined)`

name_suffix
  `Returns the string after a . in the name, or the full name otherwise.`

Functions
`` |  |

ValueNameFromTraceAndChartName(trace_name, chart_name=None)
  `Mangles a trace name plus optional chart name into a standard string.
  A value might just be a bareword name, e.g. numPixels. In that case, its
  chart may be None.
  But, a value might also be intended for display with other values, in which
  case the chart name indicates that grouping. So, you might have
  screen.numPixels, screen.resolution, where chartName='screen'.`

Data
`` |  | COMPUTED_PER_PAGE_SUMMARY_OUTPUT_CONTEXT = 'merged-pages-result-output-context' CONCATENATE = 'concatenate' PER_PAGE_RESULT_OUTPUT_CONTEXT = 'per-page-result-output-context' PICK_FIRST = 'pick-first' SUMMARY_RESULT_OUTPUT_CONTEXT = 'summary-result-output-context'