Injecting Time Series Data to Customize Your BlazeMeter Reports

BlazeMeter customers often need to enhance the standard Timeline Report with additional external data from custom KPIs. When appended to existing tests in BlazeMeter, this additional data, also known as time series data, helps teams visualize the correlation between the new data and the existing time series statistical data. The result is a more complete picture of the test environment that provides additional insights into the test’s performance.

Let us see what it looks like and how to inject new data.

What is Time Series Data?

Time series data is a collection of data results that are recorded over consistent intervals of time. Also known as time-stamped data, time series data is used to track changes over specific time increments as a sequence of data points. 

Understanding the BlazeMeter Timeline Report

The Timeline Report can be found in the second tab of your BlazeMeter test results. It displays the various statistical data gathered during the period the test ran. For example, the Response Time, Hits per Second, and the number of Virtual Users are some of the color-coordinated data values that are plotted in the graph. The graph is interactive, and you can focus on a time frame or hover your mouse on the graph to display a pop-up of the underlying data points.

On the left side panel of the screen, you can find the KPI Selection panel associated with the graph in the Timeline Report. There, you can choose which data to display in the graph. For instance, you can check or uncheck whether you want to see errors.

Additionally, by default, the data displayed is the average value, but you can choose the other statistics such as min, max, or mean. It is in this panel that we want to add a new group of KPIs. Following is an illustration of the KPI Selection Panel.

Injecting Time Series Data into the Timeline Report

To illustrate how to inject new time series data into the test report, I created a simple JMeter test. The test has one request to the demoblaze.com sample site. The results of running this test for a duration of 5 minutes are seen in the first image above.

In JMeter, it looks like this:

Step 1: Getting the Test Master Number

In order to add the time series data, you will need to know the number of the test Master. The Master is the ID of a test run. Below you can see an example of the Master ID of a test run taken from the History tab of the test.

Step 2: Converting the Time Series Data

The next item necessary is the time series data you want to inject. This data is a pair of data points: a timestamp as an Epoch date (Unix format) and a value for that date. The key to injecting the data is to understand that the timestamp is in GMT time, represented in the Unix format as a ten-digit number. So even though the timeline report is in your local time, the data in the database is actually in GMT time.

This is where many people make a mistake and use the Unix format for the local timestamp and not in GMT. If you do that, the data points won’t be seen on the graph. There is a site called EpochConverter that can be used to convert the local time/date to Unix format in GMT time.

For example, the following image shows how to convert a local timestamp of 2:34:00 p.m. to the Unix/Epoch time in GMT. Enter the time in the form and click on the “Human date to Timestamp”. Make sure that “Local time” appears in the drop-down box. The value of Epoch timestamp (highlighted) is what you would use to specify the date/time of the time series data. Keep in mind that the timestamp value must be in the range of the test duration.

Step 3: Calling the API

The method for injecting time series data is by calling the API:

https://a.blazemeter.com/api/v4/data/timeseries

This API is documented in the BlazeMeter API guide.

The command syntax is as follows:

curl 'https://a.blazemeter.com/api/v4/data/timeseries'\

    -X POST \

    -H 'Content-Type: application/json'\

    --user 'api_key_id:api_key_secret'\

    -d '{< postbody>}’

This API call uses the POST method to add the data in the <postbody> (explained below). As with all the APIs, you must provide credentials in the form of an API key.

To demonstrate how to construct the <postbody> section, I will continue with the example I began above. For my example test, I want to inject data on temperature readings (for lack of a better/more realistic example). In this case, the data section of the API call will look like this: 

-d "{'intervals': 

  'intervals': [

    {

      '_id': {

        'masterId': 61234567,

        'metricPath': "temperature|celcius",

        'ts': 1654672269245

      },

      'profileName': 'weather',

      'kpis': [

        {

          'ts': 1654672307827,

          'value': 15

        },

        {

          'ts': 1654672336176,

          'value': 17

        },…. More ts/value pairs as needed.

The time series data consists of the following:

• Intervals: This marks the start of a group time series data called ‘intervals’ because there can be several intervals (i.e, data points on the graph).
• Identifier: Intervals are followed by a dictionary of identifiers specified by an _id key. The identifier is made up of the Master id, the metric path, and the timestamp of the metric.
• Metric path: The metric path refers to the hierarchy of the data – in my example I kept it simple with just temperature and the sub-group of Celsius. I could have added another series for temperature|Fahrenheit.
• Profile name: In my case, it is ‘weather’. 
• KPIs: the timestamp/value pairs of data points.

Following is the complete curl command in Windows format for people who struggle to get the syntax right.

curl -X POST "https://a.blazemeter.com/api/v4/data/timeseries" 

-H "Content-Type:application/json" 

 --user "0......................0:c.........................................................................d" 

 -d "{\"intervals\":[{\"_id\": 

{\"masterId\": 61234567,\"metricPath\": \"temperature^|celsius\",\"ts\": 1654687770},

  \"profileName\": \"weather\",\"kpis\": [

{\"ts\": 1654687770,\"value\": 15},

{\"ts\": 1654687830,\"value\": 17},

{\"ts\": 1654687890,\"value\": 21},

{\"ts\": 1654687920,\"value\": 25},

{\"ts\": 1654687951,\"value\": 23},

{\"ts\": 1654687980,\"value\": 26},

{\"ts\": 1654688010,\"value\": 24},

{\"ts\": 1654688040,\"value\": 30}]}]}"

The Modified Timeline Report with Time Series Data

The result of running this curl command is the following modified Timeline Report:

For the sake of clarity, here is the profile section in the left-hand panel:

And, as you can see here, the plotting of the times series data is integrated with the other KPIs that were already in the report. Notice that when you click on the ‘celsius’ checkbox, then a new label is added to the x-axis of the graph as well as in the pop-up of the data points.

Generally, you would use the time series API to add data after the test has finished running. However, there is a possibility of adding time series data in real time as your test is running. If you are planning on adding data as your test is running, make sure you append the new data to the old request data as you go, as every POST will delete the previous data that was present.

Bottom Line

Augmenting the Timeline Report is something many BlazeMeter users find useful. The Timeline report is a standard report that displays basic information on the performance of the test. 

However, sometimes this is not enough, so BlazeMeter has a feature of injecting other user-provided data as a time series. This ability to inject time series data gives users the ability to customize the Timeline report according to their needs. 

Experience BlazeMeter in Action

Start your BlazeMeter testing today with a free trial.

Start testing now