bug 1477750 - Correct the 'event' identifier pattern documentation r=janerik
authorChris H-C <chutten@mozilla.com>
Tue, 07 Aug 2018 19:50:33 +0000
changeset 430430 d0e9a6ae0f655fd6fd1292834398530de58c9637
parent 430429 924956d87045a070e38a312cb88966313e75d015
child 430431 3d2b630fe3c92e962424f4b84ab647cd8dd9aafc
push id34405
push userncsoregi@mozilla.com
push dateWed, 08 Aug 2018 09:57:26 +0000
treeherdermozilla-central@c65991f3fa10 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersjanerik
bugs1477750
milestone63.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
bug 1477750 - Correct the 'event' identifier pattern documentation r=janerik Differential Revision: https://phabricator.services.mozilla.com/D2735
toolkit/components/telemetry/docs/collection/events.rst
--- 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: