Create and manage dashboards

The functionality in this topic is for unified dashboards and not dashboards for Streams.

You can monitor both your metric and span data by adding charts to unified dashboards based on queries to your telemetry data. Dashboards can contain any number of charts from both metric and span data.

For many metrics received from AWS CloudWatch Metric Streams or from a metric integration that uses the OTel Collector, you can create pre-built dashboards with a click of a button. You can also create dashboards manually by adding charts with custom queries to your telemetry data.

Once created, you can apply global filters and change the reporting time period. You can also create sections then drag and drop the charts to rearrange the dashboard, add labels, and export the dashboard to Terraform.

Once your dashboard is created, you can use it to:

• Create an alert from a dashboard chart
• Start your investigation by adding a chart to a notebook
• Use Change Intelligence to uncover correlations to any anomalies you are seeing

Using Terraform? You can use the Lightstep Terraform provider to create and manage your dashboards and charts. You can also use it to export existing dashboards into the Terraform format.

Use pre-built dashboards

As a starting point, you can use our pre-built dashboards for AWS CloudWatch Metric Streams metrics or for a metric integration that uses the OTel Collector. Once the dashboard builds, you can edit it to add additional charts, change chart queries, rearrange the charts, and more.

1. From the navigation bar, click Dashboards.

2. Click Create a pre-built dashboard.

   The side panel lists the available pre-built dashboards for the different metric integrations. Choose the integration you need.

   Pre-built dashboards are not available for all AWS and Collector integrations.

   

The dashboard displays a number of pre-built charts. You can edit the dashboards and add or edit the charts as needed.

Manually create a dashboard

This image shows how to create a dashboard. The steps below describe the procedure in more detail.

1. From the navigation bar, click Dashboards.

2. Click Create a custom dashboard to access a new, blank dashboard.

3. Click New Dashboard and Add a description to rename and give details about your dashboard.

   The description appears on the dashboard and Dashboard List view. The description can be up to 256 characters, and it supports Markdown. Here’s an example:

   1
   2
   3
   4
   5
   6
   7
   8
    Use this dashboard to monitor and identify issues with Lightstep's customer experience.
    Have questions?
    Ask in [#customer-experience](https://lightstep.com/).
   
    Docs:
   
    - [Runbooks](https://lightstep.com/)
    - [Troubleshooting](https://lightstep.com/)
   

You’re now ready to add charts to the dashboard.

You can also add a chart to the dashboard from the Service Directory view.

Edit a dashboard

You can add labels apply filters and global time periods to all the charts. You can also clone and delete dashboards and charts, rearrange charts, and share the dashboard with other Lightstep Observability users.

Add sections

You can organize your dashboard by adding named sections.

This image shows how to add a section. The steps below describe the procedure in more detail.

1. At the top of the page, click Add a section. The new section is placed at the bottom of the dashboard.

2. By default, the section is named New Section. Click into the title to rename it.

3. The first blank chart is added for you. Click on it to create your query and configure you chart.

4. To add more charts, click Add a chart. To rearrange charts, click the title of a chart to drag and drop it into a section.

5. To move a section, click the More ( ⋮ ) icon to move it up or down the dashboard. You can also expand and collapse sections from here.

6. When you delete a section, you can choose to delete just the section (the charts remain in the same place in the dashboard), or you can remove the section and its charts.

Rearrange and resize charts

You can move charts added to a dashboard by dragging and dropping them. Hover over a chart title. When the cursor turns into a hand, drag and drop the chart into its desired location.

You can resize a chart by hovering over the lower right-hand corner and dragging to the size you need.

Add labels

A dashboard can be labeled with information like team or service name, making it easier to surface useful metadata, find dashboards using labels you care about, and discover related dashboards that use the same labels.

To add a label:

1. Click Add labels.

2. Start typing to add a key:value pair.
   Autocomplete helps you find and select labels that have already been created.

   Although you can enter just a value, best practice is to use key:value pairs for easier maintenance and governance.

3. Click out of the field to apply the label.

Note the following syntax requirements:

• Keys must start with a lowercase letter
• Keys and values must be UTF-8
• After the first letter, keys and values can contain
  • lowercase letters
  • numeric characters
  • underscores
  • colons (words before the first colon are always considered the key)
  • dashes
  • international characters
  • emojis
• A key can contain 1-128 characters
• A value can contain 1-255 characters
• A dashboard can contain up to 40 labels

Labels are displayed on the dashboard and in the Dashboard list view. You can also add labels from here by clicking the information icon to open the side bar.

Apply global filters

You can change the data reported on in the dashboard by applying global filters based on available attributes (tags/labels) from your metrics and spans. For example, say you have these charts in your dashboard.

You hear that the customer ProWool is experiencing issues accessing your app. You can filter the charts to show just data from that customer.

Global filters only affect your view - they are not persisted.

To add global filters, click Apply filters and choose the attributes for your filter. You can select from the list or type in a key/value pair.

When adding multiple filters, Lightstep narrows down your choices based on attributes available after the previous filter. Multiple selections use AND to join filters.

Global filters and span charts

When you add a global filter, you’re changing the query for each chart on the dashboard. If a chart is using a Stream to retain a span query and you apply a global filter, it’s considered a new query that is not retained (you will only see data currently in the retention window). If you add a chart with a Stream’s retained query to a dashboard that uses global filters, the query is retained as a Stream without those filters applied.

Change the reporting time range

By default, Lightstep Observability shows data from the last hour.

To change a dashboard’s time range, click the time picker drop-down and:

• Set relative time ranges in minutes, hours, days, or weeks.
• Enter custom time ranges.

To help you explore data, the time picker saves your custom time ranges and shows them under Recently used. You can also click the < > controls next to the drop-down to move back and forward in time.

Changing the time period only affects your view - the change isn’t persisted. {: .tip}

Data may not be available for the time range you select, based on the type of data and your data retention policy.

Clone a dashboard

There are two ways to clone an entire dashboard:

• In the dashboard, click ⋮, select Clone, and click Clone in the dialog.

• In the Dashboard List view, click ⋮ next to the relevant dashboard, select Clone, and click Clone in the dialog.

Cloned dashboards do not copy over the global filters and they reset to the default time period of the last 60 minutes.

Clone a chart on a dashboard

Follow these steps to clone a chart on a dashboard:

1. On the chart, click ⋮ and select Clone.
2. In the dialog, update the chart name and click Clone. The cloned chart appears at the bottom of your dashboard.

Cloned charts use any global filters and the time period set for the dashboard.

Delete a chart from a dashboard

Follow these steps to delete a chart:

1. On the chart, click ⋮ and select Delete.
2. In the dialog, click Yes, delete.

Deleting a chart from a dashboard deletes it from everyone’s view of the dashboard.

Delete a dashboard

You can delete a dashboard from either the dashboard itself or from the Dashboard list. Deleting a dashboard also deletes all charts created for it.

To delete it from the dashboard, click ⋮, select Delete, and click Yes, delete in the dialog.

To delete it from the list view, click ⋮ for the dashboard, select Delete, and click Yes, delete in the dialog.

Share a dashboard

Lightstep creates a short link that you can use to share a dashboard. Any filters or time ranges applied to the dashboard are maintained when the other person visits the link.

To get the short link, click the Share dashboard icon and copy the URL.

Export a dashboard to Terraform

If you use Terraform to manage your dashboards, a common use case is to create a “baseline” dashboard in the Lightstep UI and then export it to Terraform to create and manage new dashboards. Creating a dashboard in the UI is easier and more intuitive than working in a Terraform configuration file. When you export the dashboard to a Terraform file, you can then clone it and edit the file to create new dashboards, for example by changing the individual queries behind the charts.

To export a dashboard to Terraform, click the More ( ⋮ ) icon and choose Export to Terraform. The tf config file can then be downloaded to any local directory.

View a single chart

To get a better look at a chart on a dashboard, you can enlarge it. Hover over the chart and click the Expand chart icon.

The chart opens in the editing view with the query builder collapsed. Click Query to open the builder and edit the query.

If the chart contains multiple queries or queries and a formula, you can toggle their display on and off below the chart.

The toggle selection is not persisted to the dashboard.

Manage dashboards

You manage all your dashboards from the Dashboard view. By default, dashboards are listed in alphabetical order.

Sorting and dashboard favorites are saved only for a user. Other users will not see your sort or favorites.

Sort dashboards

You can sort the dashboards by any column.

Search for a dashboard

Use the Search field to find a dashboard. You can search by name, date, type, or creator’s name.

Favorite a dashboard

On the Dashboard list page, click the star to favorite a dashboard. Favorited dashboards always appear at the top of the dashboard list.

Create an alert from a dashboard chart

You can create an alert from a chart, but because alerts require a specific structure, not all charts can be used to create one. If your query contains a group-by, you will not be able to create an alert (the option is disabled). For queries that don’t meet other requirements, you’ll be able to edit the query on the Alert Configuration page.

Creating an alert from a span query automatically creates a Stream.

Follow these steps to create an alert from a chart:

1. Hover over the chart in the dashboard, click the More ( ⋮ ) icon, and select Create an alert.

   The Alert Configuration page opens in a new tab using the query from the original chart. A banner describes the edits needed to create a valid alert. Fields in violation are highlighted.

2. Fix the violations.

3. By default, the title is the same as the original chart. You can change it and you can add a description, if needed.

4. Continue creating the alert.

Add a chart to a notebook

You can add to a notebook for when, during an investigation, you want to be able to run ad hoc queries, take notes, and save your analysis for use in postmortems or runbooks. Notebooks allow you to view metric and trace data from different places in Lightstep Observability together, in one place.

To add to a notebook, click Add to notebook and search to choose an existing notebook or create a new notebook.

When you add to a notebook, a chart is created using the same query. The annotation is a link back to the original, so you can quickly return to the origin of your investigation.

Learn more about notebooks.

Use Change Intelligence

When you notice an issue on the dashboard, you can use Change Intelligence to help determine what caused the change in performance. For metric data, Change Intelligence looks at traces that include spans from key operations on the service that emitted the metric. For span data, it searches traces that match the chart’s query. In both cases, Change Intelligence surfaces the attributes that appeared in traces with performance issues occurring at the same time as the spike in the chart.

You can’t use Change Intelligence with big number charts.

To run Change Intelligence, click Analyze deviation or click directly in the chart and select Analyze deviation.

Change Intelligence opens in the side panel, where you can begin your investigation. You can also click View full Change Intelligence to navigate to the expanded view.

Follow these instructions to get started.