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/1234You 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=johnJava 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 | |
| Sample response | |
| 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) |
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 | |
| Sample response | |
| 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 | |
| Sample response | |
| 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 |