View Lightstep data in Grafana

The Lightstep Observability Data Source lets you view and visualize telemetry data from Lightstep Observability directly in Grafana. Using the Lightstep data source, you can access Lightstep Observability from a Grafana chart to find the root cause of an issue, using advanced functionality like Change Intelligence.

This guide describes how to install and enable the Lightstep Observability Data Source. It also shows how to use the data source to access Lightstep from Grafana and investigate issues.

Prerequisites

You need the following to enable and use the plugin:

• A Grafana account (version 7 and greater).

  The plugin only supports graph and time series charts.

• Telemetry data reporting to Lightstep.

• Your Lightstep Project and Organization name. You can find that information in Project settings and Account management.

  

• A Lightstep API key with Viewer permissions created just for Grafana.

  Paste the key someplace safe, as you will not be able to access it again from Lightstep Observability.

Installation

Recommended: Install using the Grafana CLI

1. Install the plugin from the Grafana CLI using Grafana’s plugin installation instructions. Copy the latest release zip URL from the releases page.

   1
   2
   grafana-cli --pluginUrl https://github.com/lightstep/lightstep-observability-datasource/releases/download/v2.0.1/lightstep-observability-datasource-2.0.1.zip \
      plugins install lightstep-observability-datasource
   

   If running locally on Mac OS (arm) via Homebrew, try:

   1
   2
   3
   grafana-cli --pluginsDir /opt/homebrew/var/lib/grafana/plugins \
               --pluginUrl https://github.com/lightstep/lightstep-observability-datasource/releases/download/v2.0.1/lightstep-observability-datasource-2.0.1.zip \
               plugins install lightstep-observability-datasource
   

2. Ensure your Grafana installation is configured to allow unsigned plugins.

   This generally requires ensuring the allow_loading_unsigned_plugins value in the plugins section of grafana.ini is updated to include lightstep-observability-plugin in the list of allowed plugins.

   1
   2
   3
   4
   5
   [plugins]
   ;enable_alpha = false
   ;app_tls_skip_verify_insecure = false
   # Enter a comma-separated list of plugin identifiers to identify plugins that are allowed to be loaded even if they lack a valid signature.
   allow_loading_unsigned_plugins = lightstep-observability-datasource
   

Install directly from GitHub

1. Download the zip file for the plugin.

2. Unzip the release into your Grafana plugins directory.

   The value of YOUR_GRAFANA_PLUGINS_DIR depends on your system and how Grafana was installed. For example, it may be at /var/lib/grafana/plugins on Linux.

   1
   unzip -d [YOUR_GRAFANA_PLUGINS_DIR]/lightstep-observability-datasource lightstep-observability-datasource-X.Y.Z.zip
   

3. Ensure your Grafana installation is configured to allow unsigned plugins.

   In the plugins section of grafana.ini, make sure allow_loading_unsigned_plugins includes lightstep-observability-plugin.

   1
   2
   3
   4
   5
   [plugins]
   ;enable_alpha = false
   ;app_tls_skip_verify_insecure = false
   # Enter a comma-separated list of plugin identifiers to identify plugins that are allowed to be loaded even if they lack a valid signature.
   allow_loading_unsigned_plugins = lightstep-observability-datasource
   

4. In the Grafana plugin installation, install the Lightstep Observability (unsigned) data source. If you see only the Lightstep Metrics plugin, your installation likely has not succeeded.

   

For more information, follow the steps in the Grafana documentation for local installations.

Enable the Lightstep Observability Data Source in Grafana

After you install the plugin, follow these steps. Steps may vary slightly depending on your version of Grafana.

1. Restart the Grafana server so it can discover the new plugin.

2. In the Navigation Bar, choose Configuration, select Data Sources, and click Add data source.

   

3. Start typing Lightstep in the search field to find the Lightstep Observability data source and click Select. If you do not see the Lightstep plugin listed, please ensure it has been correctly installed or reach out to the Lightstep team for further assistance.

4. Enter your Lightstep organization and project name. If you want to use the data source with multiple projects, enter the name of each project separated by a comma into the project name field. Then paste in your Lightstep API key and click Save & Test.

   Grafana confirms that it’s connected to Lightstep.

   

You can now create dashboards and charts in Grafana using data provided by your Lightstep project.

Create Grafana charts from Lightstep Observability

With the Lightstep plugin installed, you can query your Lightstep data directly from Grafana.

1. From the Query tab of the Edit Panel, select Lightstep Observability data source from the Data source drop-down.

2. Add a query to the text input, using Lightstep’s Unified Query Language (UQL).

   Click out of the field (or press shift + Enter) to run your query.

   

3. Choose the visualization for the chart (Lightstep supports either Graph or Time Series). Click Apply to create the graph.

Investigate a deviation from a Grafana chart

Now that you have a chart in Grafana, when you notice an unexpected change in your data, you can investigate in Lightstep to rapidly find the root cause.

To investigate, click into the deviation and select Create a Notebook in Lightstep.

You’re taken to a notebook in Lightstep with your query pre-populated where you can start your investigation.

Use Change Intelligence or Trace view to further your investigation.