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'