@servicenow/ui-metrics

@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 renderer onChange function is called. [2]
• RENDER_END is marked directly after the component renderer onChange 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:

1. Component Instance Metric Types: Specify the an array of metric types in the component nowMetricTypes property
2. Component Instance Metrics Level: Specify the metrics level integer in the component nowMetricsLevel property
3. Global Metric Types: Specify the an array of metric types in window.nowUiFramework.metricTypes
4. 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 time
• interactionId: Unique identifier of interaction to which the marker belongs
• componentName: Name of the component that created marker
• componentId: Unique identifier of component instance that created marker
• event: Name of event that was marked
• labels: Variable data related to marked event
• meta: 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:

1. A user interaction results in a dispatch, state update, and property update, e.g., a Seismic helper function is called from the view
2. A component lifecycle is dispatched and handled by an effect in the component definition
3. 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.