Overview

Notebooks are collaborative rich text documents that give you all the power of Datadog graphs. Multiple users can work together to put together an investigation or postmortem featuring live data from your incident. Notebooks are also great for runbooks and documentation featuring real insights into your systems alongside your content.

Creating a notebook

You can create a notebook in two places:

• From the left-hand navigation bar, click Dashboards > New Notebook.
• On the upper-right-hand corner of the Notebooks List page, click New Notebook.

Notebook templates

In 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.

Editing a notebook

Notebooks offer a rich text editing experience to create and collaborate on content. You can freely type and format text using familiar toolbar options and keyboard shortcuts—such as bold, italic, headers, lists, and more—directly in the editor.

For users who prefer shortcuts, Notebooks also supports Markdown syntax. For example, typing # followed by a space creates a header, and using triple backticks (```) starts a code block.

Text content is automatically saved as you type. For embedded graphs, be sure to save your changes in the graph editor to apply them within the notebook.

Content types

Notebooks support various rich-text and embedded content types, including but not limited to:

• Graphs
• Images
• Headers (H1 - H3)
• Lists (bullet lists, numbered lists, and checklists)
• Codeblocks
• Block quotes
• Markdown cells

For the full list, type / into a notebook.

Graphs in notebooks

Notebooks support all widget types. For the full list, see Widgets.

Hover over the widget to display options for editing and configuring graphs.

To edit the query or configure the graph’s display, use the Quick Edit feature to make most changes inline. For more advanced configuration, click the pencil icon or hold down the Cmd/Ctrl key and click on the graph to open the full graph editor. You can adjust the local timeframe or link the graph to the global notebook time by clicking the clock icon.

Additional graph configuration options are accessible under the three-dot ellipsis menu, depending on the graph type:

• Graph size: Adjust the graph height by selecting XS, S, M (default), L, or XL.
• Graph legend: Uncheck the box to hide the legend. Legends are automatically disabled for XS and S graphs.

Rich text features

Notebooks support commonly used rich text features like bold, italics, inline code, and headers. Notebooks also support a variety of list types such as bullet, numbered, or check list.

Smart chips

Slash commands

Slash commands are an interface for creating graphs or inserting other content. On a new line, type / to open the slash command menu. Continue typing the name of the desired content type and select the appropriate option.

When you select a graph type, it opens the graph editor. After you click Save, the graph appears in your notebook.

Keyboard shortcuts

At the bottom-left corner of a notebook, click the keyboard icon to view a list of keyboard shortcuts for editing.

Additionally, you can use the following shortcuts to cut and paste widgets (Cmd/Ctrl + X, Cmd/Ctrl + V).

Table of contents

Notebooks automatically generate a table of contents from any headers or graphs you insert into your document. You can create a header using the markdown shortcut # or by selecting text and clicking Header in the toolbar.

Notebook tags

Add images to notebooks

You can add images to your notebook using /image or the Add Cell menu. This provides options for resizing, aligning, and captioning the image. Uploaded images are hosted by Datadog.

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 image action tray to adjust the size, alignment, add a caption for the image, or view the image in full screen mode.

Adding comments to a notebook

You can add comments on content in the body of the notebook. To comment on text, highlight the text and click on the comment icon in the toolbar.

To comment on a graph or an image, click on the comment icon to the right of the graph.

Multiplayer experience in Notebooks

Notebooks support full collaboration, allowing multiple users to edit simultaneously. When a collaborator opens your notebook, their cursor appears in real time. Hover over a cursor to see the collaborator’s name.

Widgets

When another user is editing a widget, an outline appears around the widget. Since widgets are saved as last write wins, avoid editing a widget that someone else is working on.

Presence

At the top of the notebook, you can see avatar images of all of the users currently viewing the notebook. Hover over an avatar to see the name of the associated collaborator.

Configuring a notebook

Template variables

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

Time controls

By default, all graphs 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 updates 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 graph from the global time. It changes the notebook’s global time instead.

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 graphs can be unlinked from the global time and set to an independent time frame.

To view a different time frame on a single graph, edit the graph 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.

Modes

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.

Version history

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

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.

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.

Permissions

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.

You must have edit access to restore general access to a restricted notebook. Complete the following steps:

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.

Finding notebooks

The Notebooks List page is the place to find all of your notebooks.

Search

The search field supports full-text search. Type your query to display the relevant notebooks as results.

Filtering

You can filter notebooks with the following methods:

There are also quick filters to access your notebooks and notebooks tagged with your teams.

Jump back in

If no filters are enabled, the Jump Back In section appears, displaying the most recent notebooks you’ve viewed or edited.

Sorting notebooks

You can sort notebooks by selecting the ⭐, details, or modified headers to sort by those values.

Further reading

Additional helpful documentation, links, and articles:

Create and navigate a documentation libraryBLOG Tell data-driven stories with Collaborative NotebooksBLOG Best practices for writing incident postmortemsBLOG Transform and enrich your logs with Datadog Observability PipelinesBLOG Explore your data with Sheets, DDSQL Editor, and Notebooks for advanced analysis in DatadogBLOG How we've created a successful FinOps practice at DatadogBLOG