Metrics Capture

WARNING

There is a disconnect between metric/analytic properties and the metric capture object with the system_profile and uptime Metrics. This document to be updated to clarify.

The Experience Manager provides time-series data collection for system metrics as well as application analytics. This document provides the specification for analytics and metrics collections by the Experience Manager and how to ship data to the Experience Manager from your application.

The Experience Manager uses InfluxDB a to capture and analyze data. Data presentation within the Experience Manager is based on simple, defined metrics common for most customer uses.

TIP

Data collected in Influx is available for direct analysis, this use is out of the scope of this document – contact Upswell for details.

Definitions

For the purposes of this document, the following terms are defined as:

• Analytics: Sporadic data such as application events (clicks, state changes or conversion) measured to determine aggregate performance over time
• Metrics: Consistent data points (uptime check, CPU/Memory utilization, etc) collected to monitor system performance and alert on potential outages

Influx Terms

• Measurement: A specific data point to collect such as uptime or system_profile
• Tags: An attribute of a data point such as the Cluster, Node or Application ID
• Fields: The measurement values such as CPU Utilization (multiple values are supported)

Capturing Metrics

Metrics are captured through the capture action on the Node API endpoint in the Experience Manager:

POST /api/v2/clusters/nodes//capture/

All metrics payloads follow a similar schema:

{
    "app_id": "00000000-0000-0000-0000-00000000",
    "measurement": "<measurement>",
    "id": "<event id>",
    "sid": "<secondary id>",
    "value": "<optional value>"
}

Metric Object Schema

Key	Value
app_id	Required. The application ID for the application you are tracking from the Experience Manager.
measurement	Required. The measurement type: conversion, event, state.
id	Required. The event ID, a string value defined for your application.
sid	Optional. A secondary ID, such as start or end that can be used to track durations.
value	Optional. A value associated with this metric such as the duration.

Metrics

INFO

By default metrics shall have a 7-day retention period assigned unless otherwise specified within you Cloud Hosting Agreement, or configured differently for on-premesis installations.

system_profile

Profiles a system’s (Node) performance over time.

Field	Type	Description
cpu	float	The average CPU load across all cores.
gpu	float	The average GPU load when available to the Experience Agent (typically NVIDIA GPU's only).
memory	float	The average memory pressure (percentage utilization)
disk	float	The percentage of the primary volume utilized.

Tags (automatically applied through the Node capture endpoint):

• cluster_id(str): The Cluster UUID of the system
• node_id(str): The Node UUID of the system

Example

WARNING

This example appears to be incorrect, review for accuracy.

{
    "app_id": "00000000-0000-0000-0000-00000000",
    "measurement": "system_profile",
    "id": "cpu",
    "value": 11.73
}

uptime

Measures the Uptime of a system, typically at a 1-minute interval:

Field	Type	Description
up	int	Is the system Up (1) or Down (0)

Tags (automatically applied through the Node capture endpoint):

• cluster_id(str): The Cluster UUID of the system
• node_id(str): The Node UUID of the system
• app_id(str): The sending application ID

Analytics

attendance

The attendance metrics is a special type of event used for counting attendance/visitor-ship within a physical space.

Field	Type	Description
count	int	Should always equal 1

Tags:

• cluster_id(str): The Cluster UUID of the system
• location_id(str): An identifier for the location, such as Gallery Name

conversion

A conversion is a datapoint, similar to an event, but, has a user transaction (i.e. newsletter signup, submit, etc.) associated with it.

Conversions typically have associated goals.

Field	Type	Description
count	int	Should always equal 1, indicates a conversion was started.
value	float, int	The value of the conversion (such as a dollar amount, or seconds engaged)

Tags:

• cluster_id(str): The Cluster UUID of the system
• node_id(str): The Node UUID of the system
• app_id(str): The sending application ID

Example

At minimum, app_id, measurement and id are required. If count and value are left off, they default to 1.

{
    app_id: "00000000-0000-0000-0000-00000000",
    measurement: "conversion",
    id: "signup"
}

event

An event is a trackable action such as a button click, content selection to be quantified.

Events are typically an aggregate quantity that may be compared with one or more other events.

Field	Type	Description
count	int	Should always equal 1, indicates a single instance of the event.
value	float, int	Typically omitted for event, an additional value associated with that event.

Tags:

• cluster_id(str): The Cluster UUID of the system
• node_id(str): The Node UUID of the system
• app_id(str): The sending application ID

Example

At minimum, app_id, measurement and id are required. If count and value are left off, they default to 1.

{
    app_id: "00000000-0000-0000-0000-00000000",
    measurement: "event",
    id: "object-1"
}

state

A state is a special type of event tracked separately to measure where users spend their time within an application.

• For a website/page based application, this will be the web page, for kiosk applications, this will be the kiosk state.
• For websites, the id shall be the page path (i.e. /path/to/page).
• For kiosks, the id shall be the state name, all lower with hyphens (i.e. attract, explore)

When a start is entered, it should send a state metric with sid == start.

Optionally, when a state is closed, an event with sid == end may be sent. When using end also specify a duration indicating how long the state was active.

Field	Type	Description
count	int	Should always equal 1, indicates a single instance of the event.
duration	int	The number of seconds the application was in this state.

Tags:

• cluster_id(str): The Cluster UUID of the system
• node_id(str): The Node UUID of the system
• app_id(str): The sending application ID
• id: The ID of the state (i.e. attract)
• sid: The state action, typically start or end

Example Start Event

{
    "app_id": "00000000-0000-0000-0000-00000000",
    "measurement": "state",
    "id": "attract",
    "sid": "start"
}

Example End Event

{
    "app_id": "00000000-0000-0000-0000-00000000",
    "measurement": "state",
    "id": "attract",
    "sid": "end",
    "duration": 3600
}