Notebooks

Overview

Notebooks combine graphs and text in a linear, cell-based format. They help you explore and share stories with your data by creating postmortems, investigations, runbooks, documentation, and more.

Getting started

  1. Build a new notebook, from the main navigation Notebooks > New Notebook.

  2. Click the Save Notebook button.
    Note: A new notebook is not saved by default.

  3. Add new cells to your notebook with supported graph and text content.

  4. Configure cells.

Collaboration

Indicators of users viewing the notebook and making live edits

Notebooks support real-time collaboration. Presence indicators show who is viewing your notebook at any time, as well as real-time edits to notebook cells. Changes made to a notebook appear automatically, without the need to refresh.

Everyone on your team can open any notebook, but a notebook can only be modified or deleted by any Datadog role with the Notebooks Write permission.

Commenting

To add a comment, select some text or hover over a graph. The Add comment icon is displayed to the right of the cell. From the comments you can also notify a member on your team through the @mention feature. Click the three vertical dots in the top-right corner of your comment to edit or delete a comment you wrote. View or re-open resolved comments in the Comment History side panel, available in the Notebook cog menu.

Notebook authors receive email notifications for new comments on their notebooks, and commenters are notified for replies to their comments. Manage your notification settings through Notifications in the notebook cog menu.

View mode

View mode drop down menu

You can switch between modes from within the Notebook by selecting the dropdown at the top right of your notebook.

  • Editing: make changes to the notebook.

  • Viewing: contents are Read Only, preventing users from making unwanted edits to existing configurations and information.

  • Presenting: share the contents of the Notebook in a display format where each cell appears as a slide. Presentation mode supports graph interactions such as tooltips and legends.

Share notebooks

Click on the cog icon in the upper right of a notebook to see sharing options. Notebooks can be exported to PDF, Markdown, or any document editor.

To copy a notebook into a document editor, click Copy formatted contents. Paste into a document editor like Google Docs or Microsoft Word to see notebook contents, including graphs, with original formatting.

Example exported Notebook in Google Docs

Import or export notebook JSON

Use Export Notebook JSON to download a JSON file containing the definition of your notebook. Import Notebook JSON overwrites all content on the notebook with the content of the uploaded JSON.

Copy the URL for a specific cell by clicking Link directly to cell in the cell’s Share menu. Direct linking is available for both visualization and Markdown cells.

When a user visits the URL for a specific cell, the notebook is opened to show the cell at the top of the viewport. Links are absolute. A cell’s URL remains the same even if it is moved to a new position within the notebook.

Notebook List

notebook list previewing the cell types of a selected notebook

The Notebook List allows you to view and search previously created notebooks. Each notebook’s name, creator, and last modified date are displayed. Notebooks are grouped by:

  • Your Notebooks: Notebooks created by you.
  • All Notebooks: All Notebooks in your organization.
  • Notebook Type: Group notebooks by type.

Hover over the Preview icon for any Notebook to see a preview of the contents, including widget types and Markdown. To open the Notebook in View Mode, hover over the notebook and click Open notebook in view mode on the right.

From the Template Gallery, see ready-to-use templates including an Incident Response postmortem and an Incident Report which you can create new notebooks from. You can also create a new custom template to build reusable notebook structures.

Notebook configuration

Time frames

By default, all graph cells are linked to the global time frame set in the notebook header.

To view a different time frame, select an option in the global time picker, or scrub on a graph directly. The notebook URL will update to reflect this new time frame without saving it to the notebook.

Note: Clicking and dragging to zoom in on a graph does not unlock the cell from the global time. It changes the notebook’s global time instead.

Save notebook global time with Set Default Time button

To save this time as the notebook’s default, click Set Default Time. To reset your global time back to the previously saved default global time, click the reset button.

Individual cells can be unlinked from the global time and set to an independent time frame.

Cell Time Selector with the cell unlinked from global time

To view a different time frame on a single cell, edit the cell and use the toggle to unlink it from Global Time. Change the time frame using the time picker or by scrubbing on the graph. Changes made in edit mode are saved automatically when you click Done. To discard your changes, click Cancel instead of Done.

Notebook types

Add Type button highlighted in a Notebook

Notebooks can be grouped into types, giving you quick access to relevant information. Notebooks built from other products like Incident Management or Monitors may automatically assign a type. Hover over the notebook title to display the option to add or edit the type. Click + Add Type, or to edit the type, click the pencil icon that appears next to it on hover.

Graph snapshots

Notebooks can be set to automatically take snapshots of graphs that might expire. Enable this by clicking Turn on snapshots in the cog menu of any notebook. Use the cog menu to view snapshots or turn off automatic snapshots. Turn off automatic snapshots to remove access to existing snapshots.

Cog menu option to turn on snapshots

Notebooks with snapshots enabled automatically capture a static image of any graphs with a fixed time range (for example, Aug 18, 12:00 am - Aug 19, 11:59 pm). These snapshots update when the graph is updated, as long as the new graph also has a fixed time range. Changing the graph to a global time range (like Past 1 Hour) removes the snapshot.

You can preview the existing snapshot on any fixed-time graph by hovering over the camera icon while in edit mode.

To share a version of your notebook with snapshots, from the cog menu, click View snapshots. Copy the URL, or append &view=snapshots to the URL of any notebook that has snapshots enabled.

Template variables

Notebooks support template variables. Dynamically scope visualizations by adding and selecting template variable values. For more information, see Template Variables.

Cell configuration

To add cells, use the + button that appears to the left of the cell, or select an option from the Add New Cell section at the bottom of the notebook. Use the action tray that appears above the cell on hover to share, clone, or delete cells. Graph cells can be exported to a dashboard, or downloaded as a PNG or a CSV of graph data. Changes made in edit mode are saved automatically when you click Done. To discard your changes, click Cancel instead of Done.

Edit options

Click on More options in the inline editor of a widget to edit widget options. Add details like event overlays, markers, and y-axis controls.

Layout options

In a Notebook cell, click Edit to view the cell configuration in edit mode. You can also see the available layout options, which vary based on the cell content type, but include the following:

  • Graph size: Choose between XS, S, M (default), L, and XL.
  • Graph legend: Uncheck the box to hide the legend. Legends are automatically disabled for XS and S graphs.
  • Grouping: Display one graph per tag value to see small multiples of your visualization.
The graph settings option of a notebook cell in edit mode displaying layout options for graph size, legend, and grouping configuration

Note: Changing any of these settings only affects the targeted cell.

Types of content

Notebooks support visualizations and text cells. Text cells are formatted with Markdown, which enables the use of headings, subheadings, links, images, lists, and code blocks. Notebooks also support diagrams formatted with MermaidJS.

Graphs in notebooks support all Datadog data sources: metrics, log events, Indexed Spans, live processes, network traffic, RUM events, profiling metrics, security signals, and more. Graphs are created with the Datadog query editor. Notebooks support:

Limit edit access

By default, all users have full access to notebooks.

Use granular access controls to limit the roles that may edit a particular notebook:

  1. While viewing a notebook, click on the cog in the upper right. The settings menu opens.
  2. Select Permissions.
  3. Click Restrict Access.
  4. The dialog box updates to show that members of your organization have Viewer access by default.
  5. Use the drop-down to select one or more roles that may edit the notebook.
  6. Click Add.
  7. The dialog box updates to show that the role you selected has the Editor permission.
  8. Click Save

Note: To maintain your edit access to the notebook, the system requires you to include at least one role that you are a member of before saving.

To restore general access to a notebook with restricted access, follow the steps below:

  1. While viewing the notebook, click on the cog in the upper right. The settings menu opens.
  2. Select Permissions.
  3. Click Restore Full Access.
  4. Click Save.

Further Reading