Overview
HeadSpin offers APIs for users to customize Performance Session data captured from HeadSpin-enabled devices. In this document, we'll review the tools at your disposal to customize and annotate your Performance Sessions.
What is a Performance Session?
A Performance Session is a living document consisting of a collection of data and metadata from a recorded device experience. Each session is given a unique identifier or <code class="dcode">session_id</code>. Sessions can be created using the remote control UI, HeadSpin Appium or Selenium capabilities, or the Session API. The Session API also makes session data accessible for reading, writing, and applying custom analytics.
Session Tags
Tags are custom annotations associated with a session. Tags consist of key-value pairs, and you can create multiple tags with the same key but different values. For example, <code class="dcode">foo: bar</code> and <code class="dcode">foo: baz</code> would represent two different tags when applied to the same session. See the documentation on Session Tags API for more details.
Standard tags associated with User Flows*:
*When a session gets added to a User Flow and its status is set (see Performance Monitoring UI for a high-level description of what a User Flow is), the standard tags shown below are automatically added to the session.
Tag |
Description |
Example |
user_flow: <user_flow_name> |
The name of the user flow that this session is associated with. |
Add to Cart |
user_flow_id: <user_flow_id> |
The unique ID for the user flow that this session is associated with. |
ed18aa5b-d8eb-43a0-9a68-61ced64f567e |
geo: <location> |
Codes for the country and city where the device was located. |
Mountain View, US |
device_id: <device_id> |
The ID for the device the session was captured on. |
9d14f02c035fa335a50c47a13b193bc4d1323c41 |
hostname |
The host address of the device that captured the session. |
proxy-us-mvo-5.headspin.io |
device_sku: <sku> |
The device the session was captured on. |
iPhone X |
carrier: <carrier_name> |
The name of the network service provider for a device SIM card. |
T-Mobile |
start_timestamp: <unix_timestamp> |
The UNIX timestamp corresponding to the start of the capture session. |
1603834949.580 |
end_timestamp: <unix_timestamp> |
The UNIX timestamp corresponding to the end of the capture session. |
1603835021.060 |
duration_seconds: <duration_in_seconds> |
The capture session duration in units of seconds. |
71.480 |
datetime_utc |
A string representing the UTC date and time following ISO 8601 format. |
2021-10-21T16:21:54.321 |
datetime_local |
A string representing the date and time in device time zone following ISO 8601 format. |
2021-10-21T16:21:54.321 |
day_of_week: <day_of_week> |
The day of the week when the capture session started in the UTC timezone. |
Mon |
month_in_year: <month_in_year> |
The integer index of the month of the year when the capture session started in the UTC timezone. |
5 represents May |
year: <year> |
The year when the capture session started in the UTC timezone. |
2020 |
app: <app_package_name> |
The name of an app used during a session. |
com.google.ios.youtube |
user_email_address: <user_email_address> |
The email address of the user that captured the session. |
[email protected] |
team_name: <team_name> |
The name of the team that captured the session. |
TeamA |
Tags that have side-effects:
Tag |
Description |
session type: video |
Analyze the whole session for issues associated with video streaming, gaming, or rich interactive media experiences. |
session type: first load |
Analyze the visual time to completion from the first page change to the last. |
analysis: screen freezing |
Enable the Screen Freezing Issue card analysis. See the documentation on Issues for more details. |
vmaf: <reference_session_id> |
Run the Netflix VMAF analysis on the session video using the specified reference session ID for the required reference video. |
Session Labels
Session labels are custom annotations associated with specific parts of the Session timeline. As opposed to tags which are simple key-value pairs, session labels have the following properties:
Session Label Object Property |
Description |
label_id |
A UUID that uniquely identifies the label. |
session_id |
The session UUID that the label is associated with. |
name |
A string name for a label. |
start_time |
The start time relative to session start. |
end_time |
(optional) The end time relative to session start. |
ts_start |
The absolute (UNIX) start time. |
ts_end |
(optional) The absolute (UNIX) end time. |
label_type |
(optional, default "user" ) A string that is the type of the label. The label type determines how HeadSpin responds to the label. |
category |
(optional) A string that is the category of the label. The label category is converted to lower case. |
data |
(optional) Any useful JSON-serializable content associated with this label. |
pinned |
(optional, default false ) A boolean flag indicating whether the label is pinned to the session or not. Pinned labels are shown by default when viewing a session, under the right panel's Details section. Pinned labels cannot be deleted. |
video_box |
(optional) Coordinates of bounding boxes provided as nested arrays in the format [[x0, y0, x1, y1], ...] . |
See the documentation on Session Annotation API for more details.
Standard label types
Capture sessions may automatically be annotated with the following label types, except for <code class="dcode">user</code>, which is created by the user. See the documentation on the Waterfall UI for more details.
Label Type |
Description |
capture-started |
The UNIX timestamp when session capture start was initiated. |
capture-ended |
The UNIX timestamp when session capture ended. |
capture-complete |
The UNIX timestamp when session data was fully uploaded. |
foreground-app |
The current foreground application at a given time during the session. |
foreground-activity |
The current foreground activity at a given time during the session. |
stack-trace-warning , stack-trace-exception , stack-trace-fatal |
Stack traces identified in the device log. |
appium-command |
Appium commands issued during the session. |
selenium-command |
Selenium commands issued during the session. |
user |
The default label type for free-form user annotations with no side-effects. |
User label types
Along with the <code class="dcode">user</code> label type, you can specify one of the following feedback or analysis label types. If you specify any other label type, the label will be created with the <code class="dcode">user</code> type instead.
Use a feedback label type to report issues to the HeadSpin team about the session. For details on providing feedback, see the Providing Feedback Documentation.
Label Type |
Description |
needs-improvement |
Feedback that an existing solution is insufficient or inadequate and needs to be improved to be useful. |
report-an-error |
Feedback that the existing solution is broken or unusable. |
suggestion |
A tip, hint, or friendly request regarding ways HeadSpin could better meet your needs. |
Use an analysis label type to request HeadSpin analysis. For details on label-driven analyses, see the Session Analysis API Documentation.
Label Type |
Description |
audio-activity-request |
Runs the audio activity analysis inside the label's timespan. |
audio-match-request |
Runs the audio match analysis inside the label's timespan. |
image-match-request |
Runs the image match analysis inside the label's timespan. |
loading-animation-request |
Runs the loading animation issue analysis inside the label's timespan. |
ocr-request |
Runs the OCR (Optical Character Recognition) analysis inside the label's timespan. |
page-load-request |
Runs the visual page load time analysis inside the label's timespan. |
time-series-request |
Runs the time series data analysis inside the label's timespan. |
video-content |
Runs the video quality analyses inside the label's timespan. |
Creating capture session labels from log statements
For capture sessions, you can inject logging statements within your application to create labels on demand. This is a simple yet versatile way to create labels on-the-fly, placing the start and end times of the label accurately as your application runs. You can use this for tasks such as measuring the duration of load times, certain actions, or scenarios in your application. You can also create certain labels that will automatically drive HeadSpin analyses inside the label's timespan.
To create these labels, have your application produce log lines containing statements in the following format:
HeadSpinV1 Label.<action> name:<name> label_type:<label type> category:<category> video_box:<video box settings> data:<data>
The <code class="dcode">HeadSpinV1</code> phrase is the keyword signaling the log statement's intent. It may be entered differently for Android and iOS (see the examples below). <code class="dcode">name</code> is a required field. All other fields are optional and may be omitted. However, you must use the same ordering for the fields as above. Except for <code class="dcode">data</code>, no whitespace is permitted for any field. The table below contains detailed explanations for all the terms.
Examples - creating a label spanning some time
Android example:
# Android, mark the beginning of the label
Log.i("HeadSpinV1", "Label.start name:launch-timing data:{\"x\": 123, \"y\": 200}");
# After performing some actions, mark the end of the label
Log.i("HeadSpinV1", "Label.end name:launch-timing");
iOS example:
# iOS, mark the beginning of the label
NSLog("HeadSpinV1 Label.start name:%@ data:%@", "launch-timing", "{\"x\": 123, \"y\": 200}")
# After performing some actions, mark the end of the label
NSLog("HeadSpinV1 Label.end name:%@", "launch-timing")
This will create a pairing, matched by <code class="dcode">name</code>, to mark the start and end of a label during a capture session. If <code class="dcode">Label.start</code> does not have a corresponding <code class="dcode">Label.end</code> at the end of the capture session, an instantaneous label will be created at the time of <code class="dcode">Label.start</code>.
Examples - creating an instantaneous label
Android example:
# Android
Log.i("HeadSpinV1", "Label.instant name:task-finished data:3");
iOS example:
# iOS
NSLog("HeadSpinV1 Label.instant name:%@ data:%@", "task-finished", "3")
Specifications for log label statements
The logging statements must provide fields in the order listed below.
Field |
When to Use |
Whitespace Allowed? |
Description |
action |
Required for all statements |
No |
Must be one of the following: start , end , instant . Indicates which part of the label the log statement is for. To create a label with a timespan, there must be matching start and end statements. A start without end results in an instant label. An end without an existing matching start will be ignored. |
name |
Required for all statements |
No |
Name of the label. Used to match start and end logging statements. |
label_type |
Optional & only used for start |
No |
Must be one of the user label types. All other inputs will result in the default value user being used. |
category |
Optional & only use for start |
No |
Category of the label which is used to group the labels in the Waterfall UI. Analysis label types have set categories regardless of user input (e.g., the category assigned to page-load-request labels is page load ). |
video_box |
Optional & only use for start |
No |
Must be a JSON-encoded string of the appropriate data stripped of whitespace. E.g., [[0,50,200,300]] . All invalid inputs will be ignored. See the documentation on applying spatial filtering in video analyses for details. |
data |
Optional & can be used for all statements |
Yes |
If used, everything after data: in the log line will be taken as the value for data . If decodable as a JSON string, the label will have the decoded object in its data . Otherwise, it will hold the raw string. When provided with the end statement, it will overwrite any data provided in the matching start statement. |