updating ai docs (#21594)
* updating ai docs * Apply suggestion from @shyamvalsan * Update conversations.md
Shyam Sreevalsan committed
Jan 21, 2026 at 15:03 UTC
cc58a589f9a3673869a6c7d018a875f84a2353de
7 files changed
+96
-58
docs/.map/map.csv
+2
-2
@@ -169,7 +169,7 @@ https://github.com/netdata/netdata/edit/master/src/health/REFERENCE.md,Alert Con
169
https://github.com/netdata/netdata/edit/master/src/web/api/health/README.md,Health API Calls,Published,Alerts & Notifications,,
170
,,,,,
171
https://github.com/netdata/netdata/edit/master/docs/category-overview-pages/machine-learning-and-assisted-troubleshooting.md,Netdata AI,Published,Netdata AI,,
172
-https://github.com/netdata/netdata/edit/master/docs/ai-powered-alert-configuration/ai-powered-alert-configuration.md,AI-Powered Alert Configuration,Published,Netdata AI,,
172
+https://github.com/netdata/netdata/edit/master/docs/netdata-ai/conversations.md,Conversations,Published,Netdata AI,"conversations,chat,real-time,live exhibits",
173
https://github.com/netdata/netdata/edit/master/docs/ml-ai/ai-insights.md,Insights,Published,Netdata AI/Insights,,
174
https://github.com/netdata/netdata/edit/master/docs/netdata-ai/insights/infrastructure-summary.md,Infrastructure Summary,Published,Netdata AI/Insights,,
175
https://github.com/netdata/netdata/edit/master/docs/netdata-ai/insights/performance-optimization.md,Performance Optimization,Published,Netdata AI/Insights,,
@@ -183,7 +183,7 @@ https://github.com/netdata/netdata/edit/master/docs/netdata-ai/troubleshooting/i
183
https://github.com/netdata/netdata/edit/master/docs/troubleshooting/troubleshoot.md,Alert Troubleshooting,Published,Netdata AI/Troubleshooting,,
184
https://github.com/netdata/netdata/edit/master/docs/ml-ai/anomaly-advisor.md,Anomaly Advisor,Published,Netdata AI/Troubleshooting,,
185
https://github.com/netdata/netdata/edit/master/docs/metric-correlations.md,Metric Correlations,Published,Netdata AI/Troubleshooting,,Quickly find metrics and charts closely related to a particular timeframe of interest anywhere in your infrastructure to discover the root cause faster.
186
-https://github.com/netdata/netdata/edit/master/docs/netdata-ai/troubleshooting/troubleshoot-button.md,Troubleshoot Button,Published,Netdata AI/Troubleshooting,,
186
+https://github.com/netdata/netdata/edit/master/docs/netdata-ai/alerts-automation/alerts-automation.md,Alerts Automation,Published,Netdata AI,"alerts,automation,ai alerts",AI-powered alert creation and suggestions
187
https://github.com/netdata/netdata/edit/master/docs/ml-ai/ml-anomaly-detection/ml-anomaly-detection.md,Anomaly Detection,Published,Netdata AI/Anomaly Detection,,
188
https://github.com/netdata/netdata/edit/master/src/ml/ml-configuration.md,ML Configuration,Published,Netdata AI/Anomaly Detection,,
189
https://github.com/netdata/netdata/edit/master/docs/ml-ai/ml-anomaly-detection/ml-accuracy.md,ML Accuracy,Published,Netdata AI/Anomaly Detection,,"Analysis of Netdata's ML anomaly detection accuracy, false positive rates, and comparison with other approaches"
docs/category-overview-pages/machine-learning-and-assisted-troubleshooting.md
+15
-7
@@ -13,7 +13,11 @@ Netdata AI is a set of analysis and troubleshooting capabilities built into Netd
13
14
## Capabilities
15
16
-### 1) Insights
16
+### 1) Conversations
17
+
18
+[Real-Time Conversations](/docs/netdata-ai/conversations.md) provide a live, interactive dialogue with Netdata AI. Ask rapid-fire questions, explore hypotheses, and get instant visualizations (Live Exhibits) embedded directly in the chat. Use Conversations for the exploratory phase of troubleshooting, then pivot to Investigations for comprehensive reports.
19
+
20
+### 2) Insights
21
22
Generates on‑demand, professional reports (see [AI Insights](/docs/ml-ai/ai-insights.md)):
23
@@ -24,23 +28,27 @@ Generates on‑demand, professional reports (see [AI Insights](/docs/ml-ai/ai-in
28
29
Each report includes an executive summary, evidence, and actionable recommendations. Reports are downloadable as PDFs and shareable with your team. You can also [schedule reports](/docs/netdata-ai/insights/scheduled-reports.md).
30
27
-### 2) Investigations
31
+### 3) Investigations
32
29
-Ask open‑ended questions (“what changed here?”, “why did X regress?”) and get a researched answer using your telemetry — see the [Investigations overview](/docs/netdata-ai/investigations/index.md). Launch from the “Troubleshoot with AI” button (captures current scope) or from Insights → New Investigation. Create [Custom Investigations](/docs/netdata-ai/investigations/custom-investigations.md) and set up [Scheduled Investigations](/docs/netdata-ai/investigations/scheduled-investigations.md).
33
+Ask open‑ended questions ("what changed here?", "why did X regress?") and get a researched answer using your telemetry — see the [Investigations overview](/docs/netdata-ai/investigations/index.md). Launch from Insights → New Investigation. Create [Custom Investigations](/docs/netdata-ai/investigations/custom-investigations.md) and set up [Scheduled Investigations](/docs/netdata-ai/investigations/scheduled-investigations.md).
34
31
-### 3) Troubleshooting
35
+### 4) Troubleshooting
36
37
- [Alert Troubleshooting](/docs/troubleshooting/troubleshoot.md) – one‑click analysis for any alert with a root‑cause hypothesis and supporting signals
38
- [Anomaly Advisor](/docs/ml-ai/anomaly-advisor.md) – interactive exploration of how anomalies propagate across systems
39
- [Metric Correlations](/docs/metric-correlations.md) – focus on the most relevant charts for any time window
40
37
-See the [Troubleshooting overview](/docs/netdata-ai/troubleshooting/index.md). From any view, use the [Troubleshoot with AI button](/docs/netdata-ai/troubleshooting/troubleshoot-button.md).
41
+See the [Troubleshooting overview](/docs/netdata-ai/troubleshooting/index.md).
42
+
43
+### 5) Alerts Automation
44
+
45
+[Alerts Automation](/docs/netdata-ai/alerts-automation/alerts-automation.md) lets you describe alert conditions in plain English while AI handles the syntax. Create production-ready alerts, get intelligent suggestions based on your infrastructure, and explain existing alert definitions.
46
39
-### 4) Anomaly Detection
47
+### 6) Anomaly Detection
48
49
Local, unsupervised ML runs on every agent, learning normal behavior and scoring anomalies for all metrics in real time. Anomaly ribbons appear on charts, and historical scores are stored alongside metrics for analysis. See [ML Anomaly Detection](/docs/ml-ai/ml-anomaly-detection/ml-anomaly-detection.md), configure via [ML Configuration](/src/ml/ml-configuration.md), and review methodology in [ML Accuracy](/docs/ml-ai/ml-anomaly-detection/ml-accuracy.md).
50
43
-### 5) MCP (Model Context Protocol)
51
+### 7) MCP (Model Context Protocol)
52
53
Connect AI clients to Netdata’s MCP server to bring live observability into natural‑language workflows and optional automation. Options include [MCP](/docs/netdata-ai/mcp/README.md), [Chat with Netdata](/docs/netdata-ai/mcp/ai-chat-netdata.md), and [MCP Clients](/docs/netdata-ai/mcp/mcp-clients/ai-devops-copilot.md) like Claude Desktop, Cursor, VS Code, JetBrains IDEs, Claude Code, Gemini CLI, and the Netdata Web Client.
54
docs/netdata-ai/alerts-automation/alerts-automation.md
renamed
+2
-2
@@ -1,10 +1,10 @@
1
-# AI-Powered Alert Configuration
1
+# Alerts Automation
2
3
## Overview
4
5
Netdata has an incredibly powerful alerting engine that offers immense flexibility to build specific, intelligent alerts. However, mastering its syntax can feel like learning a new language.
6
7
-To ensure accessibility for every member on your engineering team, we created the AI-Powered Alert Configuration feature. A bridge between your intent and Netdata's syntax, letting you describe conditions in plain English while the AI handles the rest.
7
+To ensure accessibility for every member on your engineering team, we created Alerts Automation. A bridge between your intent and Netdata's syntax, letting you describe conditions in plain English while the AI handles the rest.
8
9
## Capabilities
10
docs/netdata-ai/conversations.md
new
+73
@@ -0,0 +1,73 @@
1
+# Conversations
2
+
3
+Real-Time Conversations is a live, interactive interface for engaging in a back-and-forth dialogue with Netdata AI. Unlike Investigations and Insights reports that generate comprehensive async documents, Conversations are designed for the rapid-fire "what if" questions and quick exploration that happen in the heat of troubleshooting.
4
+
5
+
6
+
7
+## When to use it
8
+
9
+- Initial, exploratory phase of an investigation
10
+- Quick questions and ad-hoc data pulls
11
+- Rapidly testing hypotheses during incidents
12
+- Interactive data exploration with instant visualizations
13
+
14
+## Live Exhibits
15
+
16
+Netdata AI doesn't just respond with text—it generates **Live Exhibits**. These are rich, interactive data visualizations (charts, tables, and log snippets) embedded directly into your conversation.
17
+
18
+This eliminates context-switching: you don't need to open new dashboards or manually search for the data the AI references. The evidence appears inline, right in the flow of your conversation.
19
+
20
+
21
+
22
+## Example workflow
23
+
24
+Imagine you're investigating a slow API endpoint:
25
+
26
+**You:** "Show me the average latency for the `api-gateway` service over the last 3 hours."
27
+
28
+**Netdata AI:** A real-time chart visualizing the P95 latency appears in the chat. You notice a clear spike an hour ago.
29
+
30
+**You:** "What was the CPU usage on the underlying Kubernetes pods during that spike?"
31
+
32
+**Netdata AI:** A table appears listing the pods and their peak CPU usage during the incident window. One pod stands out.
33
+
34
+**You:** "Show me any error logs from that specific pod around that time."
35
+
36
+**Netdata AI:** A snippet of relevant logs appears, showing "database connection timeout" errors.
37
+
38
+In under a minute, you've gone from a vague symptom to a clear, evidence-backed root cause—all within a single, continuous conversation.
39
+
40
+## Conversations vs Investigations
41
+
42
+Use the right tool for the right job:
43
+
44
+| Feature | Conversations | Investigations & Insights |
45
+|---------|--------------|---------------------------|
46
+| **Best for** | Exploratory, real-time dialogue | Deep, comprehensive analysis |
47
+| **Output** | Interactive chat with live exhibits | Shareable PDF reports |
48
+| **Speed** | Instant responses | ~2 minutes to generate |
49
+| **Use case** | During incidents, testing hypotheses | Post-mortems, capacity planning, stakeholder updates |
50
+
51
+**Typical workflow:** Start with a Conversation to explore and form a hypothesis, then trigger an Investigation to generate a thorough, shareable report.
52
+
53
+## How to start a conversation
54
+
55
+Click the **"Conversations"** button above the space selectors in Netdata Cloud. Your conversation history is saved, allowing you to pick up an investigation where you left off.
56
+
57
+## AI credits consumption
58
+
59
+Usage is based on AI credits (10 monthly complimentary credits on Business plans, plus the ability to top up as needed).
60
+
61
+The conversations window displays a live measure of credits consumed by the current conversation:
62
+- Short conversations use a small fraction of a single credit
63
+- Long, involved conversations may consume more than 1 credit
64
+
65
+## Availability
66
+
67
+Real-Time Conversations are available for all users on a Business plan or free trial.
68
+
69
+## See also
70
+
71
+- [Investigations](/docs/netdata-ai/investigations/index.md) – comprehensive async analysis
72
+- [Insights](/docs/ml-ai/ai-insights.md) – on-demand professional reports
73
+- [Troubleshooting](/docs/netdata-ai/troubleshooting/index.md) – alert analysis and anomaly exploration
docs/netdata-ai/troubleshooting/index.md
+2
-2
@@ -22,6 +22,6 @@ From any dashboard or time window, surface the charts most related to your selec
22
23
## See also
24
25
-- Troubleshoot Button (how to trigger analysis from anywhere)
26
-- Investigations (ask open‑ended questions with rich context)
25
+- [Alerts Automation](/docs/netdata-ai/alerts-automation/alerts-automation.md) (AI‑powered alert creation and suggestions)
26
+- [Investigations](/docs/netdata-ai/investigations/index.md) (ask open‑ended questions with rich context)
27
docs/netdata-ai/troubleshooting/troubleshoot-button.md
deleted
-41
@@ -1,41 +0,0 @@
1
-# Troubleshoot with AI Button
2
-
3
-Trigger an AI‑powered investigation from anywhere in Netdata Cloud. The `Troubleshoot with AI` button captures your current context (chart, dashboard, room, or service) and launches an investigation with that scope pre‑selected.
4
-
5
-
6
-
7
-## Where to find it
8
-
9
-- Alerts tab: `Ask AI` next to any alert
10
-- Insights tab: `Alert Troubleshooting` and `New Investigation`
11
-- Top‑right of most views: `Troubleshoot with AI`
12
-- Alert emails: `Troubleshoot with AI` link
13
-
14
-## How it works
15
-
16
-1. Click `Troubleshoot with AI`
17
-2. Review the captured scope and time window
18
-3. Add your question and any extra context (symptoms, recent changes)
19
-4. Start the investigation
20
-
21
-Within ~2 minutes, you’ll receive a report with:
22
-
23
-- Summary of findings and likely root cause
24
-- Correlated metrics/logs across affected systems
25
-- Suggested next steps with rationale
26
-
27
-## Tips for better results
28
-
29
-- Be explicit about timeframe, environment, and related services
30
-- Paste relevant notes from tickets/Slack/deploy logs
31
-- Run multiple investigations in parallel during incidents
32
-
33
-## Availability and credits
34
-
35
-- Available on Business and Free Trial plans
36
-- Each run consumes 1 AI credit (10 free per month on eligible plans)
37
-
38
-## Privacy
39
-
40
-Your infrastructure data is summarized to a compact context for analysis and is not used to train foundation models.
41
-
docs/troubleshooting/custom-investigations.md
+2
-4
@@ -81,11 +81,9 @@ You can create investigations in two ways:
81
2. Click **"New Investigation"**
82
3. Enter your question and context
83
84
-#### From Anywhere with "Troubleshoot with AI"
84
+#### From Any Alert
85
86
-Click the **"Troubleshoot with AI"** button in the top right corner from any screen. This automatically captures your current context—including the specific chart, dashboard, or service you're viewing. Add your question and any extra context, then start the investigation.
87
-
88
-[SCREENSHOT FROM FIRST BLOG POST SHOULD BE PLACED HERE - showing the Troubleshoot with AI button]
86
+Click **"Ask AI"** next to any alert, or use the **"Alert Troubleshooting"** option in the Insights tab. This automatically captures your current context—including the specific alert, timeframe, and affected services. Add your question and any extra context, then start the investigation.
87
88
### Getting Your Results
89