README
@servicenow/ui-metrics
@servicenow/ui-metrics
is the performance instrumentation and metrics parsing library used by Seismic. It creates marker entries at specific code execution points in Seismic as described in the following sections. The library can also be used to define custom metrics to be marked by components, but that need should be rare, if ever. Additionally, the parsing code that gets the markers and collates the data in a meaningful and useful fashion can be imported and used by reporting libraries and tests both in production and development.
Seismic Metrics
The metrics described in this section can be marked by some or all Seismic components based on the metric levels and enablement options described in the following section. The metrics below are annotated with their corresponding level.
ERROR
is marked when the Seismic Sandbox catches an error. [5]GQL
is marked directly before the GQL effect XHR call is made. [4]HTTP
is marked directly before the HTTP effect XHR call is made. [4]DISPATCH
is marked when an event is dispatched. [3]RENDER_START
is marked directly before the component rendereronChange
function is called. [2]RENDER_END
is marked directly after the component rendereronChange
function call has completed. [2]RENDER_TREE
is marked after the component and all descendant renders have completed. [2]UPDATE_PROPERTIES
is marked directly before a scheduled property update is applied. [1]UPDATE_STATE
is marked directly before a scheduled state update is applied. [1]SCHEDULE
is marked when code execution is scheduled. This includes, but is not limited to, state updates, property updates, dispatches, and renders. [1]DEFER
is marked when the execution of code is intentionally deferred. [1]PROPERTY_REFLECTION
is marked when the corresponding property attributes are updated in the DOM. [1]EFFECT_START
is marked directly before an effect function is executed. [0]EFFECT_END
is marked directly after an effect function is executed. [0]PATCH_START
is marked directly before Snabbdom patches the DOM. [0]PATCH_END
is marked directly after Snabbdom patches the DOM. [0]HOOK_START
is marked directly before a Snabbdom hook function executes.HOOK_END
is marked directly after a Snabbdom hook function executes.
Enabling Metrics
Enabling metrics can be done globally and/or on a component instance basis. The order of precedence for determining what metrics a component instance will mark during code execution are as follows:
- Component Instance Metric Types: Specify the an array of metric types in the component
nowMetricTypes
property - Component Instance Metrics Level: Specify the metrics level integer in the component
nowMetricsLevel
property - Global Metric Types: Specify the an array of metric types in
window.nowUiFramework.metricTypes
- Global Metrics Level Specify the metrics level integer in the
window.nowUiFramework.metricsLevel
Global variables must be set before importing Seismic.
Accessing Metrics
Metrics can be accessed by importing and calling getMarkers
, i.e.,
import {getMarkers} from '@servicenow/ui-metrics';
const markers = getMarkers();
Metric Data Structure
getMarkers
returns an array of marker objects. Marker objects are chronologically ordered. Below are the marker object properties.
startTime
: Marker timeinteractionId
: Unique identifier of interaction to which the marker belongscomponentName
: Name of the component that created markercomponentId
: Unique identifier of component instance that created markerevent
: Name of event that was markedlabels
: Variable data related to marked eventmeta
: Additional data specific to the event type, e.g., GQL or HTTP resource entry (XHR request data)
Interactions
Client interactions are identified by the interactionId
property of a marker item returned by getMarkers
. A client interaction can be initiated in two ways:
- A user interaction results in a dispatch, state update, and property update, e.g., a Seismic helper function is called from the view
- A component lifecycle is dispatched and handled by an effect in the component definition
- An event handler,
eventHandlers
, responds to a native event
All subsequent events, updates, renders, etc. that are a direct result from code execution at one of these entry points are part of a single interaction.
Defining Custom Metrics
Custom metrics can be defined by calling defineMetric(name, level)
once and then calling mark(host, interactionId, event, labels)
at the point of interest in the code. The interactionId
can be retrieved calling getInteractionId(action.meta)
. labels
should be delimited by :
. Labels should be scalar values.