HeadSpin Documentation

Replica DB UI

The HeadSpin Replica DB feature of HeadSpin allows for exporting user flows to an external Postgres database. The following sections will detail how to manage this in the UI.


The Replica DB user interface can be accessed by opening a user flow in the Performance Monitoring UI and clicking the "Replica" button on the top-right, which opens the following dialog:

HeadSpin Replica

In the middle of this dialog we see two controls: Status and AutoSync.


The Status control shows the current status of the replica DB. The Status can be one of:

  • Inactive: This user flow has never been exported to the Replica DB.
  • Out of Sync: There is recent data in the user flow which has not yet been exported to the Replica DB.
  • Syncing: Data in the user flow is currently syncing/being exported to the replica.
  • Error: There was an error on the most recent sync.

The Status control may also indicate how many sessions have not yet been exported to the Replica DB, as appropriate.


AutoSync is a feature that will automatically export any new data to the Replica DB as soon as it is added to the user flow, or when a session in the user flow is updated. For example, when a session is attached to a user flow, its corresponding measurements will be automatically exported to the Replica DB. When AutoSync is Off, any exports to the Replica DB must be done manually, either from the UI or the Replica DB API

Syncing Data to the Replica DB

To sync the user flow to the Replica DB from the UI, you can either

  • Enable AutoSync, which will automatically launch a sync.
  • Click "Sync Now" in the Status bar to perform a manual sync.

Note: When AutoSync is enabled, the "Sync Now" option will not be available.

Accessing the Replica DB

Once a replica sync is scheduled, the Replica DB will be provisioned (if not provisioned already). The database credentials and a description of the Replica DB schema will be displayed. Here's an example:

database credentials and a description of the Replica DB schema

If you are using the standard <code class="dcode">psql</code> postgres command-line client, you can copy and paste the <code class="dcode">psql</code> command into a terminal. Enter the given password when prompted.

Note: There is a limit to the number of simultaneous connections that can be opened with these credentials. Bear this in mind for different consumers for replica. If more simultaneous connections are needed (default is 5), contact HeadSpin to increase the limit.

Understanding the Replica DB Schema

The Replica DB UI has a section called "Tables" which describes the schema of the available tables in the context of the current user flow:

Replica DB Schema

Core Data Export

The "Core Data Export" section shows the name of the table to which the current user flow has been exported. Clicking the table name expands a description of its columns.

In the "Standard Columns" subsection, we see a list of columns which are standard across all Replica DB exports, providing generic information about a session: the device on which the session was recorded, the hostname, geographic location, and the session_id of the session.

In the "Performance Measurement Columns" subsection, we see a list of columns that correspond 1-to-1 with the Measurements available in this user flow. The table maps each SQL column name to the readable name of its corresponding measurement.

Note: Column name generation generally works by translating readable names like "My Measurement" to snake-case names like <code class="dcode">my_measurement</code>. However, this is not strictly the case. In some cases, names are truncated and appended a number at the end. For example "My Measurement" may be mapped to a name like <code class="dcode">my_measurem_1</code>. Always check with the information here to use the correct column names.

Auxiliary Tables

At the bottom of the Tables section is a subsection named Auxiliary Tables.

Auxiliary Tables

These tables store session-related data and can be joined on from the original "Core Export" table using the session_id column.

  • capture_issues: Data about the Issues computed by HeadSpin analysis including their impact time.
  • capture_sessions: Network traffic data, including all HTTP message exchanges and associated timing data.
  • session_timeseries: Metadata about the session's timeries.
  • session_timeseries_data: The actual (x,y) point data for the timeseries.

See here for more details on what is stored in these tables.