Metrics Capture

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 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.

INFO

By default all measurements have a 7-day retention period unless otherwise specified in your Cloud Hosting Agreement, or configured differently for on-premises installations.

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)

Analytics

Analytics events are sent to the capture endpoint using the Node's token:

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

All analytics payloads share a common schema:

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

Key	Value
app_id	Required. The Application UUID from the Experience Manager.
measurement	Required. One of: attendance, conversion, event, state.
id	Required (except attendance). An identifier for the event, defined by your application.
sid	Optional. A secondary identifier, e.g. start or end to track durations.
count	Optional. Integer count, defaults to 1.
value	Optional. A numeric value associated with this event.

The following tags are automatically applied from the Node capture endpoint and do not need to be included in the payload:

• cluster_id: The Cluster UUID
• node_id: The Node UUID
• app_id: The sending Application UUID

attendance

The attendance measurement counts visitor-ship within a physical space.

Field	Type	Description
count	int	Should always equal 1.

Additional tags:

• location_id(str): An identifier for the location, such as a Gallery Name (optional)

Example

{
    "app_id": "00000000-0000-0000-0000-000000000000",
    "measurement": "attendance",
    "location_id": "main-gallery"
}

conversion

A conversion is a user transaction (newsletter signup, form submit, etc.) with an optional associated value.

Field	Type	Description
count	int	Should always equal 1, indicates a single conversion.
value	float, int	The value of the conversion (dollar amount, seconds engaged, etc.)

Example

At minimum, app_id, measurement and id are required. count defaults to 1.

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

event

An event is a trackable action such as a button click or content selection to be quantified. Events are typically compared in aggregate 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	Optional. An additional value associated with the event.

Example

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

state

A state tracks where users spend their time within an application.

• For page-based applications, id should be the page path (e.g. /path/to/page).
• For kiosk applications, id should be the state name in lowercase with hyphens (e.g. attract, explore).

When entering a state, send a state event with sid set to start. Optionally, when a state is exited, send a second event with sid set to end and a duration indicating how long the state was active.

Field	Type	Description
count	int	Should always equal 1.
duration	int	Seconds the application was in this state. Only sent with sid: end.

Additional tags (automatically applied):

• id: The state ID (e.g. attract)
• sid: The state action (start or end)

Example — Enter State

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

Example — Exit State

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

System Metrics

System metrics are reported to the profile endpoint using the Node's token:

POST /api/v2/clusters/nodes//profile/

The sending application is identified by the X-Xom-Aid request header (the Application UUID from the Experience Manager). This endpoint is typically called by the Experience Agent on a regular interval, not directly by user applications.

Posting to this endpoint automatically records both a system_profile point and an uptime point to InfluxDB.

Request Headers

Header	Value
X-Xom-Aid	Required. The Application UUID from the Experience Manager.

Request Body

{
    "cpu": 11.73,
    "memory": 75.2,
    "disk": 42.1,
    "gpu": null,
    "processes": {
        "my-app": 1,
        "other-service": 0
    }
}

Key	Type	Description
cpu	float	Required. Average CPU load across all cores (percentage).
memory	float	Required. Memory pressure (percentage utilization).
disk	float	Required. Primary volume utilization (percentage).
gpu	float	Optional. Average GPU load (typically NVIDIA only).
processes	object	Optional. Map of process name to running state (1 = running, 0 = stopped).

system_profile

Profiles a Node's hardware performance over time. Written automatically by the profile endpoint.

Field	Type	Description
cpu	float	Average CPU load across all cores.
memory	float	Average memory pressure (percentage utilization).
disk	float	Percentage of the primary volume utilized.
gpu	float	Average GPU load when available.
<process>	int	Per-process running state (1 running, 0 stopped), one field per entry in processes.

Tags:

• cluster_id: The Cluster UUID
• node_id: The Node UUID
• app_id: The reporting Application UUID

uptime

Records a presence heartbeat for the Node. Written automatically alongside every system_profile — there is no separate uptime payload.

Field	Type	Description
count	int	Always 1 when reported.

Tags:

• cluster_id: The Cluster UUID
• node_id: The Node UUID
• app_id: The reporting Application UUID