Skip to main content
Skip to main content
Edit this page

AI Notebooks with ClickStack

Private preview in ClickHouse Cloud

AI Notebooks are an interactive investigation tool in ClickStack that combines an AI agent with manual analysis. You can describe an issue in plain language, and the AI agent will query logs, traces, and metrics on your behalf — surfacing relevant data, charts, and summaries as a series of tiles. You can also add your own tiles (charts, tables, searches, and markdown notes) alongside the AI-generated output, building a complete record of an investigation.

Managed ClickStack only

AI Notebooks are only available in Managed ClickStack deployments.

Setup​

AI Notebooks are currently in private preview in ClickHouse Cloud. AI models and providers are managed automatically by the platform.

Before using AI Notebooks:

  1. Generative AI enabled — A team admin must enable the Generative AI consent toggle. See Enabling Generative AI.
  2. Notebook access — Your role must have read/write permissions for Notebooks.

Once enabled, the Notebooks entry appears in the left sidebar for everyone with the appropriate role.

Enabling Generative AI​

A team admin must enable the Generative AI consent toggle before notebooks (and other AI features) can be used.

  1. Navigate to Team Settings > Security Policies.
  2. Toggle Generative AI to on.
  3. Review and accept the consent dialog.

Using AI Notebooks​

Creating a notebook​

  1. Select Notebooks from the left sidebar.
  2. Click New Private Notebook (visible only to you) or New Shared Notebook (visible to your team).

The notebook list page shows all notebooks you have access to. You can filter by name, tags, or toggle between My Notebooks and All Notebooks.

Running an AI investigation​

At the bottom of a notebook, enter a prompt describing what you want to investigate — for example, "Why did error rates spike in the checkout service over the last hour?"

Press Send (or hit Enter). The AI agent will:

  1. Examine your available data sources.
  2. Run search and aggregation queries against your logs, traces, and metrics.
  3. Produce a series of tiles showing its thought process, the queries it ran, intermediate charts, and a final summary with conclusions.

Each step appears as a tile in the notebook. Thought process tiles show the reasoning behind each query, and Output tiles contain the agent's conclusions and optional charts. Unlike a standard AI chat, notebooks let you see exactly what data the AI is working with at each step — so you can verify its reasoning, spot interesting leads it may have overlooked, and branch the investigation to steer it in a different direction.

While an investigation is running, you can click Stop to cancel it.

Branching an investigation​

As the AI investigates, you may notice an intermediate step that surfaces something interesting — but the agent continued down a different path. Branching lets you restart from that point with a different prompt, without losing the original investigation path.

To create a branch:

  1. Expand a thought process tile and click Restart from Here.
  2. In the dialog, enter a modified prompt that steers the investigation in the new direction.
  3. Click Interrupt & Create Branch. The AI starts a new investigation branch from that point.

Once a tile has multiple branches, left and right arrow buttons appear on the tile header with a badge (e.g. 1/2) indicating how many branches exist. Click the arrows to switch between branches.

Adding manual tiles​

In addition to AI-generated tiles, you can add your own analysis blocks using the buttons at the bottom of the notebook:

ButtonShortcutDescription
SearchSA log/trace search view, equivalent to the search page.
ChartLA time series line chart, using the same visualization builder as Dashboards.
TableTA tabular aggregation view.
MarkdownMFreeform text for notes, hypotheses, or conclusions.

After adding a tile, it opens in inline edit mode where you can configure the data source, filters, and aggregations — the same interface used when building dashboard visualizations. Click Save to finalize the tile.

Manual tiles are added below the last visible tile in the current branch. You can resize tiles vertically by dragging their bottom edge.

Note

If an AI investigation is currently running, adding or editing a manual tile will cancel the investigation. A confirmation dialog will appear before proceeding.

Sharing and organizing​

  • Private vs. Shared — Toggle the lock icon in the notebook header to switch between private (only you) and shared (visible to the team). Only the notebook creator can change this setting.
  • Tags — Add tags to notebooks for easy filtering on the list page.
  • Naming — Click the notebook title to rename it. If you start an investigation on an untitled notebook, the AI will suggest a name automatically.

Custom agent context​

Team admins can provide additional context that is included in every AI notebook investigation for the team. This is useful for giving the AI background on your system architecture, naming conventions, or known issues.

To configure this:

  1. Navigate to Notebooks from the left sidebar.
  2. Open Agent Settings (available to team admins).
  3. Enter your custom context (up to 50,000 characters) and save.

This context is appended to the AI's system prompt for all notebook investigations across the team.