HeadSpin Documentation
Documentation

Annotating Your Session

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. someone@gmail.com
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.