| |
| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html><head><title>Python: package telemetry.value</title> |
| <meta charset="utf-8"> |
| </head><body bgcolor="#f0f0f8"> |
| |
| <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="heading"> |
| <tr bgcolor="#7799ee"> |
| <td valign=bottom> <br> |
| <font color="#ffffff" face="helvetica, arial"> <br><big><big><strong><a href="telemetry.html"><font color="#ffffff">telemetry</font></a>.value</strong></big></big></font></td |
| ><td align=right valign=bottom |
| ><font color="#ffffff" face="helvetica, arial"><a href=".">index</a><br><a href="../telemetry/value/__init__.py">telemetry/value/__init__.py</a></font></td></tr></table> |
| <p><tt>The <a href="#Value">Value</a> hierarchy provides a way of representing the values measurements<br> |
| produce such that they can be merged across runs, grouped by page, and output<br> |
| to different targets.<br> |
| <br> |
| The core <a href="#Value">Value</a> concept provides the basic functionality:<br> |
| - association with a page, may be none<br> |
| - naming and units<br> |
| - importance tracking [whether a value will show up on a waterfall or output<br> |
| file by default]<br> |
| - other metadata, such as a description of what was measured<br> |
| - default conversion to scalar and string<br> |
| - merging properties<br> |
| <br> |
| A page may actually run a few times during a single telemetry session.<br> |
| Downstream consumers of test results typically want to group these runs<br> |
| together, then compute summary statistics across runs. <a href="#Value">Value</a> provides the<br> |
| Merge* family of methods for this kind of aggregation.</tt></p> |
| <p> |
| <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section"> |
| <tr bgcolor="#aa55cc"> |
| <td colspan=3 valign=bottom> <br> |
| <font color="#ffffff" face="helvetica, arial"><big><strong>Package Contents</strong></big></font></td></tr> |
| |
| <tr><td bgcolor="#aa55cc"><tt> </tt></td><td> </td> |
| <td width="100%"><table width="100%" summary="list"><tr><td width="25%" valign=top><a href="telemetry.value.failure.html">failure</a><br> |
| <a href="telemetry.value.failure_unittest.html">failure_unittest</a><br> |
| <a href="telemetry.value.histogram.html">histogram</a><br> |
| <a href="telemetry.value.histogram_unittest.html">histogram_unittest</a><br> |
| <a href="telemetry.value.histogram_util.html">histogram_util</a><br> |
| <a href="telemetry.value.histogram_util_unittest.html">histogram_util_unittest</a><br> |
| <a href="telemetry.value.improvement_direction.html">improvement_direction</a><br> |
| </td><td width="25%" valign=top><a href="telemetry.value.list_of_scalar_values.html">list_of_scalar_values</a><br> |
| <a href="telemetry.value.list_of_scalar_values_unittest.html">list_of_scalar_values_unittest</a><br> |
| <a href="telemetry.value.list_of_string_values.html">list_of_string_values</a><br> |
| <a href="telemetry.value.list_of_string_values_unittest.html">list_of_string_values_unittest</a><br> |
| <a href="telemetry.value.merge_values.html">merge_values</a><br> |
| <a href="telemetry.value.merge_values_unittest.html">merge_values_unittest</a><br> |
| <a href="telemetry.value.none_values.html">none_values</a><br> |
| </td><td width="25%" valign=top><a href="telemetry.value.scalar.html">scalar</a><br> |
| <a href="telemetry.value.scalar_unittest.html">scalar_unittest</a><br> |
| <a href="telemetry.value.skip.html">skip</a><br> |
| <a href="telemetry.value.skip_unittest.html">skip_unittest</a><br> |
| <a href="telemetry.value.string.html">string</a><br> |
| <a href="telemetry.value.string_unittest.html">string_unittest</a><br> |
| <a href="telemetry.value.summarizable.html">summarizable</a><br> |
| </td><td width="25%" valign=top><a href="telemetry.value.summary.html">summary</a><br> |
| <a href="telemetry.value.summary_unittest.html">summary_unittest</a><br> |
| <a href="telemetry.value.trace.html">trace</a><br> |
| <a href="telemetry.value.trace_unittest.html">trace_unittest</a><br> |
| <a href="telemetry.value.value_unittest.html">value_unittest</a><br> |
| </td></tr></table></td></tr></table><p> |
| <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section"> |
| <tr bgcolor="#ee77aa"> |
| <td colspan=3 valign=bottom> <br> |
| <font color="#ffffff" face="helvetica, arial"><big><strong>Classes</strong></big></font></td></tr> |
| |
| <tr><td bgcolor="#ee77aa"><tt> </tt></td><td> </td> |
| <td width="100%"><dl> |
| <dt><font face="helvetica, arial"><a href="__builtin__.html#object">__builtin__.object</a> |
| </font></dt><dd> |
| <dl> |
| <dt><font face="helvetica, arial"><a href="telemetry.value.html#Value">Value</a> |
| </font></dt></dl> |
| </dd> |
| </dl> |
| <p> |
| <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section"> |
| <tr bgcolor="#ffc8d8"> |
| <td colspan=3 valign=bottom> <br> |
| <font color="#000000" face="helvetica, arial"><a name="Value">class <strong>Value</strong></a>(<a href="__builtin__.html#object">__builtin__.object</a>)</font></td></tr> |
| |
| <tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td> |
| <td colspan=2><tt>An abstract value produced by a telemetry page test.<br> </tt></td></tr> |
| <tr><td> </td> |
| <td width="100%">Methods defined here:<br> |
| <dl><dt><a name="Value-AsDict"><strong>AsDict</strong></a>(self)</dt><dd><tt>Pre-serializes a value to a dict for output as JSON.</tt></dd></dl> |
| |
| <dl><dt><a name="Value-AsDictWithoutBaseClassEntries"><strong>AsDictWithoutBaseClassEntries</strong></a>(self)</dt></dl> |
| |
| <dl><dt><a name="Value-GetBuildbotDataType"><strong>GetBuildbotDataType</strong></a>(self, output_context)</dt><dd><tt>Returns the buildbot's equivalent data_type.<br> |
| <br> |
| This should be one of the values accepted by perf_tests_results_helper.py.</tt></dd></dl> |
| |
| <dl><dt><a name="Value-GetBuildbotValue"><strong>GetBuildbotValue</strong></a>(self)</dt><dd><tt>Returns the buildbot's equivalent value.</tt></dd></dl> |
| |
| <dl><dt><a name="Value-GetChartAndTraceNameForComputedSummaryResult"><strong>GetChartAndTraceNameForComputedSummaryResult</strong></a>(self, trace_tag)</dt></dl> |
| |
| <dl><dt><a name="Value-GetChartAndTraceNameForPerPageResult"><strong>GetChartAndTraceNameForPerPageResult</strong></a>(self)</dt></dl> |
| |
| <dl><dt><a name="Value-GetRepresentativeNumber"><strong>GetRepresentativeNumber</strong></a>(self)</dt><dd><tt>Gets a single scalar value that best-represents this value.<br> |
| <br> |
| Returns None if not possible.</tt></dd></dl> |
| |
| <dl><dt><a name="Value-GetRepresentativeString"><strong>GetRepresentativeString</strong></a>(self)</dt><dd><tt>Gets a string value that best-represents this value.<br> |
| <br> |
| Returns None if not possible.</tt></dd></dl> |
| |
| <dl><dt><a name="Value-IsMergableWith"><strong>IsMergableWith</strong></a>(self, that)</dt></dl> |
| |
| <dl><dt><a name="Value-__eq__"><strong>__eq__</strong></a>(self, other)</dt></dl> |
| |
| <dl><dt><a name="Value-__hash__"><strong>__hash__</strong></a>(self)</dt></dl> |
| |
| <dl><dt><a name="Value-__init__"><strong>__init__</strong></a>(self, page, name, units, important, description, tir_label)</dt><dd><tt>A generic <a href="#Value">Value</a> <a href="__builtin__.html#object">object</a>.<br> |
| <br> |
| Args:<br> |
| page: A Page <a href="__builtin__.html#object">object</a>, may be given as None to indicate that the value<br> |
| represents results for multiple pages.<br> |
| name: A value name string, may contain a dot. Values from the same test<br> |
| with the same prefix before the dot may be considered to belong to<br> |
| the same chart.<br> |
| units: A units string.<br> |
| important: Whether the value is "important". Causes the value to appear<br> |
| by default in downstream UIs.<br> |
| description: A string explaining in human-understandable terms what this<br> |
| value represents.<br> |
| tir_label: The string label of the TimelineInteractionRecord with<br> |
| which this value is associated.</tt></dd></dl> |
| |
| <hr> |
| Class methods defined here:<br> |
| <dl><dt><a name="Value-MergeLikeValuesFromDifferentPages"><strong>MergeLikeValuesFromDifferentPages</strong></a>(cls, values)<font color="#909090"><font face="helvetica, arial"> from <a href="__builtin__.html#type">__builtin__.type</a></font></font></dt><dd><tt>Combines the provided values into a single compound value.<br> |
| <br> |
| When a full pageset runs, a single value_name will usually end up getting<br> |
| collected for multiple pages. For instance, we may end up with<br> |
| [ScalarValue(page1, 'a', 1),<br> |
| ScalarValue(page2, 'a', 2)]<br> |
| <br> |
| This function takes in the values of the same name, but across multiple<br> |
| pages, and produces a single summary result value. In this instance, it<br> |
| could produce a ScalarValue(None, 'a', 1.5) to indicate averaging, or even<br> |
| ListOfScalarValues(None, 'a', [1, 2]) if concatenated output was desired.<br> |
| <br> |
| Some results are so specific to a page that they make no sense when<br> |
| aggregated across pages. If merging values of this type across pages is<br> |
| non-sensical, this method may return None.</tt></dd></dl> |
| |
| <dl><dt><a name="Value-MergeLikeValuesFromSamePage"><strong>MergeLikeValuesFromSamePage</strong></a>(cls, values)<font color="#909090"><font face="helvetica, arial"> from <a href="__builtin__.html#type">__builtin__.type</a></font></font></dt><dd><tt>Combines the provided list of values into a single compound value.<br> |
| <br> |
| When a page runs multiple times, it may produce multiple values. This<br> |
| function is given the same-named values across the multiple runs, and has<br> |
| the responsibility of producing a single result.<br> |
| <br> |
| It must return a single <a href="#Value">Value</a>. If merging does not make sense, the<br> |
| implementation must pick a representative value from one of the runs.<br> |
| <br> |
| For instance, it may be given<br> |
| [ScalarValue(page, 'a', 1), ScalarValue(page, 'a', 2)]<br> |
| and it might produce<br> |
| ListOfScalarValues(page, 'a', [1, 2])</tt></dd></dl> |
| |
| <hr> |
| Static methods defined here:<br> |
| <dl><dt><a name="Value-FromDict"><strong>FromDict</strong></a>(value_dict, page_dict)</dt><dd><tt>Produces a value from a value dict and a page dict.<br> |
| <br> |
| <a href="#Value">Value</a> dicts are produced by serialization to JSON, and must be accompanied<br> |
| by a dict mapping page IDs to pages, also produced by serialization, in<br> |
| order to be completely deserialized. If deserializing multiple values, use<br> |
| ListOfValuesFromListOfDicts instead.<br> |
| <br> |
| value_dict: a dictionary produced by <a href="#Value-AsDict">AsDict</a>() on a value subclass.<br> |
| page_dict: a dictionary mapping IDs to page objects.</tt></dd></dl> |
| |
| <dl><dt><a name="Value-GetConstructorKwArgs"><strong>GetConstructorKwArgs</strong></a>(value_dict, page_dict)</dt><dd><tt>Produces constructor arguments from a value dict and a page dict.<br> |
| <br> |
| Takes a dict parsed from JSON and an index of pages and recovers the<br> |
| keyword arguments to be passed to the constructor for deserializing the<br> |
| dict.<br> |
| <br> |
| value_dict: a dictionary produced by <a href="#Value-AsDict">AsDict</a>() on a value subclass.<br> |
| page_dict: a dictionary mapping IDs to page objects.</tt></dd></dl> |
| |
| <dl><dt><a name="Value-GetJSONTypeName"><strong>GetJSONTypeName</strong></a>()</dt><dd><tt>Gets the typename for serialization to JSON using AsDict.</tt></dd></dl> |
| |
| <dl><dt><a name="Value-ListOfValuesFromListOfDicts"><strong>ListOfValuesFromListOfDicts</strong></a>(value_dicts, page_dict)</dt><dd><tt>Takes a list of value dicts to values.<br> |
| <br> |
| Given a list of value dicts produced by AsDict, this method<br> |
| deserializes the dicts given a dict mapping page IDs to pages.<br> |
| This method performs memoization for deserializing a list of values<br> |
| efficiently, where FromDict is meant to handle one-offs.<br> |
| <br> |
| values: a list of value dicts produced by <a href="#Value-AsDict">AsDict</a>() on a value subclass.<br> |
| page_dict: a dictionary mapping IDs to page objects.</tt></dd></dl> |
| |
| <hr> |
| Data descriptors defined here:<br> |
| <dl><dt><strong>__dict__</strong></dt> |
| <dd><tt>dictionary for instance variables (if defined)</tt></dd> |
| </dl> |
| <dl><dt><strong>__weakref__</strong></dt> |
| <dd><tt>list of weak references to the object (if defined)</tt></dd> |
| </dl> |
| <dl><dt><strong>name_suffix</strong></dt> |
| <dd><tt>Returns the string after a . in the name, or the full name otherwise.</tt></dd> |
| </dl> |
| </td></tr></table></td></tr></table><p> |
| <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section"> |
| <tr bgcolor="#eeaa77"> |
| <td colspan=3 valign=bottom> <br> |
| <font color="#ffffff" face="helvetica, arial"><big><strong>Functions</strong></big></font></td></tr> |
| |
| <tr><td bgcolor="#eeaa77"><tt> </tt></td><td> </td> |
| <td width="100%"><dl><dt><a name="-ValueNameFromTraceAndChartName"><strong>ValueNameFromTraceAndChartName</strong></a>(trace_name, chart_name<font color="#909090">=None</font>)</dt><dd><tt>Mangles a trace name plus optional chart name into a standard string.<br> |
| <br> |
| A value might just be a bareword name, e.g. numPixels. In that case, its<br> |
| chart may be None.<br> |
| <br> |
| But, a value might also be intended for display with other values, in which<br> |
| case the chart name indicates that grouping. So, you might have<br> |
| screen.numPixels, screen.resolution, where chartName='screen'.</tt></dd></dl> |
| </td></tr></table><p> |
| <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section"> |
| <tr bgcolor="#55aa55"> |
| <td colspan=3 valign=bottom> <br> |
| <font color="#ffffff" face="helvetica, arial"><big><strong>Data</strong></big></font></td></tr> |
| |
| <tr><td bgcolor="#55aa55"><tt> </tt></td><td> </td> |
| <td width="100%"><strong>COMPUTED_PER_PAGE_SUMMARY_OUTPUT_CONTEXT</strong> = 'merged-pages-result-output-context'<br> |
| <strong>CONCATENATE</strong> = 'concatenate'<br> |
| <strong>PER_PAGE_RESULT_OUTPUT_CONTEXT</strong> = 'per-page-result-output-context'<br> |
| <strong>PICK_FIRST</strong> = 'pick-first'<br> |
| <strong>SUMMARY_RESULT_OUTPUT_CONTEXT</strong> = 'summary-result-output-context'</td></tr></table> |
| </body></html> |
