Task flow in using the KairosDB UI

You can perform tasks in sequence to use the KairosDB UI to query the data store and graphically view stub metrics for virtual services.
You can perform the following tasks:

Launching the KairosDB UI

To view the query and the graph of the metrics for the stubs running on HCL Quality Server, you must launch the KairosDB UI.

About this task

You must complete the prerequisite tasks before you launch the KairosDB UI. You must use a browser on the same system that is running the HCL Quality Server instance.

Procedure

  1. Use the URL http://localhost:7828/ to launch the KairosDB UI.

    The KairosDB UI is displayed as shown in Figure 1.

    Figure 1. The KairosDB UI
    image of the kairosdb UI.
    Note: The mandatory fields to be selected are marked with an Asterisk (*).
  2. Before you generate a graph for the metrics, complete the following steps:
    1. Select a time range.
    2. Select one or more metrics.

    You can then view the graph for the details you specified. You can also add Tags or Aggregators to generate custom views for the data values of the metrics.

Results

You have successfully launched the KairosDB UI. However, you must configure more settings to view the graph.

What to do next

You must continue to select a time range for the data points stored.

Selecting a time range and the time zone

You must first select the time range during which the KairosDB collected the metrics for the stubs. The time would correspond to the time when the stubs ran on HCL Quality Server.

About this task

You can also find the time when the stubs ran by using the Usage page accessed from HCL Quality Server. For more information, see Viewing usage statistics of virtual services in HCL Quality Server.

Procedure

Selecting a time range

  1. Launch the KairosDB UI. See Launching the KairosDB UI. The Time Range panel in the UI is as shown in Figure 2.
    Figure 2. The Time Range panel
    image of the time range panel in the UI.
  2. In the Time Range panel, select one from the following options:
    1. Select an Absolute range.

      You can specify a definite time range. You must select the date and time from when the stubs were run on Rational® Test Control Panel in the From field by clicking the field and selecting the date. You can set the time by using the slider against Hour, Minute, second, or millisecond. Click Done to set the date and time. Optionally, you can set the date and time in the To field for the end time for this range. If not, the time from the set time until the current time will be considered as the time range.

    2. Select a Relative range.

      You can specify a relative time range. You must enter a number in the first box and select the unit from the list of options that includes Years, Months, Weeks, Days, Hours, Minutes, or Seconds. For example, you can select the relative time as 1 Week ago, from the current date. Optionally, you can set the relative time in the To field for the end time for this range. For example, if you want to select the time as the previous two months, you can set 3 Months ago, in the From field and 1 Month ago, in the To field.

Selecting a time zone

  1. Specify the Time Zone by selecting one from the list or let the Default time zone remain unchanged. The default time zone corresponds to the server time zone on which the HCL Quality Server runs.

Results

You have successfully configured the time range and the time zone by using the KairosDB UI.

What to do next

You must continue with selecting the metrics for which you want to view the graph.

Selecting metrics

You must select metrics for the stubs you ran to include them in the KairosDB query.

Before you begin

You must have completed the prerequisite tasks before you launch the KairosDB UI. You must use a browser on the same system that is running the HCL Quality Server instance. You must have launched the KairosDB UI and configured the time range before you select the metrics.

Procedure

  1. From the list in the Name field, select any one metric. For example, rtvs.stub.evt_match. See Figure 3.
    Figure 3. Selecting metrics in the KairosDB UI
    image showing selecting a metric in the UI
    The following metrics are supported starting from V9.2.1 onwards:
    • Events passed through (rtvs.stub.evt_passthrough). You must have set the pass-through configuration for the stubs. See Configuring stub pass-through behavior.
    • Events that match input filters and are processed (rtvs.stub.evt_match).
    • Events handled by a stub (rtvs.stub.evt_in).
  2. Set the number of records for which you want to view the metrics in the Limit field. For example, 100.
  3. You can view the graph of the metric by clicking Graph or you can proceed to view the graph after you group metrics and add aggregators to the grouped metrics.
  4. You can add more than one metric to the query. To add a metric, click the add metric (image of the add icon) icon and complete the steps 1 and 2.

Results

You can view the basic graph for the query or you can customize the view by grouping the data points and assigning aggregators to the grouped metrics.

A sample of the graph generated by the query for a single metrics is shown in Figure 4. The graph shows the different stubs grouped with their names as tags.
Figure 4. Graph showing the stub metric values
image of the basic graph showing the stub metric values.
Another sample in Figure 5 shows the graph for the different metrics collected for the stubs. The metrics queried include rtvs.stub.evt_in, rtvs.stub.evt_match, and rtvs.stub.evt_passthrough.
Figure 5. Graph of the three stub metrics
image of the basic graph showing the three stub metric values.

What to do next

You can continue to group the metrics.

Grouping metrics

You can group the data points collected for the metrics in the database into groups and assign aggregators to the grouped data so that the data values can be presented in a simplified graph.
You can group the data in the following ways:
  • By tags
  • By a time range
  • By value
Note: Grouping by a time range or value can slow down the execution of the query and loading of the graph.

You can assign more than one group to a metric. For example, you can group by a tag and time range so that you can see the grouped data points in a simplified view in the graph.

Grouping by tags

  1. To add a grouping item, click the image of the add icon icon adjacent to Group By label.
  2. Select Tags from the list. The screen shown in Figure 6 is displayed.
    Figure 6. The Group by panel
    image of the group by panel.
  3. Enter the tags you want to select for the data points in the Tags field. You can also use the Search icon (image of the search icon) and add the tags from the list displayed for the metric. See Figure 7.
    Figure 7. Adding Tags to the group
    image of the group by panel.

You can add multiple Group by items for the same metric by completing the tasks in Step 1 to Step 3.

You can view the graph for the query created by clicking Graph.

A sample of the graph generated by this query is shown in Figure 8. The graph shows the different stubs grouped with their names as tags.
Figure 8. Graph showing metric values grouped by tag name
image of graph grouped by tag name.

Grouping by time

  1. To add a grouping item, click the image of the add icon icon adjacent to Group By label.
  2. Select Time from the list. The screen shown in Figure 9 is displayed.
    Figure 9. The Group by time panel
    image of the group by time panel.
  3. Set the number of data points you want to be grouped in the Target Size field. For example, you can set the grouping of the data points for every 30 Seconds.
  4. Select the time value from the list. See Figure 10 for the time values you can select.
    Figure 10. Time-values for selection
    image of the time values available for selection.
  5. Set the number of records for which, you want to view the metrics in the Count field. For example, 10.

You can view the graph for the query created by clicking Graph.

A sample of the graph generated by this query is shown in Figure 11. The graph shows the different stubs grouped based on the time interval of 30 seconds.
Figure 11. Graph showing metric values grouped by time
image of graph grouped by time.

Grouping by value

  1. To add a grouping item, click the image of the add icon icon adjacent to Group By label.
  2. Select Value from the list. The screen shown in Figure 12 is displayed.
    Figure 12. The Group by value panel
    image of the group by value panel.
  3. Set the data value you want the data points within or equal to that value that is to be grouped in the Target Size field.

You can view the graph for the query created by clicking Graph.

A sample of the graph generated by this query is shown in Figure 13. The graph shows the different stubs grouped based on their data values equal to or less than 2.
Figure 13. Graph showing metric values grouped by value
image of graph grouped by value.

Assigning aggregators

After you group the data points, you can assign aggregators to the grouped data points so that the selected operation is performed on the data points. For example, you can count the number of data points that exist in a 10-minute time period.

Procedure

  1. To add an aggregator, click the image of the add icon icon adjacent to Aggregators. The screen shown in Figure 14 is displayed.
    Figure 14. The Aggregators panel
    image of the aggregators panel.
  2. Select an aggregator from the list. The list shown in Figure 15 is displayed.
    Figure 15. List of aggregators
    image of the list of aggregators.
  3. Enter the number of data points you want to group in the Sampling field.
  4. Select the time value from the list for the grouping.
  5. Optional: Click the Align start time check box if the grouped data points must have the same starting point in the graph.
  6. Click Graph to view the graph for the query created.

Results

The graph is displayed for the query you created.

Figure 16 shows a sample graph displayed when the query is set up by grouping by the tag name and an aggregator (Sum) is set to sum the data values of the stub metric (rtvs.stub.evt_in) in a 30-second interval.
Figure 16. Graph showing metric values grouped and an aggregator assigned
image of the graph of a metric grouped and an aggregator assigned

Assigning tags

You can use Tags in your query for the selected metric so that the result displays the data points with the selected tags and their values specified.

Procedure

  1. To add a tag, click the image of the add icon icon adjacent to Tags. The screen shown in Figure 17 is displayed.
    Figure 17. The Tags panel
    image of the tags panel.
  2. Select the name of the tag from the list under Name.
  3. Select and associate a value from the Value list. For example, select Name for the Tag name and select the stub name as the Value.
    Note: Depending on the state of the stub configured, you can select the options for the attributes you want to be used in the graph for the selected metric. You can assign one or more tags to a metric.
  4. Click Graph to view the graph for the query created.

Results

The graph is displayed for the query you created.

Figure 18 shows a sample graph that is displayed when the query is set up for a stub metric (rtvs.stub.evt_in) and the tag is set for the name and the value chosen for the stub.
Figure 18. Graph showing the stub metrics tagged for the name and value
image of the graph of a stub metric tagged by name and value.

Viewing the graph

You can view the graph for the query you created using the KairosDB UI. You can view the graph at any stage of the query you are creating.

Before you begin

Before you can view the graph in the KairosDB UI, certain tasks are completed:
  1. You have set up the database to collect the data points for the stub metrics, published stubs, and ran tests in HCL OneTest API.
  2. You have launched and set the time range in the KairosDB UI.
  3. You have selected the metrics for which you want to view the graph.

Procedure

Viewing a basic graph

  1. In the KairosDB UI, click Graph. The graph shown in Figure 19, as an example, is displayed for a query for the stub metrics in the selected time range.
    Figure 19. Graph of the stub metrics
    image showing a simple graph of the stub metrics.

Viewing a graph

  1. When you create a query for multiple stub metrics with one of the metrics that is grouped by tags, and an aggregator (SUM) is assigned, and you click Graph, the graph displays. As an example, see the graph displayed in Figure 20 for such a query.
    Figure 20. Graph of the metrics query
    image of the graph for the stub metrics queried.

Scaling and adding the Y-axis

  1. When you create a query with multiple stub metrics, the Scale and add Y-axis field is displayed. Select this option to add the Y-axis and scale the data series. An example graph is shown in Figure 21. You can compare the displayed graph to the graph in Figure 20 to see how the display differs because of the scaling and with the Y-axis added.
    Figure 21. Graph of the metrics query with scale and Y-axis added
    image of the graph for the stub metrics queried.

Using the zoom feature

  1. You can zoom in and enlarge part of the graph by clicking on the graph and selecting an area you want to zoom in on as shown in Figure 22.
    Figure 22. View of the zoomed part in the graph
    Image of the graph showing the zoomed part.
  2. To reset the graph to its original size, click Reset Zoom.

Viewing data point details

  1. You can view the details of the data point by hovering over the data point in the graph as shown in Figure 23.
    Figure 23. Hovering over a data point
    view of the hover message displayed for a data-point.

Viewing and saving the query

After you create your query by using the KairosDB UI, you can view the query and save it to the local folder that you can use later to reload the query in the KairosDB UI.

Procedure

Viewing the query

  1. Click Show Query to view the query you created by using the KairosDB UI. You can view the query in the JSON format or as a JS Object by selecting the appropriate button in the displayed query.

    The query is displayed as shown in the following sample.

    image of the query box

Saving the query

  1. To save the query to your local folder, click Save.

    You can save the query as a CSV file or a JSON query text file by clicking the appropriate button in the dialog displayed.

  2. Navigate to the folder you want to save the file in, provide a name for the file, and then click Save.

Results

You can save your query as a JSON query text file that you can use later in the HTTP requests to get the data points and their values in the HTTP response.

What to do next

You can retrieve the data points from the KairosDB data store by using the HTTP requests, GET or POST.

Using the saved JSON request

You can use the saved JSON query with an HTTP POST or HTTP GET to retrieve the raw data points and their values from the KairosDB data store.

Before you begin

You must have saved the query you created as a JSON text file.

About this task

You can retrieve the metrics data points from the KairosDB data store by using the JSON query you saved. Apart from the HTTP request, you can also use the REST APIs to query the KairosDB to fetch details about the metrics, tags, metric data points, and so on. For more information about the KairosDB REST API, see KairosDB REST API.

Procedure

  1. Use either of the following HTTP request types to request the KairosDB data store from a browser or test:
    1. HTTP POST
    2. HTTP GET
  2. Use the URL http://localhost:7828/api/v1/datapoints/query to send the request.
  3. For HTTP POST, place the JSON query in the body of the request.
  4. For HTTP GET, there is no message body, the JSON query is appended to the URL in the form of a query string. Encode the JSON query in HTML format as shown in the following example:

    http://localhost:7828/api/v1/datapoints/query?query=%7B%22metrics%22

Results

The response to the HTTP GET or HTTP POST request returns the data points and their values in the JSON format.

Feedback