Annotating Your Session
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.
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 you might encounter:
Tags that have side-effects:
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:
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
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
Specifications for log label statements
The logging statements must provide fields in the order listed below.