@cryptotaxi247 / netdata-1 / commits / 042f80da2

Add reporting documentation page (#21520)

* Add reporting documentation page New documentation covering 4 methods for extracting infrastructure insights from Netdata: 1. AI Insights - executive summaries and scheduled reports 2. AI Assistants (MCP) - ad-hoc queries via Claude, Cursor, etc. 3. Grafana integration - custom dashboards from Netdata Cloud 4. Export to BI tools - Power BI, Tableau, Looker, and others Methods are ordered from easiest to most advanced. Page includes SEO keywords for major BI platforms to improve discoverability. * Update reporting.md removed --- * docs/reporting.md: address PR feedback on Export to BI section - Recommend Netdata Cloud API as primary option for multi-node infrastructure - Add concrete examples with API tokens for querying all nodes - Clarify distinction between Cloud API (all nodes) vs Agent API (single node) - Use clearer terminology (AGENT_IP instead of YOUR_NETDATA_IP) - Fix broken REST API link to point to src/web/api/README.md * docs/reporting.md: clarify Agent vs Parent API access - Use NODE_IP instead of AGENT_IP to indicate both work - Parent IP returns aggregated metrics from all child agents - Update to /api/v3/ endpoints (current version in use) * docs/reporting.md: fix API v3 endpoint parameters - Use context=system.cpu instead of chart=system.cpu (v3 API uses context, not chart) - chart parameter is v1 API only * docs/reporting.md: fix API v3 parameter - use contexts (plural) not context - v3 API uses 'contexts' parameter (plural), not 'context' or 'chart' - chart parameter is v1 API only - format=json2 is the v3 default format * docs/reporting.md: document key API v3 parameters - Explain contexts, after/before, points, time_group parameters - Show example with meaningful values instead of defaults * docs/reporting.md: add practical BI use cases with examples - Show common BI scenarios (daily averages, weekly max, hourly sum) - Add table explaining key parameters for BI workflows - Make it clear this is for combining with other business data --------- Co-authored-by: Kanela <kanela@netdata.cloud>

Costa Tsaousis committed Jan 29, 2026 at 07:54 UTC 042f80da23211a973bf0328b2d91948a530b9dc2

2 files changed +298

docs/.map/map.csv

@@ -5,6 +5,7 @@ https://github.com/netdata/netdata/edit/master/docs/realtime-monitoring.md,Real-

5 https://github.com/netdata/netdata/edit/master/docs/scalability.md,Scalability,Published,Welcome to Netdata,,

6 https://github.com/netdata/netdata/edit/master/src/collectors/COLLECTORS.md,Monitor Anything,Published,Welcome to Netdata,,Netdata gathers real-time metrics from hundreds of data sources using collectors. Most require zero configuration and are pre-configured out of the box.

7 https://github.com/netdata/netdata/edit/master/docs/fleet-configuration-management.md,Fleet Deployment and Configuration Management,Published,Welcome to Netdata,,

8 +https://github.com/netdata/netdata/edit/master/docs/reporting.md,Reporting,Published,Welcome to Netdata,"power bi, tableau, looker, qlik, reporting, business intelligence, bi, grafana, ai insights, mcp, executive reports, board reporting, data export","Extract infrastructure insights for stakeholders and BI tools using AI Insights, AI assistants (MCP), Grafana, or data export to Power BI, Tableau, and other analytics platforms."

9 https://github.com/netdata/netdata/edit/master/docs/getting-started-netdata/guide.md,Getting Started,Published,root,,

10 https://github.com/netdata/netdata/edit/master/docs/Demo-Sites.md,Live Demo,Published,root,,

11 ,,,,,

docs/reporting.md new

+297

@@ -0,0 +1,297 @@

1 +# Reporting

2 +

3 +Extract infrastructure insights for stakeholders, leadership, and external tools. Netdata provides four ways to create reports—from asking a simple question to exporting raw metrics into your existing business intelligence stack.

4 +

5 +## Methods overview

6 +

7 +| Method | Effort | Best for |

8 +|--------|--------|----------|

9 +| **[AI Insights](#ai-insights)** | Easiest | Executive summaries, recurring reports, natural language queries |

10 +| **[AI Assistants (MCP)](#ai-assistants-mcp)** | Easy | Ad-hoc analysis, deep investigation, developer workflows |

11 +| **[Grafana](#grafana-integration)** | Medium | Custom dashboards, teams already using Grafana |

12 +| **[Export to BI](#export-to-business-intelligence-tools)** | Advanced | Power BI, Tableau, Looker, custom analytics pipelines |

13 +

14 +## AI Insights

15 +

16 +Ask Netdata anything about your infrastructure in plain language and receive an executive-ready report. No configuration required—just describe what you need.

17 +

18 +### When to use it

19 +

20 +- Monday morning recap of weekend incidents

21 +- Post-incident executive summary for leadership

22 +- Weekly health checks and situational awareness

23 +- Cost optimization analysis

24 +- SLO conformance reporting

25 +

26 +### How to generate a report

27 +

28 +1. Open Netdata Cloud and go to `Insights`

29 +2. Select a pre-built report type (Infrastructure Summary, Performance Optimization, Capacity Planning, Anomaly Analysis) or click `New Investigation` for a custom prompt

30 +3. Choose the time range and scope (all nodes or a specific room/space)

31 +4. Click `Generate`

32 +

33 +Reports complete in 2–3 minutes and are saved in Insights. You receive an email when the report is ready.

34 +

35 +### Scheduling recurring reports

36 +

37 +Automate your reporting workflow with scheduled reports:

38 +

39 +1. Configure your report as above

40 +2. Click `Schedule` (next to `Generate`)

41 +3. Choose cadence: daily, weekly, or monthly

42 +4. Set the delivery time

43 +

44 +Scheduled reports run automatically and deliver results to your email and the Insights tab.

45 +

46 +### Example prompts

47 +

48 +**Weekly infrastructure health:**

49 +```

50 +Generate a weekly infrastructure summary for services A, B, and C.

51 +Include major incidents, anomalies, capacity risks, and recommended follow-ups.

52 +```

53 +

54 +**Cost optimization:**

55 +```

56 +Identify underutilized nodes for cost savings. Monthly compute is ~$12K

57 +with mixed workloads. Goal: save $2–3K/month without reliability impact.

58 +```

59 +

60 +**SLO conformance:**

61 +```

62 +Generate an SLO conformance report for 'user-auth' (99.9% uptime,

63 +p95 latency <200ms) for the last 7 days. Include breaches, contributing

64 +factors, and remediation recommendations.

65 +```

66 +

67 +### Availability

68 +

69 +- Available to Business and Free Trial plans

70 +- Each report consumes 1 AI credit (10 free per month on eligible plans)

71 +- Data privacy: metrics are summarized into structured context; your data is not used to train foundation models

72 +

73 +## AI Assistants (MCP)

74 +

75 +Connect your AI assistant directly to Netdata using the Model Context Protocol (MCP). Ask questions in natural language and receive answers based on live infrastructure data.

76 +

77 +Every Netdata Agent and Parent (v2.6.0+) includes an MCP server. AI assistants can query metrics, alerts, logs, and live system information across your entire infrastructure.

78 +

79 +### Supported AI clients

80 +

81 +| Client | Description |

82 +|--------|-------------|

83 +| Claude Desktop | Anthropic's desktop AI assistant |

84 +| Claude Code | Anthropic's CLI for development workflows |

85 +| Cursor | AI-powered code editor |

86 +| VS Code | Visual Studio Code with MCP support |

87 +| JetBrains IDEs | IntelliJ, PyCharm, WebStorm, and others |

88 +| Gemini CLI | Google's Gemini CLI |

89 +| OpenAI Codex CLI | OpenAI's development tools |

90 +

91 +### How to connect

92 +

93 +```bash

94 +# Export your MCP key

95 +export NETDATA_MCP_API_KEY="$(cat /var/lib/netdata/mcp_dev_preview_api_key)"

96 +

97 +# Connect using mcp-remote

98 +npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp \

99 + --allow-http \

100 + --header "Authorization: Bearer $NETDATA_MCP_API_KEY"

101 +```

102 +

103 +### Example queries

104 +

105 +Once connected, ask natural language questions:

106 +

107 +- "Show me CPU usage for all nodes in the last 24 hours"

108 +- "What are the top 10 processes by memory consumption?"

109 +- "Find any anomalies in network traffic this week"

110 +- "Generate a summary of all active alerts"

111 +- "Which nodes have the highest disk utilization?"

112 +

113 +### Availability

114 +

115 +- Available on all plans (v2.6.0+)

116 +- Unlimited queries with no per-query charges

117 +- Requires API key for access to sensitive data

118 +

119 +See [Netdata MCP](/docs/netdata-ai/mcp/README.md) for detailed setup instructions.

120 +

121 +## Grafana integration

122 +

123 +Connect Grafana to Netdata Cloud for infrastructure-wide dashboards. Use Grafana's visualization capabilities with Netdata's real-time metrics.

124 +

125 +### When to use it

126 +

127 +- Teams already using Grafana for other data sources

128 +- Custom dashboard requirements beyond Netdata's built-in charts

129 +- Combining Netdata metrics with data from other systems

130 +

131 +### How to connect

132 +

133 +1. Install the Netdata data source plugin in Grafana

134 +2. Configure connection to Netdata Cloud using an API token

135 +3. Create dashboards using Grafana's query builder

136 +

137 +:::tip

138 +

139 +Generate API tokens from Netdata Cloud under **User Settings** → **API Tokens**. See [API Tokens](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md) for details.

140 +

141 +:::

142 +

143 +### Availability

144 +

145 +- Requires Netdata Cloud account

146 +- Grafana Cloud or self-hosted Grafana

147 +- API tokens available on all plans

148 +

149 +## Export to business intelligence tools

150 +

151 +Export metrics from Netdata to external databases and business intelligence platforms. You can query data from individual Agents or use Netdata Cloud to aggregate metrics from your entire infrastructure.

152 +

153 +### Supported BI platforms

154 +

155 +Netdata integrates with popular business intelligence tools through several pathways:

156 +

157 +| BI Platform | Integration Options |

158 +|-------------|---------------------|

159 +| **Power BI** | Netdata Cloud API, Prometheus endpoint, or database export |

160 +| **Tableau** | Netdata Cloud API, PostgreSQL, or Prometheus |

161 +| **Looker / Looker Studio** | Netdata Cloud API, BigQuery, or Prometheus |

162 +| **Qlik** | Netdata Cloud API, PostgreSQL, or InfluxDB |

163 +| **SAP Analytics Cloud** | Netdata Cloud API or PostgreSQL |

164 +| **Metabase** | Netdata Cloud API, PostgreSQL, or TimescaleDB |

165 +| **Apache Superset** | Netdata Cloud API, PostgreSQL, or Prometheus |

166 +| **Domo** | Netdata Cloud API or database connectors |

167 +| **ThoughtSpot** | Netdata Cloud API or PostgreSQL |

168 +

169 +### Query options

170 +

171 +#### Netdata Cloud API (recommended)

172 +

173 +The Netdata Cloud API lets you query metrics from all your nodes through a single endpoint. This is the simplest approach for multi-node infrastructure.

174 +

175 +1. Generate an API token from **User Settings** → **API Tokens**

176 +2. Use the token to authenticate requests to `https://app.netdata.cloud/api/v2/data`

177 +

178 +```bash

179 +# Query CPU metrics from all nodes

180 +curl -H 'Accept: application/json' \

181 + -H "Authorization: Bearer YOUR_API_TOKEN" \

182 + 'https://app.netdata.cloud/api/v2/data?contexts=system.cpu&after=-3600'

183 +

184 +# Get list of all nodes in your space

185 +curl -H 'Accept: application/json' \

186 + -H "Authorization: Bearer YOUR_API_TOKEN" \

187 + 'https://app.netdata.cloud/api/v2/nodes'

188 +```

189 +

190 +The Cloud API returns aggregated data from all nodes in your infrastructure, making it ideal for BI tools that need a unified view.

191 +

192 +#### Prometheus endpoint (single-node)

193 +

194 +For single-node deployments or Prometheus-based workflows, query the Agent or Parent directly:

195 +

196 +```

197 +http://NODE_IP:19999/api/v3/allmetrics?format=prometheus

198 +```

199 +

200 +Replace `NODE_IP` with your Netdata Agent or Parent IP address:

201 +- **Agent IP**: Returns metrics from that single node

202 +- **Parent IP**: Returns aggregated metrics from all child agents connected to that Parent

203 +

204 +This endpoint is useful when you need metrics from a specific node or when your BI tool already integrates with Prometheus.

205 +

206 +#### REST API with JSON

207 +

208 +Query specific metrics from an Agent or Parent in JSON format. This is useful for BI tools that need to combine Netdata metrics with other business data.

209 +

210 +**Common BI use cases:**

211 +

212 +```bash

213 +# Daily averages for last 30 days, grouped by node

214 +curl 'http://NODE_IP:19999/api/v3/data?contexts=system.cpu&after=-2592000&points=30&time_group=avg&group_by=node'

215 +

216 +# Weekly max values for capacity planning

217 +curl 'http://NODE_IP:19999/api/v3/data?contexts=system.ram&after=-604800&points=4&time_group=max&group_by=node'

218 +

219 +# Hourly sum for cost analysis

220 +curl 'http://NODE_IP:19999/api/v3/data?contexts=system.cpu&after=-86400&points=24&time_group=sum'

221 +```

222 +

223 +**Key parameters for BI workflows:**

224 +

225 +| Parameter | Description | Example |

226 +|-----------|-------------|---------|

227 +| `contexts` | Metric context to query | `system.cpu`, `system.ram`, `disk.io` |

228 +| `after` / `before` | Timeframe (seconds or Unix timestamp) | `-2592000` = last 30 days |

229 +| `points` | Number of output points | `30` = daily for monthly view |

230 +| `time_group` | Aggregation function | `avg`, `sum`, `min`, `max` |

231 +| `group_by` | How to group results | `node`, `context`, `label:LABEL_NAME` |

232 +

233 +Power BI, Tableau, and similar tools can consume this JSON through their data transformation features (Power Query, etc.).

234 +

235 +#### Database export connectors

236 +

237 +For persistent storage and historical analysis, export metrics to a database:

238 +

239 +| Database | Connector |

240 +|----------|-----------|

241 +| PostgreSQL | Prometheus remote write adapter |

242 +| TimescaleDB | Prometheus remote write or netdata-timescale-relay |

243 +| InfluxDB | Graphite or Prometheus remote write |

244 +| Elasticsearch | Graphite or Prometheus remote write |

245 +| Google BigQuery | Prometheus remote write |

246 +| AWS services | AWS Kinesis Data Streams |

247 +| Azure services | Prometheus remote write |

248 +

249 +See [Export Metrics to External Time-Series Databases](/docs/exporting-metrics/README.md) for full connector documentation.

250 +

251 +### When to use this approach

252 +

253 +- Existing BI infrastructure with established workflows

254 +- Requirement to combine Netdata data with other business data sources

255 +- Custom visualization needs not covered by built-in dashboards

256 +- Long-term archival beyond Netdata's retention

257 +- Compliance requirements for data export

258 +

259 +## Choosing the right method

260 +

261 +### Start with AI Insights if you:

262 +

263 +- Need reports quickly without setup

264 +- Want executive-ready summaries

265 +- Prefer natural language over configuration

266 +- Need recurring automated reports

267 +

268 +### Use AI Assistants (MCP) if you:

269 +

270 +- Want real-time answers to ad-hoc questions

271 +- Already use Claude, Cursor, or similar AI tools

272 +- Need deep investigation capabilities

273 +- Prefer conversational interaction with your data

274 +

275 +### Use Grafana if you:

276 +

277 +- Already have Grafana deployed

278 +- Need highly customized dashboards

279 +- Want to combine Netdata with other data sources in one view

280 +- Have team expertise in Grafana

281 +

282 +### Export to BI tools if you:

283 +

284 +- Have established Power BI, Tableau, or Looker workflows

285 +- Need to combine infrastructure metrics with business data

286 +- Require custom analytics beyond monitoring

287 +- Have compliance requirements for data in specific systems

288 +

289 +## Related documentation

290 +

291 +- [AI Insights: Infrastructure Summary](/docs/netdata-ai/insights/infrastructure-summary.md)

292 +- [AI Insights: Scheduled Reports](/docs/netdata-ai/insights/scheduled-reports.md)

293 +- [Investigations](/docs/netdata-ai/investigations/index.md)

294 +- [Netdata MCP](/docs/netdata-ai/mcp/README.md)

295 +- [API Tokens](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md)

296 +- [Export Metrics to External Time-Series Databases](/docs/exporting-metrics/README.md)

297 +- [REST API](/src/web/api/README.md)