When you are in a metrics performance investigation, you often need to run ad hoc queries and share findings with your team. Instead of creating “throw-away” dashboards, Lightstep provides notebooks that allow you to create queries on the fly, add text blocks, and share with anyone with a Lightstep account. Notebooks view

Metric charts in a notebook behave the same as charts in a dashboard. You use the query builder to create the chart and filter the data. You can also run Change Intelligence directly from a notebook.Run Change Intelligence

About Notebooks

You access notebooks from the Notebook icon in the navigation bar. Notebook icon in nav bar

Existing notebooks are listed in the sidebar in the order they were created (latest on top). You can see when the notebook was last edited and by who.

You can use the Search field to find a notebook by searching on name or user.

You can create notebooks from existing dashboards or charts in a dashboard or alert, or you can create them from the notebook view.

When to Use Notebooks

Notebooks are helpful anytime during an investigation when you want to create ad-hoc queries. They are also useful when you want a record of your investigation for postmortems or runbooks.

Here are some examples of how you might use notebooks:

  • Ad-hoc queries: You can build ad-hoc queries in a notebook and compare the charts and run Change Intelligence from there.
  • Collaboration: When your team needs to collaborate during an investigation, you can each add your own charts and text blocks to the notebook and run Change Intelligence, all working with the same data.
  • Postmortems and runbooks: When you use notebooks during an investigation, you can add your steps to resolution to the notebook once you’ve resolved the issue.

Create a Notebook

You can create a notebook from an existing dashboard, from a chart in a dashboard or alert, or you can create one from scratch.

Create a Notebook from an Existing Chart

You can create a notebook from an existing chart on any dashboard or alert. The notebook opens using the same query as the chart with an annotation showing which dashboard or alert it came from. The annotation is a link back to the original, so you can quickly return to the origin of your investigation.

To create a notebook from an existing chart:

  1. From a chart on a dashboard click the the More ( ⋮ ) icon and choose Add to a notebook. Add chart from dashboard

    From an open chart or an alert, click Add to notebook. Add chart to notebook

  2. Click Create a notebook to start a new one. Create new notebook

    The query and chart display as the first entry in the notebook. An annotation shows the dashboard or alert the chart came from. Notebook with chart

    The same chart title is used, but you can click into the field to edit it.

  3. Click into the fields to add a title and an optional description for the notebook. Notebook title

    If you don’t add a title, Lightstep automatically names the notebook after the metric used in the query, along with a timestamp. Auto title You will need to click Save notebook. Save notebook

    You only need to explicitly save a notebook if you don’t add a notebook title. All changes are auto-saved after that point.

You can now add text fields, more charts, share the notebook, or run Change Intelligence. Run Change Intelligence

Create a Notebook from Scratch

When you want to run ad-hoc queries or start an investigation using a query different from an existing chart or alert, you can create a notebook from scratch.

To create a notebook from scratch:

  1. From the navigation bar, click Notebooks.

    Existing notebooks for the projects are shown on the left. Notebook icon in nav bar

  2. In the query builder, click into the search field to find the metric for your query. Search for metric

  3. Continue building your query as you would for a chart on a dashboard or an alert.

  4. Click Add a chart title to add a title for your chart. Add chart title

  5. Click into the fields to add a title and an optional description for the notebook. Notebook title

    If you don’t add a title, Lightstep automatically names the notebook after the metric used in the query, along with a timestamp. Auto title You will need to click Save notebook. Save notebook

    You only need to explicitly save a notebook if you don’t add a notebook title. All changes are auto-saved after that point.

You can now add text fields, more charts, share the notebook, or run Change Intelligence. Run Change Intelligence

Add Text Blocks and Charts

Once you add a chart to a notebook, you can add text blocks and additional charts to enhance your investigation.

To add a chart or text block, click the plus icon above or below an existing notebook entry. Add a chart or text block

About Adding Text blocks

  • Text blocks are saved as plain text.
  • URLs resolve to clickable links.
  • Duplicate a text block by clicking the More ( ⋮ ) icon. Duplicate a note
  • Delete the contents of a text block by clicking the X icon. Delete note's contents
  • Delete the entire text block by clicking the More ( ⋮ ) icon Delete a note

About Adding Charts

  • You can change the query for any chart.

    Edit history for notebooks is not saved, so you can’t “undo” a change. If you think you might want to save a query but also want to try variations of the query, best practice is to duplicate the chart first.

  • The time range for charts imported from dashboards or alerts uses the time range from the original chart. Charts added directly to the notebook use the same time range as the chart directly above the new chart.

    You can change the time range using the time picker. When you change the range, you can apply it to just that chart or to all charts in the notebook (the default). Change time range

    When you use the < > controls to move backward and forward through time, the time range changes for only that chart.

  • Delete a chart clicking the More ( ⋮ ) icon Delete a chart
  • Duplicate a chart clicking the More ( ⋮ ) icon Duplicate a chart

    The chart title is automatically populated with Copy of [Chart title]

Duplicate a Notebook

You can copy any existing notebook to start a new one.

To copy a notebook, click the More ( ⋮ ) icon and choose Duplicate notebook. Duplicate notebook

The notebook is saved as Copy of [Notebook title]. Click into the field to edit it.

Delete a Notebook

You can delete a notebook. When you do, all included charts and text blocks are also deleted.

To delete a notebook, click the More ( ⋮ ) icon and choose Delete. Delete notebook

Share a Notebook

You can share a notebook with any other Lightstep user in your organization. Users with Admin or Member roles can edit the notebook, including changing queries, time ranges, and text blocks. Users with Viewer roles will see a read-only version. They can’t edit the query, add notes or charts, or change the time range.

Read only notebook

To share a notebook, click the Share button and copy the link. Share a notebook

When someone adds a chart or text block to a notebook, you will need to refresh your page to see any additions/changes. If you’ve shared your notebook and know that someone else may be editing it, best practice is to refresh the page after each change you make to ensure you don’t overwrite each other’s edits.