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. From the Notebook List page, click + 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 dropdown 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.

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.

To copy the URL for a specific cell, click the cell’s Share menu and select Link directly to cell. 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.

Add images to notebooks

Only PNG, JPG, JPEG, and GIF file types are supported. Uploads have a max file size of 4MB.

You can add images to your notebook using either the image cell or the Markdown editor.

Image cell

This approach places the image in a separate cell from your text, and provides options for resizing, aligning, and captioning the image. Images uploaded by the image cell are hosted by Datadog.

To add an image, click the Image cell option in the Add New Cell menu.

Image cell in the Add New Cell menu of cells

You can use any of the following options to upload an image to be hosted by Datadog:

  • Drop an image file into the upload area
  • Click Choose File and locate the image in your file directory
  • Paste a publicly accessible URL for the image

Click the icons on the cell action tray to adjust the size, alignment, add a caption for the image cell, or view the image in full screen mode.

Image cell action tray to adjust image alignment and add a caption

Markdown editor

This approach places the image inline with your text, but does not provide options for resizing the image.

Enter the edit mode on any Markdown cell and use any of the following options to add the image:

  • Drop an image file into the text cell area.
  • Copy and paste the image directly into the text cell area.
  • Hyperlink an external image using the image widget in the header or by referencing the official Markdown guide. Note: This option does not upload the image to be hosted by Datadog.

You can preview the image in the Preview tab before saving it to your 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 which you can create new notebooks from. Templates include an Incident Response postmortem, an Incident Report, and SLO Specification. You can also create a new custom template to build reusable notebook structures.

Version history

From a notebook, click the Configure icon and click Version history to open the Version History side panel. You can preview, restore, or clone your notebook’s version history. For more information, see the Version History guide.

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 dropdown to select one or more roles, teams, or users 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