• Documentation
  • Tutorials
  • Case studies
  • White papers
  • Product

What's on this Page

  • RTM APIs
    • Measurement Ingestion
      • Quick ingestion over HTTP
      • Java driver
    • Raw data extraction
    • On-demand data aggregation
      • Job submission
      • Results polling
      • Automatic result comparison
  • step
  • Developer guide
  • Measurement API
Categories: DEVELOPER GUIDE API
This article references one of our previous releases, click here to go to our latest version instead.

Measurement API

Measurements are created either automatically by step (these are E2E measurements) or in a custom way within keywords and as part of the Keyword API.

RTM APIs

Performance measurements retrieval and on-demand aggregation

Measurement Ingestion

Quick ingestion over HTTP

A basic ingestion request can be sent using the following URI pattern:

curl {host:port}/rtm/rest/ingest/structured/{arbitrary_groupping_value}/{begin_timestamp}/{name}/{value}

Here is a qualified example:

curl localhost:8099/rtm/rest/ingest/structured/myMeasurementGroup/1494428139000/myMeasurementName/1234

You can also attach as much additional custom data as you wish in order to tag your measurement and perform filtering or grouping in your analysis later on. Just append semicolumn-separated key-value pairs like such (note: the “;” is here url-encoded as %3B):

curl localhost:8099/rtm/rest/ingest/structured/myMeasurementGroup/1494428139000/myMeasurementName/1234/client=127.0.0.1%3Buser=john

Java driver

Using the rtm-commons library, measurement ingestion can also be done using the class MeasurementAccessor (see method “sendStructuredMeasurement”).

<dependency>
  <groupId>ch.exense.rtm</groupId>
  <artifactId>rtm-commons</artifactId>
  <version>{rtm_version}</version>
</dependency>

The latest version available at the time this page has been written or last updated is 2.2.5.

Raw data extraction

This service is to be used in order to select and retrieve the individual measurements in the form of a paged list of data points.

Basic service description
Service Type Synchronous with paging (multiple potential HTTP calls)
Extraction request
URL /rtm/rest/measurement/find
Method POST
Required headers Content-Type: application/json; charset=UTF-8
Sample payload
{
  "selectors1": [
    {
      "textFilters": [
        {
          "key": "eId",
          "value": "5e3be2477fc50f000dd36447",
          "regex": "false"
        }
      ],
      "numericalFilters": [
        {
          "key": "value",
          "minValue": "0",
          "maxValue": "2000"
        }
      ]
    }
  ],
  "serviceParams": {
    "measurementService.nextFactor": "0",
    "aggregateService.sessionId": "defaultSid",
    "aggregateService.granularity": "auto",
    "aggregateService.groupby": "name",
    "aggregateService.cpu": "1",
    "aggregateService.partition": "8",
    "aggregateService.timeout": "600"
  }
} 
Sample response
{
  "status": "SUCCESS",
  "metaMessage": "ok",
  "payload": [
    {
      "_id": {
        "timestamp": 1546592852,
        "machineIdentifier": 3106649,
        "processIdentifier": 11,
        "counter": 8595278,
        "date": 1546592852000,
        "time": 1546592852000,
        "timeSecond": 1546592852
      },
      "eId": "5c2f22522f6759000b832716",
      "rnId": "5c2f22522f6759000b83273c",
      "name": "OpenChrome",
      "rnStatus": "TECHNICAL_ERROR",
      "type": "keyword",
      "value": 1743,
      "begin": 1546592850874
    },
    {
      "_id": {
        "timestamp": 1546614005,
        "machineIdentifier": 3106649,
        "processIdentifier": 11,
        "counter": 8688719,
        "date": 1546614005000,
        "time": 1546614005000,
        "timeSecond": 1546614005
      },
      "eId": "5c2f74f02f6759000b8493c3",
      "rnId": "5c2f74f32f6759000b84943d",
      "name": "MonitorStep",
      "rnStatus": "PASSED",
      "type": "keyword",
      "value": 1789,
      "begin": 1546614003351
    }
  ]
} 
Detailed payload description
selectors1 a named top-level object representing the selection criteria to apply to the central dataset, and containing an array of selector
selector an unnamed object present within the array “selectors”, represents a combination of textual and numerical filters, contains a textFilters array and a numericalFilters array. A logical OR operation will be assumed between selectors if multiple selectors are present in the array
textFilters a named array of textFilter representing a set of text-based matches to apply as a selection criteria. A logical AND operation will be assumed between filters if multiple filters are present in the array
textFilter an unnamed object present within the textFilters array comprising of a named key element, a named name element and a named regex element
key provides the name of the measurement’s field against which the filter should be applied
value provides the value to be matched for selecting a measurement
regex a boolean used to determine whether the value field is to be interpreted as a regular expression or a static string value
numericalFilters a named array of numericalFilter representing a set of numerical order-based matches to apply as a selection criteria. A logical AND operation will be assumed between filters if multiple filters are present in the array
numericalFilter an unnamed object present within the numericalFilters array comprising of a named key element, a named min element and a named max element
key provides the name of the measurement’s field against which the filter should be applied
min provides the minimum numerical value serving as lower boundary for selecting a measurement
max provides the maximum numerical value serving as higher boundary for selecting a measurement
serviceParams a named top-level object containing additional parameters potentially relevant to the service’s execution
measurementService.nextFactor the result page number to be retrieved (works in combination with the centrally defined client.MeasurementListView.pagingValue value, which defines how many measurements should be contained in each page of results
other parameters other parameters might be technically required (refer to the example above and use it as a template), but will be ignored for this specific service call
Detailed response description
status The status of the retrieval attempt: either SUCCESS or ERROR.
metaMessage A potential warning or additional bit of meta information regarding the service’s execution.
payload A named array containing the returned individual measurements
measurement an unnamed object representing each individual measurement (data point). The keys and values may vary based on the configuration of RTM but by default, and when combined with step, the attributes listed below will be found.
_id A set of technical attributes recorded at insertion time and allowing for the unique identification of the measurement
eId The execution id originating from step
begin The time origin of the measurement (start time)
name The name of the transaction/measurement (potentially a keyword in step)
value The recorded numerical value of the measurement (duration in step)
rnStatus The measurement’s status, inherited from the keyword (step only)
rnId The report node id mapped to the keyword’s execution report in step’s execution results (step only)
type usually either “keyword” or “custom”, marks a difference between automatic and custom measurements (step only)
You will potentially need to make multiple calls to the service in order to retrieve all of the data for a certain selection (depending on the number of results and hence, result pages produced). For instance, with the default value of 100 for parameter “client.MeasurementListView.pagingValue” (in rtm.properties), if your query yields 315 measurements, you will need to make 4 distinct calls with the following values for the parameter “measurementService.nextFactor”: 0, 1, 2, 3

On-demand data aggregation

This service is to be used in order to start an aggregation job in rtm and retrieve the resulting series of aggregated data points and various default metrics. This is an asynchronous service, meaning that the client is first supposed to submit a job and then poll the results until the job has completed.

Service description
Service Type Asynchronous (one HTTP request type to start job, and one to poll results)

Job submission

In this first call, the job inputs are sent to a specific url and the job’s execution ensues.

Job submission request (1st call)
URL /rtm/rest/aggregate/get
Method POST
Required headers Content-Type: application/json; charset=UTF-8
Sample payload
{
  "selectors1": [
    {
      "textFilters": [
        {
          "key": "eId",
          "value": "5e3be2477fc50f000dd36447",
          "regex": "false"
        }
      ],
      "numericalFilters": [
        {
          "key": "value",
          "minValue": "0",
          "maxValue": "2000"
        }
      ]
    }
  ],
  "serviceParams": {
    "measurementService.nextFactor": "0",
    "aggregateService.sessionId": "defaultSid",
    "aggregateService.granularity": "auto",
    "aggregateService.groupby": "name",
    "aggregateService.cpu": "1",
    "aggregateService.partition": "8",
    "aggregateService.timeout": "600"
  }
} 
Sample response
{
  "status": "SUCCESS",
  "metaMessage": "Stream initialized. Call the streaming service next to start retrieving data.",
  "payload": {
    "streamedSessionId": "6551715b-55b2-4d86-97ea-2ac694e006bf"
  }
} 
Detailed payload description
selectors1 a named top-level object representing the selection criteria to apply to the central dataset, and containing an array of selector
selector an unnamed object present within the array “selectors”, represents a combination of textual and numerical filters, contains a textFilters array and a numericalFilters array. A logical OR operation will be assumed between selectors if multiple selectors are present in the array
textFilters a named array of textFilter representing a set of text-based matches to apply as a selection criteria. A logical AND operation will be assumed between filters if multiple filters are present in the array
textFilter an unnamed object present within the textFilters array comprising of a named key element, a named name element and a named regex element
key provides the name of the measurement’s field against which the filter should be applied
value provides the value to be matched for selecting a measurement
regex a boolean used to determine whether the value field is to be interpreted as a regular expression or a static string value
numericalFilters a named array of numericalFilter representing a set of numerical order-based matches to apply as a selection criteria. A logical AND operation will be assumed between filters if multiple filters are present in the array
numericalFilter an unnamed object present within the numericalFilters array comprising of a named key element, a named min element and a named max element
key provides the name of the measurement’s field against which the filter should be applied
min provides the minimum numerical value serving as lower boundary for selecting a measurement
max provides the maximum numerical value serving as higher boundary for selecting a measurement
serviceParams a named top-level object containing additional parameters potentially relevant to the service’s execution
aggregateService.granularity the interval size to use for grouping datapoints. Either “auto” (optimized for human-readability and a series of 20 datapoints), “max” (aggregation over the entire dataset, aka summary mode: only 1 datapoint) or a numerical value in milliseconds
aggregateService.groupby the dimension(s) to use for merging or splitting data points into multiple series (by default: “name”), if multiple dimensions are to be used, they are separated by a semicolon, for example: “eid;name”
aggregateService.cpu the number of threads to start the job with (resulting in a potential maximum number of CPU cores to be monopolized by the job), default is “1”
aggregateService.partition an optimization when cpu > 1, defines how many sub-tasks are to be created in each interval before being processed by the job’s threads
aggregateService.timeout a maximum duration value allowed for the job to run (in seconds), default: 600, i.e 10 minutes
other parameters other parameters might be technically required (refer to the example above and use it as a template), but will be ignored for this specific service call
Detailed response description
status The status of the retrieval attempt: either SUCCESS or ERROR.
metaMessage A potential warning or additional bit of meta information regarding the service’s execution.
payload A named array containing identification data of the aggregation result collection
streamedSessionId The unique identifier corresponding to the job’s result collection. Will be needed to poll the results (see next section).

Results polling

In this second call, the results are polled until the completion flag flips to “true”.

Results polling request (2nd call)
URL /rtm/rest/aggregate/refresh
Method POST
Required headers Content-Type: application/json; charset=UTF-8
Sample payload
{
  "streamedSessionId" : "6551715b-55b2-4d86-97ea-2ac694e006bf"
}
Sample response
{
  "status": "SUCCESS",
  "metaMessage": "Found stream with id=6551715b-55b2-4d86-97ea-2ac694e006bf.
  Delivering payload at time=1581009955408",
  "payload": {
    "stream": {
      "streamData": {
        "1546592850874": {
          "MonitorNexus": {
            "tpm": 0.013650449,
            "avg": 8848,
            "min": 5362,
            "max": 17840,
            "tps": 0.00022750748,
            "cnt": 261,
            "sum": 2309578,
            "80th pcl": 9099,
            "50th pcl": 8776,
            "90th pcl": 9304,
            "99th pcl": 10479
          },
          "simpleHttpRequestKW": {
            "tpm": 0.05005165,
            "avg": 95,
            "min": 18,
            "max": 439,
            "tps": 0.0008341941,
            "cnt": 957,
            "sum": 91851,
            "80th pcl": 92,
            "50th pcl": 92,
            "90th pcl": 92,
            "99th pcl": 385
          }
        }
      },
      "id": {
        "streamedSessionId": "478b9294-eb86-4f25-9fde-28ee322f3fca"
      },
      "complete": false,
      "clone": false,
      "durationMs": 6,
      "compositeStream": false
    },
    "metricList": [
      "90th pcl",
      "80th pcl",
      "max",
      "50th pcl",
      "avg",
      "sum",
      "99th pcl",
      "tps",
      "cnt",
      "min",
      "tpm"
    ]
  }
} 
Detailed payload description
streamedSessionId A named top-level string value identifying the job execution results collection. Originates from the /get call respone (see previous section).
Detailed response description
status The status of the retrieval attempt: either SUCCESS or ERROR.
metaMessage A potential warning or additional bit of meta information regarding the service’s execution.
payload A named array containing the aggregation results (requested series)
stream A technical wrapper for the returned data
stream A technical wrapper for the returned data
{{timestamp}} The time origin of the aggregation interval (beginning of the interval), as a key pointing to an embedded document which will contain all of the series in that interval
{{series name}} The name of the series built in the time interval, as a key pointing to an embedded document which will contain all of the metrics computed for that series in that interval
tpm the number of measurements per minute found for that series and in that interval
avg the mean value of the measurement’s “value” field for that series and in that interval
min the minimum value of the measurement’s “value” field for that series and in that interval
max the maximum value of the measurement’s “value” field for that series and in that interval
tps the number of measurements per second found for that series and in that interval
cnt the number of measurements found for that series and in that interval
sum the sum of all the measurement’s “value” field for that series and in that interval
50th pcl the 50th percentile mark (aka median) computed over all the measurement’s “value” field for that series and in that interval
80th pcl the 80th percentile mark computed over all the measurement’s “value” field for that series and in that interval
90th pcl the 90th percentile mark computed over all the measurement’s “value” field for that series and in that interval
99th pcl the 99th percentile mark computed over all the measurement’s “value” field for that series and in that interval
In order to retrieve a complete result collection, you need to keep polling the refresh service until the completion attribute “payload.stream.complete” of the response payload indicates “true”.

Automatic result comparison

Coming soon.

See Also

  • Scheduler
  • User Preferences
  • Self Monitoring Dashboard
  • Import/Export entities
  • Requirements
  • Getting Started
    • Overview
    • Quick setup (install)
    • Quick setup (SaaS)
    • My first Execution
    • Browser automation
    • Real-world scenario
    • Scaling out
  • Whats new?
    • Release notes
    • Roadmap
    • Weekly news
  • Admin guide
    • Database installation
    • Controller installation
    • Agent installation
    • Requirements
    • Backup & Restore
    • Housekeeping
    • Migration
    • Customization
    • Project management
    • Admin Views
    • Troubleshooting
    • Encryption Manager
  • User guide
    • Keywords
    • Plans
    • Executions
    • Notifications
    • Parameters
    • Dashboards
    • Monitoring
    • Scheduler
    • User Preferences
    • Event Broker Monitor
    • Executable bundles
    • Import/Export entities
  • Developer guide
    • Dev Overview
    • Keyword API
    • Measurement API
    • step client API
    • Event Broker API
  • Plugins
    • .NET agent
    • cypress Plugin
    • Node.js agent
    • ALM
    • Azure DevOps
    • Async packages
    • JMeter
    • SoapUI
    • PDF and Image compare
    • Artifact repository connector
    • Analytics and external DBs
  • Resources
    • Tutorials
    • Case Studies
    • White papers
    • Libraries
Step Logo
    • Documentation
    • Tutorials
    • Case studies
    • White papers
    • Product
    • Getting Started
    • Whats new?
    • Admin guide
    • User guide
    • Developer guide
    • Plugins
    • Resources