Using the Grafana plugin to visualize RUM data

IBM® NS1 Connect® customers leveraging the real user monitoring (RUM) traffic steering solution (Pulsar) can push real-time performance and availability data from the IBM NS1 Connect® platform to Grafana to be analyzed using Grafana's dashboard and visualization tools. This plugin provides a unified view for monitoring services in your network and allows you to set up alerts if the data presents an anomaly.

Grafana supports three types of plugins. To push RUM data from the IBM NS1 Connect® platform, use a data source plugin. The data points plotted by Grafana are limited to the historical data stored in the IBM NS1 Connect® platform. In other words, the Grafana plugin does not extend how much time RUM data is queryable.

Prerequisites

  • You must have the RUM-based traffic steering solution enabled on your IBM NS1 Connect® account.
  • You must have configured data flow from community or private resources with at least one RUM (Pulsar) application with at least one active job.
  • You must have a valid IBM NS1 Connect® API key.
  • You must have a working Grafana instance and have the necessary permissions to modify its configuration.

Procedure

Step 1 - Install the NS1 Pulsar plugin in Grafana
Note: You will need write access to the configuration in your Grafana instance.
  1. Download the latest version of the plugin from https://github.com/ns1labs/grafana-pulsar-datasource.
  2. Uncompress the file and move the extracted directory into the plugin directory specified in the Grafana configuration file.
  3. Edit your local grafana.ini file and make the following changes:
    [plugins]
allow_loading_unsigned_plugins = ns1labs-pulsarmetrics-datasource
[plugin.ns1labs-pulsarmetrics-datasource]
allow_local_mode = true
  4. Restart your Grafana instance.
Step 2 - Add NS1 Pulsar as a data source
  1. In the Grafana portal, navigate to the Configuration page from the sidebar menu, and then select Plugins to view a list of available plugins.
  2. Verify that the NS1 Pulsar Metrics is included in your list of installed plugins. If you do not see it, refer to your Grafana logs and search for any relevant error message.
    Note: You may see a temporary "unsigned" warning while the plugin is in the review queue of Grafana Labs.
  3. Navigate to the Data sources tab (Configuration > Data Sources) and click Add data source.
  4. Search and select the NS1 Pulsar Metrics data source (listed under Others).

    A confirmation message indicates the data source was added successfully, and then you are redirected to the plugin configuration page.

  5. Next to API Key, enter the NS1 API key you created earlier. The API key is stored securely in the Grafana database. Once complete, click Save & test. Grafana validates that the API key can be used to pull data from the NS1 platform. If successful, a confirmation message appears.
    Note: If Grafana returns an error message, check the NS1 API key secret or verify the API key permissions to ensure they are correct.

    Click Back to return to the configured data sources. The NS1 Pulsar data source appears in the list.

    If this is the only data source you have installed, it will be labeled as default. As you configure additional plugins, you can specify one to be the default.

Step 3 - Add a new panel to the Grafana dashboard

Next, you must create a new panel in Grafana to query Pulsar data.

  1. Create a new Grafana dashboard or navigate to an existing one.
  2. Click the Add panel icon in the upper-right corner.

    The new options appear above the dashboard.

  3. Click Add a new panel.

    The screenshot above shows a sample query with data from Grafana's default data source. Your view might look different depending on your configuration.

  4. Click the drop-down menu next to Data source (on the lower left, under the Query tab) and select NS1 Pulsar Metrics. Now, all the available Pulsar applications and jobs are available for selection. Note that you can only view the applications and jobs accessible to the NS1 API key you entered when configuring the data source.
    Note: Refer to this topic to learn more about Pulsar applications and jobs.
  5. Under App, select a Pulsar application. A Pulsar application is a collection of Pulsar resources.
  6. Under Job, select a Pulsar job. A job corresponds to a single Pulsar resource (e.g., CDN, data center, cloud, etc.) being measured. The resource hosts an asset (such as a single-pixel image) to measure availability and latency when the JavaScript tag is executed upon page load.
  7. Under Metric, select a metric type (i.e., performance or availability) from the list.
  8. Under Aggregation, select one of the precalculated aggregations (min, max, avg, p50, p75, p90, p95, p99).
  9. Optionally, you can select a Geo and/or ASN to filter the data — although it's recommended to provide at least a Geo to avoid having a chart showing the global behavior of the CDN, which will only be meaningful under certain circumstances.
  10. On the right-hand sidebar, enter a Title for the new panel and adjust the panel settings and preferences as desired. You will likely want to set the Y-axis units to milliseconds.
  11. Optionally, you can specify additional queries to compare performance or availability data for multiple Pulsar applications and jobs. See below for details.
  12. When you’re ready, click Apply to keep your changes. Click Save in the upper right corner when you are done. You will exit the edit mode.
  13. Enter a name for the dashboard (e.g., NS1 Pulsar), and then click Save.

The new dashboard appears with the panel you just created. You can modify the dashboard and add more panels as desired.

Comparing RUM data in the Grafana panel

After creating a new panel in the Grafana dashboard, you can compare the performance data of two RUM (Pulsar) applications and/or jobs. To do this, configure a new panel or select an existing panel showing at least one set of RUM data.

Under the first query (i.e., “A”), click + Query.

A second query appears with additional settings.

Under the new query (i.e., “B”), select the application and job you want to compare with the first query. Now, the graph shows two data sets — one for each defined query.

Note: When adding additional queries for comparison, be sure to select the same RUM application, job, metrics, and aggregation so that you are comparing data of the same type.