author | Chris H-C <chutten@mozilla.com> |
Tue, 07 Aug 2018 19:50:33 +0000 | |
changeset 430430 | d0e9a6ae0f655fd6fd1292834398530de58c9637 |
parent 430429 | 924956d87045a070e38a312cb88966313e75d015 |
child 430431 | 3d2b630fe3c92e962424f4b84ab647cd8dd9aafc |
push id | 34405 |
push user | ncsoregi@mozilla.com |
push date | Wed, 08 Aug 2018 09:57:26 +0000 |
treeherder | mozilla-central@c65991f3fa10 [default view] [failures only] |
perfherder | [talos] [build metrics] [platform microbench] (compared to previous push) |
reviewers | janerik |
bugs | 1477750 |
milestone | 63.0a1 |
first release with | nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
|
last release without | nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
|
toolkit/components/telemetry/docs/collection/events.rst | file | annotate | diff | comparison | revisions |
--- a/toolkit/components/telemetry/docs/collection/events.rst +++ b/toolkit/components/telemetry/docs/collection/events.rst @@ -48,28 +48,37 @@ Where the individual fields are: - ``value``: ``String``, optional, may be ``null``. This is a user defined value, providing context for the event. - ``extra``: ``Object``, optional, may be ``null``. This is an object of the form ``{"key": "value", ...}``, both keys and values need to be strings, keys are identifiers. This is used for events where additional richer context is needed. .. _eventlimits: Limits ------ -Each ``String`` marked as an identifier is restricted to the following regex pattern: ``^[:alpha:][:alnum:_.]*[:alnum:]$``. +Each ``String`` marked as an identifier (the event ``name``, ``category``, ``method``, +``object``, and the keys of ``extra``) is restricted to be composed of alphanumeric ASCII +characters ([a-zA-Z0-9]) plus infix underscores ('_' characters that aren't the first or last). +``category`` is also permitted infix periods ('.' characters, so long as they aren't the +first or last character). -For the Firefox Telemetry implementation, several fields are subject to limits: +For the Firefox Telemetry implementation, several fields are subject to length limits: - ``category``: Max. byte length is ``30``. - ``method``: Max. byte length is ``20``. - ``object``: Max. byte length is ``20``. - ``value``: Max. byte length is ``80``. - ``extra``: Max. number of keys is ``10``. + - Each extra key name: Max. string length is ``15``. - Each extra value: Max. byte length is ``80``. +Only ``value`` and the values of ``extra`` will be truncated if over the specified length. +Any other ``String`` going over its limit will be reported as an error and the operation +aborted. + The YAML definition file ======================== Any event recorded into Firefox Telemetry must be registered before it can be recorded. For any code that ships as part of Firefox that happens in `Events.yaml <https://dxr.mozilla.org/mozilla-central/source/toolkit/components/telemetry/Events.yaml>`_. The probes in the definition file are represented in a fixed-depth, three-level structure. The first level contains *category* names (grouping multiple events together), the second level contains *event* names, under which the events properties are listed. E.g.: @@ -90,17 +99,17 @@ The probes in the definition file are re completion: # ... description: Recorded when a search completion suggestion was clicked. extra_keys: distance: The edit distance to the current search query input. loadtime: How long it took to load this completion entry. # ... -Category and probe names are subject to the limits and regex patterns :ref:`specified above <eventlimits>`. +Category and event names are subject to the limits :ref:`specified above <eventlimits>`. The following event properties are valid: - ``methods`` *(optional, list of strings)*: The valid event methods. If not set this defaults to ``[eventName]``. - ``objects`` *(required, list of strings)*: The valid event objects. - ``description`` *(required, string)*: Description of the event and its semantics. - ``release_channel_collection`` *(optional, string)*: This can be set to ``opt-in`` (default) or ``opt-out``. - ``record_in_processes`` *(required, list of strings)*: A list of processes the event can be recorded in. Currently supported values are: