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.

Tags that have side-effects:

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:

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.

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.

Use an analysis label type to request HeadSpin analysis. For details on label-driven analyses, see the Session Analysis API Documentation.

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.