@cryptotaxi247 / netdata-1 / commits / eeb68223a

Regenerate integrations docs (#21627)

Co-authored-by: ilyam8 <22274335+ilyam8@users.noreply.github.com>

Netdata bot committed Jan 24, 2026 at 10:46 UTC eeb68223abcc224ad1894d6ca73b63215e17375b

17 files changed +1266 -595

src/go/plugin/go.d/collector/clickhouse/integrations/clickhouse.md

+53 -25

@@ -178,23 +178,51 @@ This collector exposes real-time functions for interactive troubleshooting in th

178

179 ### Top Queries

180

181 -Top SQL queries from ClickHouse system.query_log.

181 +Retrieves and aggregates SQL query performance metrics from ClickHouse [system.query_log](https://clickhouse.com/docs/en/operations/system-tables/query_log) table.

182

183 -Queries system.query_log, aggregates by query, and returns the top entries sorted by the selected column.

183 +This function queries the `system.query_log` table, which contains information about executed queries including timing, resource usage, and execution statistics. Queries are grouped by their normalized hash (`normalized_query_hash`) to aggregate statistics for identical query patterns with different literal values.

184 +

185 +Use cases:

186 +- Identify slow queries that consume the most execution time

187 +- Find frequently executed queries that may benefit from optimization

188 +- Analyze I/O patterns by examining read/written rows and bytes

189 +

190 +Query text is truncated at 4096 characters for display purposes.

191

192

193 | Aspect | Description |

194 |:-------|:------------|

195 | Name | `Clickhouse:top-queries` |

189 -| Performance | Uses system.query_log and can be expensive on busy systems. Use limits to control response size. |

190 -| Security | Query text may include sensitive literals depending on server settings. |

191 -| Availability | Available when the collector can query system tables; returns 503 if system.query_log is not available. |

196 +| Require Cloud | yes |

197 +| Performance | Queries `system.query_log` table and aggregates by `normalized_query_hash`: • On busy systems with high query throughput, the table can grow large • Default limit of 500 rows balances usefulness with performance |

198 +| Security | Query text may contain unmasked literal values including potentially sensitive data: • Personal information in query parameters • Business data and internal identifiers • Access should be restricted to authorized personnel only |

199 +| Availability | Available when: • The collector has successfully connected to ClickHouse • `system.query_log` table is accessible • Returns HTTP 503 if `system.query_log` is not accessible • Returns HTTP 500 if the query fails • Returns HTTP 504 if the query times out |

200

201 #### Prerequisites

202

195 -##### Grant access to system.query_log

203 +##### Grant access to `system.query_log`

204 +

205 +Ensure the Netdata user can read `system.query_log` on the target ClickHouse instance.

206 +

207 +1. Verify `query_log` is enabled (enabled by default):

208 +

209 + ```sql

210 + SELECT * FROM system.query_log LIMIT 1;

211 + ```

212

197 -Ensure the Netdata user can read system.query_log on the target ClickHouse instance.

213 +2. If using a dedicated monitoring user, grant SELECT access:

214 +

215 + ```sql

216 + GRANT SELECT ON system.query_log TO netdata_user;

217 + ```

218 +

219 +:::info

220 +

221 +- The `query_log` table is enabled by default in ClickHouse

222 +- Only queries with `type='QueryFinish'` are included in the results

223 +- The `normalized_query_hash` column is used for grouping when available

224 +

225 +:::

226

227

228

@@ -202,30 +230,30 @@ Ensure the Netdata user can read system.query_log on the target ClickHouse insta

230

232 |:---------|:-----|:------------|:--------:|:--------|:--------|

234

235 #### Returns

236

209 -Aggregated query statistics from system.query_log.

237 +Aggregated query statistics from `system.query_log`, grouped by normalized query hash. Each row represents a unique query pattern with cumulative metrics across all executions.

238

240 |:-------|:-----|:-----|:-----------|:------------|

250 +| Read Rows | integer | | | Total number of rows read from storage across all executions. High values suggest queries scanning large amounts of data that may benefit from better filtering or indexing. |

254 +| Result Rows | integer | | | Total number of rows returned to clients across all executions. A high ratio of read rows to result rows indicates filtering or aggregation happening on large datasets. |

257

258

259

src/go/plugin/go.d/collector/cockroachdb/integrations/cockroachdb.md

+105 -51

@@ -27,7 +27,7 @@ This collector monitors CockroachDB servers.

28 It scrapes Prometheus metrics from the CockroachDB `/_status/vars` endpoint.

30 -It also provides `top-queries` and `running-queries` functions using SQL statement statistics (`crdb_internal.cluster_statement_statistics`) and `SHOW CLUSTER STATEMENTS`.

30 +It also provides `top-queries` and `running-queries` functions using SQL statement statistics (`crdb_internal.cluster_statement_statistics`) and the `SHOW CLUSTER STATEMENTS` command.

33 This collector is supported on all platforms.

@@ -36,7 +36,7 @@ This collector supports collecting metrics from multiple instances of this integ

37 The `top-queries` and `running-queries` functions require:

39 -- A SQL user with `VIEWACTIVITY` (or `VIEWACTIVITYREDACTED`) privileges.

39 +- A SQL user with `VIEWACTIVITY` or `VIEWACTIVITYREDACTED` privileges.

40 - Access to `crdb_internal.cluster_statement_statistics` (may require `SET allow_unsafe_internals = on` on newer versions).

@@ -142,23 +142,53 @@ This collector exposes real-time functions for interactive troubleshooting in th

142

143 ### Top Queries

144

145 -Top SQL statements from crdb_internal.cluster_statement_statistics.

145 +Retrieves and aggregates SQL statement performance metrics from CockroachDB [crdb_internal.cluster_statement_statistics](https://www.cockroachlabs.com/docs/stable/crdb-internal#cluster_statement_statistics) table.

146

147 -Queries crdb_internal.cluster_statement_statistics and returns the top entries sorted by the selected column.

147 +This function queries cluster-wide statement statistics grouped by fingerprint (normalized query pattern). It provides aggregated metrics including execution counts, timing breakdowns, and row operation statistics.

148 +

149 +Use cases:

150 +- Identify slow queries consuming the most total execution time

151 +- Find frequently executed queries that may benefit from optimization

152 +- Analyze row read/write patterns to detect inefficient queries

153 +

154 +Query text is truncated at 4096 characters for display purposes.

155

156

157 | Aspect | Description |

158 |:-------|:------------|

159 | Name | `Cockroachdb:top-queries` |

153 -| Performance | Executes SQL queries against system tables and may be expensive on busy clusters. |

154 -| Security | Query text may contain unmasked literals (potential PII). |

155 -| Availability | Requires SQL DSN configuration and access to system tables; returns errors if DSN is missing or SQL is unavailable. |

160 +| Require Cloud | yes |

161 +| Performance | Queries the `crdb_internal.cluster_statement_statistics` table which aggregates data across the cluster: • On busy clusters with high query throughput, this query may take longer • Default limit of 500 rows balances usefulness with performance |

162 +| Security | Query text may contain unmasked literal values including potentially sensitive data: • Personal information in WHERE clauses or INSERT values • Business data and internal identifiers • Access should be restricted to authorized personnel only |

163 +| Availability | Available when: • The collector has successfully connected to CockroachDB • The SQL user has `VIEWACTIVITY` or `VIEWACTIVITYREDACTED` privileges • Returns HTTP 503 if the SQL connection cannot be established • Returns HTTP 500 if the query fails • Returns HTTP 504 if the query times out |

164

165 #### Prerequisites

166

159 -##### Grant VIEWACTIVITY access to cluster statement stats

167 +##### Grant `VIEWACTIVITY` access to cluster statement stats

168 +

169 +The SQL user must have appropriate privileges to access statement statistics.

170 +

171 +1. Grant `VIEWACTIVITY` (shows full query text) or `VIEWACTIVITYREDACTED` (masks literals):

172 +

173 + ```sql

174 + GRANT SYSTEM VIEWACTIVITY TO netdata_user;

175 + -- OR for privacy:

176 + GRANT SYSTEM VIEWACTIVITYREDACTED TO netdata_user;

177 + ```

178

161 -Use a SQL user with VIEWACTIVITY (or VIEWACTIVITYREDACTED) and access to crdb_internal.cluster_statement_statistics.

179 +2. On newer CockroachDB versions, access to `crdb_internal` may require:

180 +

181 + ```sql

182 + SET allow_unsafe_internals = on;

183 + ```

184 +

185 +:::info

186 +

187 +- The collector automatically sets `allow_unsafe_internals = on` for the session when querying `crdb_internal` tables (required on newer versions)

188 +- `VIEWACTIVITYREDACTED` replaces literal values with underscores for privacy

189 +- Statement statistics are collected by default but can be disabled via cluster settings

190 +

191 +:::

192

193

194

@@ -166,54 +196,78 @@ Use a SQL user with VIEWACTIVITY (or VIEWACTIVITYREDACTED) and access to crdb_in

196

198 |:---------|:-----|:------------|:--------:|:--------|:--------|

200

201 #### Returns

202

173 -Aggregated SQL statement statistics.

203 +Aggregated SQL statement statistics grouped by fingerprint. Each row represents a unique query pattern with cumulative metrics across all executions.

204

206 |:-------|:-----|:-----|:-----------|:------------|

227

228 ### Running Queries

229

200 -Currently running SQL statements from SHOW CLUSTER STATEMENTS.

230 +Retrieves currently executing SQL statements across the CockroachDB cluster using [SHOW CLUSTER STATEMENTS](https://www.cockroachlabs.com/docs/stable/show-statements).

231 +

232 +This function provides a real-time snapshot of all active queries across all nodes in the cluster, including their execution phase, duration, and associated metadata.

233

202 -Queries SHOW CLUSTER STATEMENTS and returns running statements sorted by the selected column.

234 +Use cases:

235 +- Identify long-running queries that may be blocking other operations

236 +- Monitor active workload distribution across the cluster

237 +- Debug stuck or slow queries in real-time

238 +

239 +Query text is truncated at 4096 characters for display purposes.

240

241

242 | Aspect | Description |

243 |:-------|:------------|

244 | Name | `Cockroachdb:running-queries` |

208 -| Performance | Executes SQL queries against system tables and may be expensive on busy clusters. |

209 -| Security | Query text may contain unmasked literals (potential PII). |

210 -| Availability | Requires SQL DSN configuration and access to system tables; returns errors if DSN is missing or SQL is unavailable. |

245 +| Require Cloud | yes |

246 +| Performance | Executes the `SHOW CLUSTER STATEMENTS` command which queries all nodes in the cluster: • Lightweight operation with minimal overhead • Returns only currently active queries, typically a small result set |

247 +| Security | Query text may contain unmasked literal values including potentially sensitive data: • Personal information in WHERE clauses or VALUES • Session tokens or credentials • Access should be restricted to authorized personnel only |

248 +| Availability | Available when: • The collector has successfully connected to CockroachDB • The SQL user has `VIEWACTIVITY` or `VIEWACTIVITYREDACTED` privileges • Returns HTTP 503 if the SQL connection cannot be established • Returns HTTP 500 if the query fails • Returns HTTP 504 if the query times out |

249

250 #### Prerequisites

251

214 -##### Grant VIEWACTIVITY access to system tables

252 +##### Grant `VIEWACTIVITY` access to system tables

253 +

254 +The SQL user must have appropriate privileges to view running statements.

255 +

256 +1. Grant `VIEWACTIVITY` (shows full query text) or `VIEWACTIVITYREDACTED` (masks literals):

257 +

258 + ```sql

259 + GRANT SYSTEM VIEWACTIVITY TO netdata_user;

260 + -- OR for privacy:

261 + GRANT SYSTEM VIEWACTIVITYREDACTED TO netdata_user;

262 + ```

263 +

264 + :::info

265 +

266 + - `SHOW CLUSTER STATEMENTS` shows queries across all nodes, not just the connected node

267 + - `VIEWACTIVITYREDACTED` replaces literal values with underscores for privacy

268 + - Queries shown are point-in-time snapshots and may complete between retrieval and display

269

216 -Use a SQL user with VIEWACTIVITY (or VIEWACTIVITYREDACTED) and access to system tables.

270 + :::

271

272

273

@@ -221,25 +275,25 @@ Use a SQL user with VIEWACTIVITY (or VIEWACTIVITYREDACTED) and access to system

275

277 |:---------|:-----|:------------|:--------:|:--------|:--------|

279

280 #### Returns

281

228 -Snapshot of currently running SQL statements.

282 +Real-time snapshot of currently executing SQL statements across all cluster nodes. Each row represents a single active query.

283

285 |:-------|:-----|:-----|:-----------|:------------|

297

298

299

src/go/plugin/go.d/collector/couchbase/integrations/couchbase.md

+50 -20

@@ -82,23 +82,53 @@ This collector exposes real-time functions for interactive troubleshooting in th

83 ### Top Queries

85 -Top N1QL requests from system:completed_requests.

85 +Retrieves completed N1QL query statistics from Couchbase [system:completed_requests](https://docs.couchbase.com/server/current/manage/monitor/monitoring-n1ql-query.html#sys-completed-req) keyspace.

87 -Queries the system:completed_requests keyspace and returns the top entries sorted by the selected column.

87 +This function queries the `system:completed_requests` keyspace which stores information about recently completed N1QL requests. It provides timing metrics, result statistics, and error/warning counts for each completed query.

88 +

89 +Use cases:

90 +- Identify slow N1QL queries consuming the most elapsed time

91 +- Find queries with high error or warning counts

92 +- Analyze query patterns by user to understand workload distribution

93 +

94 +Statement text is truncated at 4096 characters for display purposes.

97 | Aspect | Description |

98 |:-------|:------------|

99 | Name | `Couchbase:top-queries` |

93 -| Performance | Runs N1QL queries against system keyspaces; use top_queries_limit to control response size. |

94 -| Security | Query text may include sensitive literals depending on workload. |

95 -| Availability | Available when the collector can query system keyspaces; returns 503 until the collector is initialized. |

100 +| Require Cloud | yes |

101 +| Performance | Queries `system:completed_requests` via the N1QL query service: • The `completed_requests` keyspace has a configurable size limit (`completed-limit` setting) • Default limit of 500 rows balances usefulness with performance |

102 +| Security | Query text may contain unmasked literal values including potentially sensitive data: • Personal information in WHERE clauses or INSERT values • Business data embedded in queries • Access should be restricted to authorized personnel only |

103 +| Availability | Available when: • The collector has successfully connected to Couchbase • The N1QL (Query) service is running • Returns HTTP 503 if collector is still initializing • Returns HTTP 500 if the query fails • Returns HTTP 504 if the query times out |

104

105 #### Prerequisites

106

99 -##### Grant access to system:completed_requests

107 +##### Grant access to `system:completed_requests`

108 +

109 +The user must have appropriate privileges to query system keyspaces and the N1QL service must be available.

110 +

111 +1. Ensure the N1QL (Query) service is running on the cluster

112 +

113 +2. Grant query system catalog privileges to the monitoring user:

114 +

115 + ```sql

116 + GRANT QUERY_SYSTEM_CATALOG TO netdata_user;

117 + ```

118 +

119 +3. Verify access to `completed_requests`:

120 +

121 + ```sql

122 + SELECT * FROM system:completed_requests LIMIT 1;

123 + ```

124 +

125 + :::info

126 +

127 + - The `system:completed_requests` keyspace stores recently completed queries based on Couchbase server settings `completed-limit` and `completed-threshold`

128 + - Only queries exceeding `completed-threshold` (default 1000ms) are logged to `completed_requests`

129 + - Adjust `completed-threshold` in Couchbase Query Settings to capture faster queries if needed

130

101 -Ensure the user can query system:completed_requests and the N1QL service is available.

131 + :::

132

133

134

@@ -106,25 +136,25 @@ Ensure the user can query system:completed_requests and the N1QL service is avai

136

138 |:---------|:-----|:------------|:--------:|:--------|:--------|

140

141 #### Returns

142

113 -Completed N1QL request statistics.

143 +Completed N1QL request statistics. Each row represents a single completed query with its timing and result metrics.

144

146 |:-------|:-----|:-----|:-----------|:------------|

158

159

160

src/go/plugin/go.d/collector/elasticsearch/integrations/elasticsearch.md

+50 -18

@@ -173,44 +173,76 @@ This collector exposes real-time functions for interactive troubleshooting in th

173

174 ### Top Queries

175

176 -Running queries from the Elasticsearch Tasks API.

176 +Retrieves currently running search tasks from the Elasticsearch [Tasks API](https://www.elastic.co/guide/en/elasticsearch/reference/current/tasks.html).

177

178 -Calls the Tasks API and returns running task details sorted by the selected column.

178 +This function queries the `/_tasks` endpoint filtered for search actions (`*search`), providing a real-time snapshot of all active search operations across all nodes in the cluster.

179 +

180 +Use cases:

181 +- Identify long-running search queries that may be impacting cluster performance

182 +- Monitor active search workload distribution across cluster nodes

183 +- Debug slow or stuck search operations in real-time

184

185

186 | Aspect | Description |

187 |:-------|:------------|

188 | Name | `Elasticsearch:top-queries` |

184 -| Performance | Queries the Tasks API; on large clusters this may return many rows. |

185 -| Security | Task descriptions may include query details. |

186 -| Availability | Available when the collector can query the Tasks API; returns 503 until the collector is initialized. |

189 +| Require Cloud | yes |

190 +| Performance | Queries the `/_tasks` API filtered for search actions: • Lightweight operation with minimal cluster overhead • Returns only currently active search tasks, typically a small result set |

191 +| Security | Task descriptions may contain query details including potentially sensitive information: • Index names and search patterns • Query terms and filter values • Access should be restricted to authorized personnel only |

192 +| Availability | Available when: • The collector has successfully connected to Elasticsearch/OpenSearch • The user has `monitor` or `manage` cluster privileges • Returns HTTP 503 if collector is still initializing • Returns HTTP 500 if the Tasks API query fails • Returns HTTP 504 if the query times out |

193

194 #### Prerequisites

195

190 -No additional configuration is required.

196 +##### Ensure access to Tasks API

197 +

198 +The user must have appropriate privileges to access the Tasks API.

199 +

200 +1. For secured clusters, grant the `monitor` or `manage` cluster privilege:

201 +

202 + ```json

203 + {

204 + "cluster": ["monitor"]

205 + }

206 + ```

207 +

208 +2. Verify access to the Tasks API:

209 +

210 + ```bash

211 + curl -u user:password "http://localhost:9200/_tasks?actions=*search"

212 + ```

213 +

214 +:::info

215 +

216 +- The Tasks API returns only currently running tasks; completed tasks are not stored

217 +- Search tasks can be cancelled using `POST /_tasks/{task_id}/_cancel` if they are cancellable

218 +- Works with both Elasticsearch and OpenSearch clusters

219 +

220 +:::

221 +

222 +

223

224 #### Parameters

225

227 |:---------|:-----|:------------|:--------:|:--------|:--------|

229

230 #### Returns

231

200 -Snapshot of running tasks from the Tasks API.

232 +Real-time snapshot of currently executing search tasks across all cluster nodes. Each row represents a single active search operation.

233

235 |:-------|:-----|:-----|:-----------|:------------|

246

247

248

src/go/plugin/go.d/collector/elasticsearch/integrations/opensearch.md

+50 -18

@@ -173,44 +173,76 @@ This collector exposes real-time functions for interactive troubleshooting in th

173

174 ### Top Queries

175

176 -Running queries from the Elasticsearch Tasks API.

176 +Retrieves currently running search tasks from the Elasticsearch [Tasks API](https://www.elastic.co/guide/en/elasticsearch/reference/current/tasks.html).

177

178 -Calls the Tasks API and returns running task details sorted by the selected column.

178 +This function queries the `/_tasks` endpoint filtered for search actions (`*search`), providing a real-time snapshot of all active search operations across all nodes in the cluster.

179 +

180 +Use cases:

181 +- Identify long-running search queries that may be impacting cluster performance

182 +- Monitor active search workload distribution across cluster nodes

183 +- Debug slow or stuck search operations in real-time

184

185

186 | Aspect | Description |

187 |:-------|:------------|

188 | Name | `Elasticsearch:top-queries` |

184 -| Performance | Queries the Tasks API; on large clusters this may return many rows. |

185 -| Security | Task descriptions may include query details. |

186 -| Availability | Available when the collector can query the Tasks API; returns 503 until the collector is initialized. |

189 +| Require Cloud | yes |

193

194 #### Prerequisites

195

190 -No additional configuration is required.

196 +##### Ensure access to Tasks API

197 +

198 +The user must have appropriate privileges to access the Tasks API.

199 +

200 +1. For secured clusters, grant the `monitor` or `manage` cluster privilege:

201 +

202 + ```json

203 + {

204 + "cluster": ["monitor"]

205 + }

206 + ```

207 +

208 +2. Verify access to the Tasks API:

209 +

210 + ```bash

211 + curl -u user:password "http://localhost:9200/_tasks?actions=*search"

212 + ```

213 +

214 +:::info

215 +

216 +- The Tasks API returns only currently running tasks; completed tasks are not stored

217 +- Search tasks can be cancelled using `POST /_tasks/{task_id}/_cancel` if they are cancellable

218 +- Works with both Elasticsearch and OpenSearch clusters

219 +

220 +:::

221 +

222 +

223

224 #### Parameters

225

227 |:---------|:-----|:------------|:--------:|:--------|:--------|

229

230 #### Returns

231

200 -Snapshot of running tasks from the Tasks API.

232 +Real-time snapshot of currently executing search tasks across all cluster nodes. Each row represents a single active search operation.

233

235 |:-------|:-----|:-----|:-----------|:------------|

246

247

248

src/go/plugin/go.d/collector/mongodb/integrations/mongodb.md

+81 -36

@@ -212,23 +212,68 @@ This collector exposes real-time functions for interactive troubleshooting in th

212

213 ### Top Queries

214

215 -Top queries from MongoDB Profiler (system.profile). WARNING: Query text may contain unmasked literals (potential PII).

215 +Retrieves profiled query statistics from MongoDB [system.profile](https://www.mongodb.com/docs/manual/reference/database-profiler/) collection.

216

217 -Reads from system.profile and returns the top profiled queries sorted by the selected column.

217 +This function queries the `system.profile` collection across all user databases (excluding admin, local, config) to retrieve slow or sampled queries captured by the MongoDB profiler. It provides detailed execution metrics including timing, document counts, and execution plan information.

218 +

219 +Use cases:

220 +- Identify slow queries that exceed the profiling threshold

221 +- Analyze query patterns by examining docs examined vs docs returned ratios

222 +- Detect collection scans (COLLSCAN) that may need index optimization

223 +

224 +Query text is truncated at 4096 characters for display purposes.

225

226

227 | Aspect | Description |

228 |:-------|:------------|

229 | Name | `Mongodb:top-queries` |

223 -| Performance | Requires profiling and reads from system.profile; may add load on busy systems. |

224 -| Security | Query text may contain unmasked literals (potential PII). |

225 -| Availability | Available when profiling is enabled and the collector is initialized; returns 403 if disabled in config. |

230 +| Require Cloud | yes |

231 +| Performance | Reads from `system.profile` collection across all user databases: • Profiling itself adds overhead to MongoDB operations (typically 1-5%) • Default limit of 500 rows balances usefulness with performance |

232 +| Security | Query text may contain unmasked literal values including potentially sensitive data: • Document field values in query filters • Personal information in inserted/updated documents • Access should be restricted to authorized personnel only |

233 +| Availability | Available when: • The collector has successfully connected to MongoDB • Profiling is enabled on at least one user database • Returns HTTP 503 if collector is still initializing or profiling is disabled on all databases • Returns HTTP 500 if the query fails • Returns HTTP 504 if the query times out |

234

235 #### Prerequisites

236

237 ##### Enable MongoDB profiling

238

231 -Enable profiling on the target databases and set top_queries_function_enabled to true.

239 +Database profiling must be enabled on each database you want to monitor, and the function must be enabled in the collector configuration.

240 +

241 +1. Enable profiling on a database (profile slow queries > 100ms):

242 +

243 + ```javascript

244 + use myDatabase

245 + db.setProfilingLevel(1, { slowms: 100 })

246 + ```

247 +

248 +2. Or profile all operations (level 2, use with caution):

249 +

250 + ```javascript

251 + db.setProfilingLevel(2)

252 + ```

253 +

254 +3. Verify profiling status:

255 +

256 + ```javascript

257 + db.getProfilingStatus()

258 + ```

259 +

260 +4. Enable the function in Netdata collector config:

261 +

262 + ```yaml

263 + jobs:

264 + - name: local

265 + uri: mongodb://localhost:27017

266 + top_queries_function_enabled: true

267 + ```

268 +

269 +:::info

270 +

271 +- Profiling level 0 = off, 1 = slow operations only, 2 = all operations

272 +- The `slowms` threshold determines which queries are captured at level 1

273 +- `system.profile` is a capped collection; old entries are automatically removed

274 +- System databases (admin, local, config) are excluded from profiling queries

275 +

276 +:::

277

278

279

@@ -236,42 +281,42 @@ Enable profiling on the target databases and set top_queries_function_enabled to

281

283 |:---------|:-----|:------------|:--------:|:--------|:--------|

285

286 #### Returns

287

243 -Profiled query statistics from system.profile.

288 +Profiled query statistics from `system.profile`. Each row represents a single profiled operation with execution metrics and plan details.

289

291 |:-------|:-----|:-----|:-----------|:------------|

320

321

322

src/go/plugin/go.d/collector/mssql/integrations/microsoft_sql_server.md

+108 -69

@@ -241,23 +241,62 @@ This collector exposes real-time functions for interactive troubleshooting in th

241

242 ### Top Queries

243

244 -Top SQL queries from Query Store.

244 +Retrieves aggregated SQL query performance metrics from Microsoft SQL Server [Query Store](https://learn.microsoft.com/en-us/sql/relational-databases/performance/monitoring-performance-by-using-the-query-store) runtime statistics.

245

246 -Queries Query Store runtime statistics and returns the top entries sorted by the selected column.

246 +This function queries `sys.query_store_runtime_stats` and related views across all databases with Query Store enabled, aggregating execution statistics by query hash. It provides comprehensive timing, I/O, memory, and parallelism metrics.

247 +

248 +Use cases:

249 +- Identify slow or resource-intensive queries consuming excessive CPU time or memory

250 +- Analyze I/O patterns (logical reads, physical reads, writes) to detect bottlenecks

251 +- Monitor parallelism (DOP) and tempdb usage for capacity planning

252 +

253 +Query text is truncated at 4096 characters for display purposes. Columns are dynamically detected based on SQL Server version (some metrics only available in 2016+/2017+).

254

255

256 | Aspect | Description |

257 |:-------|:------------|

258 | Name | `Mssql:top-queries` |

252 -| Performance | Uses Query Store and can be expensive on busy instances. |

253 -| Security | Query Store may contain unmasked literals (potential PII). |

254 -| Availability | Available when Query Store is enabled and the collector is initialized; returns 403 if disabled in config. |

259 +| Require Cloud | yes |

260 +| Performance | Executes dynamic SQL to aggregate Query Store data across all enabled databases: • Execution time depends on Query Store workload and number of monitored databases • Default limit of 500 rows balances completeness with performance |

261 +| Security | Query text may contain unmasked literal values including potentially sensitive data: • Personal information in WHERE clauses or INSERT values • Business data and internal identifiers • Access should be restricted to authorized personnel only |

262 +| Availability | Available when: • The collector has successfully connected to SQL Server • Query Store is enabled on at least one user database • Returns HTTP 503 if collector is still initializing • Returns HTTP 500 if the query fails • Returns HTTP 504 if the query times out |

263

264 #### Prerequisites

265

258 -##### Enable Query Store functions

266 +##### Enable Query Store

267 +

268 +Query Store must be enabled on each database you want to monitor.

269 +

270 +1. Verify Query Store is enabled on your databases:

271 +

272 + ```sql

273 + SELECT name, is_query_store_on

274 + FROM sys.databases

275 + WHERE name NOT IN ('master', 'tempdb', 'model', 'msdb');

276 + ```

277 +

278 +2. Enable Query Store on databases where it is disabled:

279

260 -Enable Query Store and set query_store_function_enabled to true.

280 + ```sql

281 + ALTER DATABASE [YourDatabaseName] SET QUERY_STORE = ON;

282 + ```

283 +

284 +3. Enable the function in Netdata collector config:

285 +

286 + ```yaml

287 + jobs:

288 + - name: local

289 + dsn: "sqlserver://user:pass@localhost:1433"

290 + query_store_function_enabled: true

291 + ```

292 +

293 +:::info

294 +

295 +- Query Store is available in SQL Server 2016+ and Azure SQL Database

296 +- Requires ALTER DATABASE permission to enable Query Store

297 +- System databases (master, tempdb, model, msdb) are excluded from queries

298 +

299 +:::

300

301

302

@@ -265,74 +304,74 @@ Enable Query Store and set query_store_function_enabled to true.

304

306 |:---------|:-----|:------------|:--------:|:--------|:--------|

307 +| Filter By | select | Select the primary sort column. The available options depend on your SQL Server version and include metrics like total execution time, number of calls, CPU time, logical I/O, memory grants, and more. Default is Total Time to focus on most resource-intensive queries. | yes | totalTime | |

308

309 #### Returns

310

272 -Query Store statistics for top queries.

311 +Aggregated query execution statistics from Query Store runtime views, providing comprehensive performance analysis across all monitored databases. Each row represents a unique query pattern (normalized query hash) with cumulative metrics across all its executions.

312

314 |:-------|:-----|:-----|:-----------|:------------|

316 +| Query | string | | | The SQL query text with literal values truncated at 4096 characters. Use this to identify the actual SQL being executed and spot parameterized queries or injection risks. |

318 +| Calls | integer | | | Total number of times this query pattern has been executed. High values indicate frequently run queries that may impact server performance significantly. |

319 +| Total Time | duration | milliseconds | | Cumulative execution time across all query executions. This is a key metric for identifying the most resource-intensive queries in terms of total server time consumption. |

320 +| Avg Time | duration | milliseconds | | Average execution time per query run, calculated as weighted average when execution count is greater than zero. Compare with Total Time to determine if individual executions or high frequency drives resource usage. |

325 +| Avg CPU | duration | milliseconds | | Average CPU time consumed per query execution. High values indicate CPU-intensive operations that may include complex calculations, string manipulations, or excessive function calls. Available in SQL Server 2016+. |

330 +| Avg Logical Reads | float | | | Average number of logical read operations (8KB pages) per execution. High values indicate queries scanning large amounts of data through indexes or table scans. Monitor for I/O subsystem impact. |

334 +| StdDev Logical Reads | float | | hidden | Standard deviation of logical reads. High variability suggests inconsistent access patterns, potentially indicating performance issues with certain queries or data volumes. |

335 +| Avg Logical Writes | float | | | Average number of logical write operations per execution. High values indicate heavy write workloads that may benefit from batching or optimization. |

339 +| StdDev Logical Writes | float | | hidden | Standard deviation of logical writes. High values indicate write performance variability, potentially suggesting inconsistent transaction sizes or periodic bulk operations. |

340 +| Avg Physical Reads | float | | | Average number of physical read operations from storage per execution. High values indicate queries requiring substantial disk I/O for data retrieval, potentially due to full table scans or missing covering indexes. |

343 +| Max Physical Reads | integer | | hidden | Maximum physical reads observed. Extremely high values may indicate storage subsystem bottlenecks, full table scans without covering indexes, or queries processing very large data volumes. |

344 +| StdDev Physical Reads | float | | hidden | Standard deviation of physical reads. High variability suggests inconsistent disk access patterns, potentially indicating intermittent I/O performance issues or storage contention. |

345 +| Avg CLR Time | duration | milliseconds | | Average CLR (Common Language Runtime) time per execution. High values indicate managed code (stored procedures, functions, triggers) with heavy computations, garbage collection pressure, or inefficient memory allocations. Available in SQL Server 2016+. |

350 +| Avg DOP | float | | | Average Degree of Parallelism (DOP) per query. Higher values indicate queries utilizing more CPU cores through parallelism, potentially consuming significant server resources. Values above 1 indicate intra-query parallelism; values of 1 indicate serial execution. |

353 +| Max DOP | integer | | hidden | Maximum DOP observed. Very high values (>4) may indicate aggressive parallelism consuming excessive resources and potentially affecting concurrent workloads. Available in SQL Server 2016+. |

354 +| StdDev DOP | float | | hidden | Standard deviation of DOP. High variability suggests inconsistent parallelism patterns across executions, potentially indicating performance variability based on data characteristics or query complexity. |

355 +| Avg Memory (8KB pages) | float | | | Average memory grant (in 8KB pages) per execution. High values indicate memory-intensive queries that may benefit from index optimization, reduced result sets, or query tuning to reduce working memory usage. |

358 +| Max Memory (8KB pages) | integer | | hidden | Maximum memory grant observed. Spikes may indicate queries with large sort operations, hash joins, temporary table creation, or excessive parameter lengths consuming working memory. |

359 +| StdDev Memory | float | | hidden | Standard deviation of memory grants. High variability suggests inconsistent memory usage patterns, potentially varying by execution parameters, result set sizes, or different code paths being executed. |

360 +| Avg Rows | float | | | Average number of rows processed per query execution. High values indicate queries returning large result sets that may consume significant network bandwidth, memory for result buffers, and client application resources. |

364 +| StdDev Rows | float | | hidden | Standard deviation of rows processed. High variability suggests inconsistent result set sizes, potentially due to varying query filters, parameterized inputs, or different data distributions across executions. |

365 +| Avg Log Bytes | float | | | Average transaction log bytes written per query execution (SQL Server 2017+). High values indicate write-intensive operations (INSERT/UPDATE/DELETE), large transactions, or bulk modifications. This measures WAL activity, not diagnostic logging. |

370 +| Avg TempDB (8KB pages) | float | | | Average tempdb space usage (in 8KB pages) per execution. High values indicate queries that create or use large temporary objects, work tables, sort operations, or have heavy tempdb spillage from disk. High tempdb usage can lead to disk I/O contention and overall performance degradation. |

373 +| Max TempDB (8KB pages) | integer | | hidden | Maximum tempdb space observed. Spikes may indicate queries with large sort operations, hash joins, index spool usage, or temporary table creation consuming substantial tempdb space. Can lead to tempdb autogrow and disk space issues. |

374 +| StdDev TempDB | float | | hidden | Standard deviation of tempdb space usage. High variability suggests inconsistent temporary object usage patterns, potentially varying by query complexity, parameter types, or different data access patterns affecting temporary object creation. |

375

376

377

src/go/plugin/go.d/collector/mysql/integrations/mariadb.md

+120 -47

@@ -190,23 +190,96 @@ This collector exposes real-time functions for interactive troubleshooting in th

190

191 ### Top Queries

192

193 -Top SQL queries from performance_schema.

193 +Retrieves aggregated SQL query performance metrics from MySQL [performance_schema.events_statements_summary_by_digest](https://dev.mysql.com/doc/refman/8.4/en/performance-schema-statement-summary-tables.html) table.

194

195 -Reads performance_schema statement digest tables and returns the top entries sorted by the selected column.

195 +This function queries the `events_statements_summary_by_digest` table which contains aggregated statistics for SQL statements grouped by their digest (normalized query pattern). The function dynamically detects available columns based on your MySQL/MariaDB version.

196 +

197 +Use cases:

198 +- Identify slow queries that consume the most execution time

199 +- Find frequently executed queries that may benefit from optimization

200 +- Detect queries with high lock time, errors, or table scans

201 +

202 +Query text is truncated at 4096 characters for display purposes.

203

204

205 | Aspect | Description |

206 |:-------|:------------|

207 | Name | `Mysql:top-queries` |

201 -| Performance | Requires performance_schema and can be expensive on busy servers. |

202 -| Security | Query text may contain unmasked literals (potential PII). |

203 -| Availability | Available when performance_schema tables are accessible and the collector is initialized. |

208 +| Require Cloud | yes |

209 +| Performance | Queries the `events_statements_summary_by_digest` table: • On busy servers with high query throughput, the digest table can grow large • Default limit of 500 rows balances usefulness with performance |

210 +| Security | Query text may contain unmasked literal values including potentially sensitive data: • Personal information in WHERE clauses or INSERT values • Business data and internal identifiers • Access should be restricted to authorized personnel only |

211 +| Availability | Available when: • The collector has successfully connected to MySQL • Performance Schema is enabled with statement digest collection • Returns HTTP 503 if collector is still initializing • Returns HTTP 500 if the query fails • Returns HTTP 504 if the query times out |

212

213 #### Prerequisites

214

207 -##### Enable performance_schema digest tables

215 +##### Enable performance_schema statement digest collection

216 +

217 +Performance Schema must be enabled and statement instrumentation must be configured to collect digest statistics.

218 +

219 +1. Check if Performance Schema is enabled:

220 + ```sql

221 + SELECT @@performance_schema;

222 + ```

223 +

224 +2. Check statement instrumentation configuration:

225 + ```sql

226 + SELECT * FROM performance_schema.setup_consumers

227 + WHERE NAME LIKE '%statement%';

228 + ```

229 +

230 +3. The following consumers should be enabled:

231 + - `events_statements_current`

232 + - `events_statements_summary_by_digest`

233 +

234 +4. Enable statement consumers if needed:

235 + ```sql

236 + UPDATE performance_schema.setup_consumers

237 + SET ENABLED = 'YES'

238 + WHERE NAME LIKE 'events_statements%';

239 + ```

240 +

241 + :::info

242 +

243 + - Changes to `setup_consumers` take effect immediately without requiring a server restart.

244 + - MariaDB also supports the `events_statements_summary_by_digest` table. Exact consumer names may vary by MariaDB version, so checking `setup_consumers` first as shown above is recommended.

245 +

246 + :::

247 +

248 +5. Verify digest table contains data:

249 + ```sql

250 + SELECT COUNT(*) FROM performance_schema.events_statements_summary_by_digest;

251 + ```

252 +

253 + Note: Statement digest data is accumulated since server startup or since the table was last truncated. To reset statistics:

254 + ```sql

255 + TRUNCATE TABLE performance_schema.events_statements_summary_by_digest;

256 + ```

257 +

258 + Ensure that statement instruments are enabled in the Performance Schema so that statement digest statistics are collected. Refer to your MySQL or MariaDB version documentation for the appropriate configuration options.

259 +

260 +

261 +##### Grant SELECT permission on Performance Schema tables

262 +

263 +The netdata user must have SELECT permission on Performance Schema tables. The standard collector permissions

264 +(USAGE, REPLICATION CLIENT, PROCESS) do not automatically include Performance Schema access.

265 +

266 +1. Grant the required permission:

267 + ```sql

268 + GRANT SELECT ON performance_schema.* TO 'netdata'@'localhost';

269 + FLUSH PRIVILEGES;

270 + ```

271 +

272 + :::info

273 +

274 + The host part (`'localhost'`) should match how the netdata user connects. If connecting via TCP/IP, you may need `'netdata'@'%'` or a specific IP address instead.

275 +

276 + :::

277

209 -Enable performance_schema and grant access to events_statements_summary_by_digest.

278 +2. Verify access:

279 + ```sql

280 + -- As the netdata user:

281 + SELECT COUNT(*) FROM performance_schema.events_statements_summary_by_digest;

282 + ```

283

284

285

@@ -214,52 +287,52 @@ Enable performance_schema and grant access to events_statements_summary_by_diges

287

289 |:---------|:-----|:------------|:--------:|:--------|:--------|

290 +| Filter By | select | Select the primary sort column. The available options depend on your MySQL/MariaDB version and include metrics like total execution time, number of calls, lock time, errors, rows examined, and more. Defaults to total execution time. | yes | totalTime | |

291

292 #### Returns

293

221 -Aggregated statement statistics from performance_schema.

294 +Aggregated statement statistics from Performance Schema, grouped by query digest. Each row represents a unique query pattern with cumulative metrics across all executions.

295

297 |:-------|:-----|:-----|:-----------|:------------|

308 +| Warnings | integer | | | Total number of times this query pattern generated warnings. Warnings may indicate data type conversions, NULL handling issues, or other non-critical problems. |

312 +| Temp Disk Tables | integer | | | Total number of temporary tables created on disk across all executions. Disk-based temporary tables are significantly slower than in-memory tables and may indicate memory pressure or complex operations requiring sorting/grouping. |

313 +| Temp Tables | integer | | | Total number of temporary tables created (both in-memory and on-disk). High values suggest frequent sorting, grouping, or DISTINCT operations. |

314 +| Full Joins | integer | | | Total number of joins that performed a full table scan without using an index. These are typically very expensive operations that should be optimized. |

334 +| Max Controlled Memory | integer | | | Maximum memory controlled by the query executor for this query pattern. Available in MySQL 8.0.31+. Helps identify memory-intensive operations. |

336

337

338

src/go/plugin/go.d/collector/mysql/integrations/mysql.md

+120 -47

@@ -190,23 +190,96 @@ This collector exposes real-time functions for interactive troubleshooting in th

190

191 ### Top Queries

192

193 -Top SQL queries from performance_schema.

194

195 -Reads performance_schema statement digest tables and returns the top entries sorted by the selected column.

196 +

197 +Use cases:

198 +- Identify slow queries that consume the most execution time

199 +- Find frequently executed queries that may benefit from optimization

200 +- Detect queries with high lock time, errors, or table scans

201 +

202 +Query text is truncated at 4096 characters for display purposes.

203

204

205 | Aspect | Description |

206 |:-------|:------------|

207 | Name | `Mysql:top-queries` |

201 -| Performance | Requires performance_schema and can be expensive on busy servers. |

202 -| Security | Query text may contain unmasked literals (potential PII). |

203 -| Availability | Available when performance_schema tables are accessible and the collector is initialized. |

208 +| Require Cloud | yes |

212

213 #### Prerequisites

214

207 -##### Enable performance_schema digest tables

215 +##### Enable performance_schema statement digest collection

216 +

217 +Performance Schema must be enabled and statement instrumentation must be configured to collect digest statistics.

218 +

219 +1. Check if Performance Schema is enabled:

220 + ```sql

221 + SELECT @@performance_schema;

222 + ```

223 +

224 +2. Check statement instrumentation configuration:

225 + ```sql

226 + SELECT * FROM performance_schema.setup_consumers

227 + WHERE NAME LIKE '%statement%';

228 + ```

229 +

230 +3. The following consumers should be enabled:

231 + - `events_statements_current`

232 + - `events_statements_summary_by_digest`

233 +

234 +4. Enable statement consumers if needed:

235 + ```sql

236 + UPDATE performance_schema.setup_consumers

237 + SET ENABLED = 'YES'

238 + WHERE NAME LIKE 'events_statements%';

239 + ```

240 +

241 + :::info

242 +

243 + - Changes to `setup_consumers` take effect immediately without requiring a server restart.

244 + - MariaDB also supports the `events_statements_summary_by_digest` table. Exact consumer names may vary by MariaDB version, so checking `setup_consumers` first as shown above is recommended.

245 +

246 + :::

247 +

248 +5. Verify digest table contains data:

249 + ```sql

250 + SELECT COUNT(*) FROM performance_schema.events_statements_summary_by_digest;

251 + ```

252 +

253 + Note: Statement digest data is accumulated since server startup or since the table was last truncated. To reset statistics:

254 + ```sql

255 + TRUNCATE TABLE performance_schema.events_statements_summary_by_digest;

256 + ```

257 +

259 +

260 +

261 +##### Grant SELECT permission on Performance Schema tables

262 +

263 +The netdata user must have SELECT permission on Performance Schema tables. The standard collector permissions

264 +(USAGE, REPLICATION CLIENT, PROCESS) do not automatically include Performance Schema access.

265 +

266 +1. Grant the required permission:

267 + ```sql

268 + GRANT SELECT ON performance_schema.* TO 'netdata'@'localhost';

269 + FLUSH PRIVILEGES;

270 + ```

271 +

272 + :::info

273 +

274 + The host part (`'localhost'`) should match how the netdata user connects. If connecting via TCP/IP, you may need `'netdata'@'%'` or a specific IP address instead.

275 +

276 + :::

277

209 -Enable performance_schema and grant access to events_statements_summary_by_digest.

278 +2. Verify access:

279 + ```sql

280 + -- As the netdata user:

281 + SELECT COUNT(*) FROM performance_schema.events_statements_summary_by_digest;

282 + ```

283

284

285

@@ -214,52 +287,52 @@ Enable performance_schema and grant access to events_statements_summary_by_diges

287

289 |:---------|:-----|:------------|:--------:|:--------|:--------|

291

292 #### Returns

293

221 -Aggregated statement statistics from performance_schema.

294 +Aggregated statement statistics from Performance Schema, grouped by query digest. Each row represents a unique query pattern with cumulative metrics across all executions.

295

297 |:-------|:-----|:-----|:-----------|:------------|

308 +| Warnings | integer | | | Total number of times this query pattern generated warnings. Warnings may indicate data type conversions, NULL handling issues, or other non-critical problems. |

313 +| Temp Tables | integer | | | Total number of temporary tables created (both in-memory and on-disk). High values suggest frequent sorting, grouping, or DISTINCT operations. |

314 +| Full Joins | integer | | | Total number of joins that performed a full table scan without using an index. These are typically very expensive operations that should be optimized. |

334 +| Max Controlled Memory | integer | | | Maximum memory controlled by the query executor for this query pattern. Available in MySQL 8.0.31+. Helps identify memory-intensive operations. |

336

337

338

src/go/plugin/go.d/collector/mysql/integrations/percona_mysql.md

+120 -47

@@ -190,23 +190,96 @@ This collector exposes real-time functions for interactive troubleshooting in th

190

191 ### Top Queries

192

193 -Top SQL queries from performance_schema.

194

195 -Reads performance_schema statement digest tables and returns the top entries sorted by the selected column.

196 +

197 +Use cases:

198 +- Identify slow queries that consume the most execution time

199 +- Find frequently executed queries that may benefit from optimization

200 +- Detect queries with high lock time, errors, or table scans

201 +

202 +Query text is truncated at 4096 characters for display purposes.

203

204

205 | Aspect | Description |

206 |:-------|:------------|

207 | Name | `Mysql:top-queries` |

201 -| Performance | Requires performance_schema and can be expensive on busy servers. |

202 -| Security | Query text may contain unmasked literals (potential PII). |

203 -| Availability | Available when performance_schema tables are accessible and the collector is initialized. |

208 +| Require Cloud | yes |

212

213 #### Prerequisites

214

207 -##### Enable performance_schema digest tables

215 +##### Enable performance_schema statement digest collection

216 +

217 +Performance Schema must be enabled and statement instrumentation must be configured to collect digest statistics.

218 +

219 +1. Check if Performance Schema is enabled:

220 + ```sql

221 + SELECT @@performance_schema;

222 + ```

223 +

224 +2. Check statement instrumentation configuration:

225 + ```sql

226 + SELECT * FROM performance_schema.setup_consumers

227 + WHERE NAME LIKE '%statement%';

228 + ```

229 +

230 +3. The following consumers should be enabled:

231 + - `events_statements_current`

232 + - `events_statements_summary_by_digest`

233 +

234 +4. Enable statement consumers if needed:

235 + ```sql

236 + UPDATE performance_schema.setup_consumers

237 + SET ENABLED = 'YES'

238 + WHERE NAME LIKE 'events_statements%';

239 + ```

240 +

241 + :::info

242 +

243 + - Changes to `setup_consumers` take effect immediately without requiring a server restart.

244 + - MariaDB also supports the `events_statements_summary_by_digest` table. Exact consumer names may vary by MariaDB version, so checking `setup_consumers` first as shown above is recommended.

245 +

246 + :::

247 +

248 +5. Verify digest table contains data:

249 + ```sql

250 + SELECT COUNT(*) FROM performance_schema.events_statements_summary_by_digest;

251 + ```

252 +

253 + Note: Statement digest data is accumulated since server startup or since the table was last truncated. To reset statistics:

254 + ```sql

255 + TRUNCATE TABLE performance_schema.events_statements_summary_by_digest;

256 + ```

257 +

259 +

260 +

261 +##### Grant SELECT permission on Performance Schema tables

262 +

263 +The netdata user must have SELECT permission on Performance Schema tables. The standard collector permissions

264 +(USAGE, REPLICATION CLIENT, PROCESS) do not automatically include Performance Schema access.

265 +

266 +1. Grant the required permission:

267 + ```sql

268 + GRANT SELECT ON performance_schema.* TO 'netdata'@'localhost';

269 + FLUSH PRIVILEGES;

270 + ```

271 +

272 + :::info

273 +

274 + The host part (`'localhost'`) should match how the netdata user connects. If connecting via TCP/IP, you may need `'netdata'@'%'` or a specific IP address instead.

275 +

276 + :::

277

209 -Enable performance_schema and grant access to events_statements_summary_by_digest.

278 +2. Verify access:

279 + ```sql

280 + -- As the netdata user:

281 + SELECT COUNT(*) FROM performance_schema.events_statements_summary_by_digest;

282 + ```

283

284

285

@@ -214,52 +287,52 @@ Enable performance_schema and grant access to events_statements_summary_by_diges

287

289 |:---------|:-----|:------------|:--------:|:--------|:--------|

291

292 #### Returns

293

221 -Aggregated statement statistics from performance_schema.

294 +Aggregated statement statistics from Performance Schema, grouped by query digest. Each row represents a unique query pattern with cumulative metrics across all executions.

295

297 |:-------|:-----|:-----|:-----------|:------------|

308 +| Warnings | integer | | | Total number of times this query pattern generated warnings. Warnings may indicate data type conversions, NULL handling issues, or other non-critical problems. |

313 +| Temp Tables | integer | | | Total number of temporary tables created (both in-memory and on-disk). High values suggest frequent sorting, grouping, or DISTINCT operations. |

314 +| Full Joins | integer | | | Total number of joins that performed a full table scan without using an index. These are typically very expensive operations that should be optimized. |

334 +| Max Controlled Memory | integer | | | Maximum memory controlled by the query executor for this query pattern. Available in MySQL 8.0.31+. Helps identify memory-intensive operations. |

336

337

338

src/go/plugin/go.d/collector/oracledb/integrations/oracle_db.md

+107 -42

@@ -143,23 +143,55 @@ This collector exposes real-time functions for interactive troubleshooting in th

143

144 ### Top Queries

145

146 -Top SQL statements from V$SQLSTATS. WARNING: Query text may contain unmasked literals (potential PII).

146 +Retrieves aggregated SQL statement performance metrics from Oracle [V$SQLSTATS](https://docs.oracle.com/en/database/oracle/oracle-database/19/refrn/V-SQLSTATS.html) view.

147

148 -Queries V$SQLSTATS and returns the top entries sorted by the selected column.

148 +This function queries `V$SQLSTATS` which provides SQL execution statistics aggregated across all cursors for each SQL statement. Statistics include execution counts, timing metrics, I/O operations, and resource consumption.

149 +

150 +Use cases:

151 +- Identify slow queries consuming the most total execution time

152 +- Find queries with high buffer gets or disk reads for I/O optimization

153 +- Analyze CPU-intensive queries for resource tuning

154 +

155 +Query text is truncated at 4096 characters for display purposes.

156

157

158 | Aspect | Description |

159 |:-------|:------------|

160 | Name | `Oracledb:top-queries` |

154 -| Performance | Queries system views and may be expensive on busy databases. |

155 -| Security | Query text may contain unmasked literals (potential PII). |

156 -| Availability | Available when the collector can query Oracle system views; returns errors if SQL is unavailable. |

161 +| Require Cloud | yes |

162 +| Performance | Queries `V$SQLSTATS` which is a lightweight view optimized for statistics retrieval: • On busy databases with many SQL statements, the query may take longer • Default limit of 500 rows balances usefulness with performance |

163 +| Security | Query text may contain unmasked literal values including potentially sensitive data: • Personal information in WHERE clauses or INSERT values • Business data and internal identifiers • Access should be restricted to authorized personnel only |

164 +| Availability | Available when: • The collector has successfully connected to Oracle DB • The user has SELECT privilege on `V$SQLSTATS` • Returns HTTP 503 if the connection cannot be established • Returns HTTP 500 if the query fails • Returns HTTP 504 if the query times out |

165

166 #### Prerequisites

167

168 ##### Grant access to V$SQLSTATS

169

162 -Use a SQL user with access to V$SQLSTATS and a working SQL connection.

170 +The monitoring user must have SELECT privilege on `V$SQLSTATS` and related views.

171 +

172 +1. Grant the required privileges:

173 +

174 + ```sql

175 + -- Note: Use V_$ (with underscore) for GRANT - this is the base fixed view

176 + -- Queries use the V$ public synonym

177 + GRANT SELECT ON V_$SQLSTATS TO netdata;

178 + -- Or grant the broader role:

179 + GRANT SELECT_CATALOG_ROLE TO netdata;

180 + ```

181 +

182 +2. Verify access:

183 +

184 + ```sql

185 + SELECT COUNT(*) FROM V$SQLSTATS WHERE ROWNUM <= 1;

186 + ```

187 +

188 +:::info

189 +

190 +- `V$SQLSTATS` is available in Oracle 10g and later

191 +- The view aggregates statistics across all child cursors for each SQL statement

192 +- Some columns like `MODULE` and `ACTION` require applications to set them via `DBMS_APPLICATION_INFO`

193 +

194 +:::

195

196

197

@@ -167,48 +199,81 @@ Use a SQL user with access to V$SQLSTATS and a working SQL connection.

199

201 |:---------|:-----|:------------|:--------:|:--------|:--------|

203

204 #### Returns

205

174 -Aggregated SQL statistics from V$SQLSTATS.

206 +Aggregated SQL statistics from `V$SQLSTATS`. Each row represents a unique SQL statement with cumulative metrics across all executions.

207

209 |:-------|:-----|:-----|:-----------|:------------|

224

225 ### Running Queries

226

195 -Currently running SQL statements from V$SESSION. WARNING: Query text may contain unmasked literals (potential PII).

227 +Retrieves currently executing SQL statements from Oracle [V$SESSION](https://docs.oracle.com/en/database/oracle/oracle-database/19/refrn/V-SESSION.html) view.

228

197 -Queries V$SESSION and returns running statements sorted by the selected column.

229 +This function queries `V$SESSION` joined with `V$SQL` to provide a real-time snapshot of all active user sessions currently executing SQL statements. It shows session details, elapsed time, and the SQL being executed.

230 +

231 +Use cases:

232 +- Identify long-running queries that may be blocking other sessions

233 +- Monitor active workload and session distribution

234 +- Debug stuck or slow queries in real-time

235 +

236 +Query text is truncated at 4096 characters for display purposes.

237

238

239 | Aspect | Description |

240 |:-------|:------------|

241 | Name | `Oracledb:running-queries` |

203 -| Performance | Queries system views and may be expensive on busy databases. |

204 -| Security | Query text may contain unmasked literals (potential PII). |

205 -| Availability | Available when the collector can query Oracle system views; returns errors if SQL is unavailable. |

242 +| Require Cloud | yes |

243 +| Performance | Queries `V$SESSION` joined with `V$SQL` for currently active sessions: • Lightweight operation as it only returns currently active user sessions • Default limit of 500 rows (rarely reached for running queries) |

244 +| Security | Query text may contain unmasked literal values including potentially sensitive data: • Personal information in WHERE clauses or INSERT values • Business data and credentials in query parameters • Access should be restricted to authorized personnel only |

245 +| Availability | Available when: • The collector has successfully connected to Oracle DB • The user has SELECT privilege on `V$SESSION` and `V$SQL` • Returns HTTP 503 if the connection cannot be established • Returns HTTP 500 if the query fails • Returns HTTP 504 if the query times out |

246

247 #### Prerequisites

248

249 ##### Grant access to V$SESSION

250

211 -Use a SQL user with access to V$SESSION and a working SQL connection.

251 +The monitoring user must have SELECT privilege on `V$SESSION` and `V$SQL`.

252 +

253 +1. Grant the required privileges:

254 +

255 + ```sql

256 + -- Note: Use V_$ (with underscore) for GRANT - this is the base fixed view

257 + -- Queries use the V$ public synonym

258 + GRANT SELECT ON V_$SESSION TO netdata;

259 + GRANT SELECT ON V_$SQL TO netdata;

260 + -- Or grant the broader role:

261 + GRANT SELECT_CATALOG_ROLE TO netdata;

262 + ```

263 +

264 +2. Verify access:

265 +

266 + ```sql

267 + SELECT COUNT(*) FROM V$SESSION WHERE ROWNUM <= 1;

268 + ```

269 +

270 +:::info

271 +

272 +- Only USER sessions with ACTIVE status and a current SQL ID are returned

273 +- The elapsed time is based on `LAST_CALL_ET` which resets when a new SQL starts

274 +- BACKGROUND sessions (Oracle internal processes) are filtered out

275 +

276 +:::

277

278

279

@@ -216,26 +281,26 @@ Use a SQL user with access to V$SESSION and a working SQL connection.

281

283 |:---------|:-----|:------------|:--------:|:--------|:--------|

285

286 #### Returns

287

223 -Snapshot of currently running SQL sessions.

288 +Real-time snapshot of currently executing SQL statements. Each row represents an active user session with its current SQL.

289

291 |:-------|:-----|:-----|:-----------|:------------|

304

305

306

src/go/plugin/go.d/collector/postgres/integrations/postgresql.md

+85 -50

@@ -234,23 +234,58 @@ This collector exposes real-time functions for interactive troubleshooting in th

234

235 ### Top Queries

236

237 -Top SQL queries from pg_stat_statements.

237 +Retrieves aggregated SQL query performance metrics from PostgreSQL [pg_stat_statements](https://www.postgresql.org/docs/current/pgstatstatements.html) extension.

238

239 -Reads pg_stat_statements and returns the top entries sorted by the selected column.

239 +This function queries `pg_stat_statements` which tracks execution statistics for all SQL statements. Statistics include execution counts, timing metrics, I/O operations, and resource consumption. Columns are dynamically detected based on your PostgreSQL version.

240 +

241 +Use cases:

242 +- Identify slow queries consuming the most total execution time

243 +- Find queries with high shared block reads for I/O optimization

244 +- Analyze temp block usage to detect queries needing memory tuning

245 +

246 +Query text is truncated at 4096 characters for display purposes.

247

248

249 | Aspect | Description |

250 |:-------|:------------|

251 | Name | `Postgres:top-queries` |

245 -| Performance | Requires pg_stat_statements and can be expensive on busy servers. |

246 -| Security | Query text may contain unmasked literals (potential PII). |

247 -| Availability | Available when pg_stat_statements is available and the collector is initialized. |

252 +| Require Cloud | yes |

253 +| Performance | Queries `pg_stat_statements` which maintains statistics in shared memory: • On busy servers with many unique queries, the extension may consume significant memory • Default limit of 500 rows balances usefulness with performance |

254 +| Security | Query text may contain unmasked literal values including potentially sensitive data: • Personal information in WHERE clauses or INSERT values • Business data and internal identifiers • Access should be restricted to authorized personnel only |

255 +| Availability | Available when: • The `pg_stat_statements` extension is installed in the database • The collector has successfully connected to PostgreSQL • Returns HTTP 503 if extension is not installed (with instructions to install) • Returns HTTP 500 if the query fails • Returns HTTP 504 if the query times out |

256

257 #### Prerequisites

258

259 ##### Enable pg_stat_statements

260

253 -Install and enable the pg_stat_statements extension.

261 +The `pg_stat_statements` extension must be installed and configured.

262 +

263 +1. Add to `postgresql.conf`:

264 +

265 + ```ini

266 + shared_preload_libraries = 'pg_stat_statements'

267 + ```

268 +

269 +2. Restart PostgreSQL, then create the extension:

270 +

271 + ```sql

272 + CREATE EXTENSION pg_stat_statements;

273 + ```

274 +

275 +3. Verify the extension is working:

276 +

277 + ```sql

278 + SELECT COUNT(*) FROM pg_stat_statements;

279 + ```

280 +

281 +:::info

282 +

283 +- `pg_stat_statements` requires a server restart to load the shared library

284 +- Statistics can be reset with `SELECT pg_stat_statements_reset()`

285 +- The `pg_stat_statements.max` parameter controls maximum tracked statements (default 5000)

286 +- Enable `track_io_timing` for block read/write timing metrics (may add slight overhead)

287 +

288 +:::

289

290

291

@@ -258,56 +293,56 @@ Install and enable the pg_stat_statements extension.

293

295 |:---------|:-----|:------------|:--------:|:--------|:--------|

297

298 #### Returns

299

265 -Aggregated query statistics from pg_stat_statements.

300 +Aggregated query statistics from `pg_stat_statements`. Each row represents a unique query pattern with cumulative metrics across all executions.

301

303 |:-------|:-----|:-----|:-----------|:------------|

346

347

348

src/go/plugin/go.d/collector/proxysql/integrations/proxysql.md

+32 -28

@@ -176,54 +176,58 @@ This collector exposes real-time functions for interactive troubleshooting in th

176

177 ### Top Queries

178

179 -Top SQL queries from ProxySQL query digest stats.

179 +Retrieves aggregated query statistics from ProxySQL's [stats_mysql_query_digest](https://proxysql.com/documentation/stats-statistics/#stats_mysql_query_digest) table.

180

181 -Queries stats_mysql_query_digest and returns the top entries sorted by the selected column.

181 +This function queries the `stats_mysql_query_digest` table which stores runtime statistics for all queries proxied through ProxySQL, aggregated by query digest (normalized query pattern). It provides timing metrics, execution counts, and error statistics for each unique query pattern.

182 +

183 +Use cases:

184 +- Identify slow queries consuming excessive total execution time

185 +- Find high-frequency queries that may benefit from caching

186 +- Monitor query error rates across backends

187 +

188 +Query text is truncated at 4096 characters for display purposes.

189

190

191 | Aspect | Description |

192 |:-------|:------------|

193 | Name | `Proxysql:top-queries` |

187 -| Performance | Uses ProxySQL stats tables and can be expensive on busy systems. |

188 -| Security | Query text may contain unmasked literals (potential PII). |

189 -| Availability | Available when the collector can query ProxySQL stats; returns errors if the SQL connection is unavailable. |

194 +| Require Cloud | yes |

195 +| Performance | Queries ProxySQL admin interface for digest statistics: • Reads from in-memory `stats_mysql_query_digest` table • Default limit of 500 rows balances completeness with performance • Data is aggregated in-memory by ProxySQL from active connections |

196 +| Security | Query text may contain unmasked literal values including potentially sensitive data: • Personal information in WHERE clauses or INSERT values • Business data embedded in queries • Access should be restricted to authorized personnel only |

197 +| Availability | Available when: • The collector has successfully connected to ProxySQL admin interface • Returns HTTP 503 if the connection cannot be established • Returns HTTP 500 if the query fails • Returns HTTP 504 if the query times out |

198

199 #### Prerequisites

200

193 -##### Grant access to stats_mysql_query_digest

194 -

195 -Ensure the ProxySQL user can read stats_mysql_query_digest.

196 -

197 -

201 +No additional configuration is required.

202

203 #### Parameters

204

206 |:---------|:-----|:------------|:--------:|:--------|:--------|

208

209 #### Returns

210

207 -Query digest statistics from ProxySQL.

211 +Aggregated query digest statistics from ProxySQL, providing comprehensive performance analysis across all monitored MySQL backends. Each row represents a unique query pattern (normalized digest) with cumulative metrics across all its executions.

212

214 |:-------|:-----|:-----|:-----------|:------------|

216 +| Query | string | | | The SQL query text with literal values truncated at 4096 characters. Use this to identify the actual SQL being executed and spot parameterized queries or injection risks. |

217 +| Schema | string | | | Database name where the query was executed. Essential for multi-database analysis to identify which database or backend is experiencing query load. |

220 +| Calls | integer | | | Total number of times this query pattern has been executed. High values indicate frequently run queries that may impact server performance significantly. |

221 +| Total Time | duration | milliseconds | | Cumulative execution time across all query executions. This is a key metric for identifying the most resource-intensive queries in terms of total server time consumption. |

225 +| Rows Affected | integer | | | Total number of rows modified by INSERT, UPDATE, DELETE, or REPLACE statements. Useful for tracking write workloads and data modification patterns. |

226 +| Rows Sent | integer | | | Total number of rows returned to the client by SELECT statements. High values may indicate queries returning large result sets that consume significant network bandwidth and client resources. |

227 +| Errors | integer | | | Total number of times this query pattern resulted in an error. Non-zero values require investigation into the underlying SQL syntax, permission issues, or constraint violations. |

228 +| Warnings | integer | | | Total number of times this query pattern generated a warning. Warnings may indicate data type conversions, NULL handling issues, or other non-critical SQL problems that should be reviewed. |

231

232

233

src/go/plugin/go.d/collector/redis/integrations/redis.md

+22 -14

@@ -109,17 +109,25 @@ This collector exposes real-time functions for interactive troubleshooting in th

109

110 ### Top Queries

111

112 -Slow commands from Redis SLOWLOG. WARNING: Command arguments may contain unmasked literals (potential PII).

112 +Retrieves slow command entries from Redis [SLOWLOG](https://redis.io/docs/latest/commands/slowlog/).

113

114 -Reads Redis SLOWLOG and returns the top entries sorted by the selected column.

114 +This function executes the `SLOWLOG GET` command to retrieve entries of commands that exceeded the configured execution time threshold (`slowlog-log-slower-than`). It provides command details, execution duration, and client information for each slow command.

115 +

116 +Use cases:

117 +- Identify slow commands that may need optimization

118 +- Analyze command patterns to detect performance hotspots

119 +- Investigate client sources of slow commands

120 +

121 +Command text is truncated at 4096 characters for display purposes.

122

123

124 | Aspect | Description |

125 |:-------|:------------|

126 | Name | `Redis:top-queries` |

120 -| Performance | Uses SLOWLOG GET and may return many entries; use top_queries_limit to control size. |

121 -| Security | Command arguments may contain unmasked literals (potential PII). |

122 -| Availability | Available when the collector is initialized; returns 503 if the collector is still connecting. |

127 +| Require Cloud | yes |

128 +| Performance | Executes `SLOWLOG GET` command to retrieve entries from Redis memory: • Minimal overhead as SLOWLOG is stored in memory • Default limit of 500 entries balances completeness with performance • Large slowlogs with many entries may take slightly longer to transfer |

129 +| Security | Command arguments may contain unmasked literal values including potentially sensitive data: • Redis keys and values in command arguments • Application-specific identifiers or session tokens • Access should be restricted to authorized personnel only |

130 +| Availability | Available when: • The collector has successfully connected to Redis • SLOWLOG is enabled (`slowlog-log-slower-than` > 0) • Returns HTTP 503 if collector is still initializing • Returns HTTP 500 if the command fails • Returns HTTP 504 if the command times out |

131

132 #### Prerequisites

133

@@ -129,21 +137,21 @@ No additional configuration is required.

137

139 |:---------|:-----|:------------|:--------:|:--------|:--------|

141

142 #### Returns

143

136 -Slowlog entries with command timing and metadata.

144 +Slowlog entries with command timing and client metadata, providing insight into Redis performance patterns. Each row represents a single slow command execution that exceeded the configured threshold.

145

147 |:-------|:-----|:-----|:-----------|:------------|

140 -| ID | integer | | hidden | |

150 +| Command | string | | | Full command text including all arguments. May contain sensitive data (keys, values) depending on application implementation. Truncated to 4096 characters. |

155

156

157

src/go/plugin/go.d/collector/rethinkdb/integrations/rethinkdb.md

+41 -17

@@ -104,23 +104,47 @@ This collector exposes real-time functions for interactive troubleshooting in th

104

105 ### Running Queries

106

107 -Currently running queries from rethinkdb.jobs. WARNING: Query text may contain unmasked literals (potential PII).

107 +Retrieves currently executing queries from the RethinkDB [rethinkdb.jobs](https://rethinkdb.com/docs/system-jobs/) system table.

108

109 -Queries rethinkdb.jobs and returns running queries sorted by the selected column.

109 +This function queries the `rethinkdb.jobs` system table which contains information about background tasks and queries currently running on the cluster. It provides query text, execution duration, client information, and involved servers.

110 +

111 +Use cases:

112 +- Identify long-running queries that may be blocking resources

113 +- Monitor active query load across the cluster

114 +- Investigate client connections generating heavy workloads

115 +

116 +Query text is truncated at 4096 characters for display purposes.

117

118

119 | Aspect | Description |

120 |:-------|:------------|

121 | Name | `Rethinkdb:running-queries` |

115 -| Performance | Uses system tables and may be expensive on busy clusters. |

116 -| Security | Query text may contain unmasked literals (potential PII). |

117 -| Availability | Available when the collector is initialized; returns 503 if the collector is still connecting. |

122 +| Require Cloud | yes |

123 +| Performance | Queries the `rethinkdb.jobs` system table: • Minimal overhead as it reads from an in-memory system table • Default limit of 500 rows balances completeness with performance • Returns only currently active queries (no historical data) |

124 +| Security | Query text may contain unmasked literal values including potentially sensitive data: • Document field values in filter conditions • User-provided data in insert/update operations • Access should be restricted to authorized personnel only |

125 +| Availability | Available when: • The collector has successfully connected to RethinkDB • The user has admin access to `rethinkdb.jobs` table • Returns HTTP 503 if collector is still initializing • Returns HTTP 500 if the query fails • Returns HTTP 504 if the query times out |

126

127 #### Prerequisites

128

121 -##### Grant admin access to rethinkdb.jobs

129 +##### Grant admin access to `rethinkdb.jobs`

130 +

131 +The user must have admin privileges to query the `rethinkdb.jobs` system table.

132 +

133 +1. Connect with an admin user account that has access to system tables

134 +

135 +2. Verify access to `rethinkdb.jobs`:

136

123 -Use an admin user with access to rethinkdb.jobs and ensure the connection is working.

137 + ```javascript

138 + r.db('rethinkdb').table('jobs').run(conn)

139 + ```

140 +

141 +:::info

142 +

143 +- The `rethinkdb.jobs` table is only accessible to admin users

144 +- Non-admin users will receive a permission error when attempting to query this table

145 +- The collector's regular metrics do not require admin access

146 +

147 +:::

148

149

150

@@ -128,22 +152,22 @@ Use an admin user with access to rethinkdb.jobs and ensure the connection is wor

152

154 |:---------|:-----|:------------|:--------:|:--------|:--------|

156

157 #### Returns

158

135 -Snapshot of running queries from rethinkdb.jobs.

159 +Currently running queries from the `rethinkdb.jobs` system table. Each row represents a single active query with its execution context.

160

162 |:-------|:-----|:-----|:-----------|:------------|

171

172

173

src/go/plugin/go.d/collector/snmp/integrations/snmp_devices.md

+34 -26

@@ -132,17 +132,25 @@ This collector exposes real-time functions for interactive troubleshooting in th

132

133 ### Network Interfaces

134

135 -Network interface traffic and status metrics.

135 +Provides detailed network interface traffic and status metrics from SNMP-enabled devices.

136

137 -Uses the latest cached SNMP interface data, filters by the selected type group, and sorts by the default column.

137 +This function queries cached SNMP interface data collected during regular polling cycles and presents it in a sortable, filterable table. Each row represents a network interface on the monitored SNMP device, with comprehensive metrics for traffic analysis, error monitoring, and operational status tracking.

138 +

139 +Use cases:

140 +- Identify top bandwidth-consuming interfaces on routers, switches, and access points

141 +- Monitor interface operational and administrative status for network health

142 +- Investigate packet errors, discards, and unusual traffic patterns

143 +

144 +Data is sourced from the IF-MIB (RFC 2863) interface counters and is cached from the last successful SNMP collection. No additional SNMP requests are triggered when calling this function.

145

146

147 | Aspect | Description |

148 |:-------|:------------|

149 | Name | `Snmp:interfaces` |

143 -| Performance | Uses cached data only and does not trigger additional SNMP requests. Large devices may return many rows. |

144 -| Security | Exposes interface names and counters only. |

145 -| Availability | Available after the collector has completed at least one data collection; returns 503 until cache is ready. |

150 +| Require Cloud | no |

151 +| Performance | Uses cached SNMP data only, no additional SNMP requests are triggered: • Responses are instantaneous from memory cache • Large devices with many interfaces may return many rows |

152 +| Security | Exposes interface names, operational status, and traffic counters only: • No packet payloads or authentication credentials are exposed • No device configuration details are exposed |

153 +| Availability | Available when: • The collector has completed at least one data collection cycle • Interface data is cached from the last successful SNMP collection • Returns HTTP 503 if cache is not ready yet |

154

155 #### Prerequisites

156

@@ -152,33 +160,33 @@ No additional configuration is required.

160

162 |:---------|:-----|:------------|:--------:|:--------|:--------|

164

165 #### Returns

166

159 -Table of interface traffic and status from cached SNMP data.

167 +Network interface metrics from cached SNMP data, including traffic rates, packet statistics, operational status, and error counters. Each row represents one physical or virtual interface.

168

170 |:-------|:-----|:-----|:-----------|:------------|

173 +| Type Group | string | | | Custom categorization mapping IANA interface types into practical groups: Ethernet (physical Ethernet interfaces), Aggregation (LAG/port-channels, bonds), Virtual (VLANs, loopbacks), or Other (all remaining types) |

174 +| Admin Status | string | | | Administrative state configured on the interface: up (enabled for use), down (administratively disabled), or testing (currently in test mode). Different from operational status. |

175 +| Oper Status | string | | | Current operational state of the interface: up (operational and passing traffic), down (not operational), testing (in test mode), unknown (status cannot be determined), dormant (waiting for external actions), notPresent (interface removed but configuration remains), or lowerLayerDown (interface down due to lower-layer issues) |

186 +| Discards In | float | packets/s | | Rate of inbound packets deliberately discarded by the device (often due to resource constraints, security policies, or unrecognized frames). Unlike errors, the interface may have been functioning correctly but chose to drop the packet. |

190

191

192

src/go/plugin/go.d/collector/yugabytedb/integrations/yugabytedb.md

+88 -40

@@ -340,23 +340,51 @@ This collector exposes real-time functions for interactive troubleshooting in th

340

341 ### Top Queries

342

343 -Top SQL queries from pg_stat_statements. WARNING: Query text may contain unmasked literals (potential PII).

343 +Retrieves aggregated query statistics from the PostgreSQL-compatible [pg_stat_statements](https://docs.yugabyte.com/preview/explore/query-1-performance/pg-stat-statements/) extension in YSQL.

344

345 -Reads pg_stat_statements and returns the top entries sorted by the selected column.

345 +This function queries the `pg_stat_statements` view which tracks execution statistics for all SQL statements executed on the YSQL layer. It provides timing metrics, execution counts, and row statistics for each unique query pattern.

346 +

347 +Use cases:

348 +- Identify slow queries consuming excessive total execution time

349 +- Find high-frequency queries that may benefit from optimization

350 +- Analyze query patterns by database and user

351 +

352 +Query text is truncated at 4096 characters for display purposes.

353

354

355 | Aspect | Description |

356 |:-------|:------------|

357 | Name | `Yugabytedb:top-queries` |

351 -| Performance | Executes SQL queries and may be expensive on busy clusters; use top_queries_limit and sql_timeout. |

352 -| Security | Query text may contain unmasked literals (potential PII). |

353 -| Availability | Available when YSQL is accessible; returns errors if the SQL connection is unavailable. |

358 +| Require Cloud | yes |

359 +| Performance | Queries the `pg_stat_statements` view via YSQL connection: • Default limit of 500 rows balances completeness with performance • Use `sql_timeout` to prevent long-running queries |

360 +| Security | Query text may contain unmasked literal values including potentially sensitive data: • Personal information in WHERE clauses or INSERT values • Business data embedded in queries • Access should be restricted to authorized personnel only |

361 +| Availability | Available when: • The collector has successfully connected to YSQL • The `pg_stat_statements` extension is installed • Returns HTTP 503 if the SQL connection cannot be established or extension is not installed • Returns HTTP 500 if the query fails • Returns HTTP 504 if the query times out |

362

363 #### Prerequisites

364

357 -##### Enable pg_stat_statements for YSQL

365 +##### Enable pg_stat_statements extension

366 +

367 +The `pg_stat_statements` extension must be installed in the target YSQL database.

368 +

369 +1. Install the extension:

370 +

371 + ```sql

372 + CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

373 + ```

374 +

375 +2. Verify access:

376 +

377 + ```sql

378 + SELECT * FROM pg_stat_statements LIMIT 1;

379 + ```

380 +

381 +:::info

382 +

383 +- The extension tracks statistics for all SQL statements executed

384 +- Statistics can be reset with `SELECT pg_stat_statements_reset()`

385 +- YugabyteDB uses PostgreSQL-compatible extensions

386

359 -Install and enable pg_stat_statements and configure a YSQL DSN.

387 +:::

388

389

390

@@ -364,45 +392,65 @@ Install and enable pg_stat_statements and configure a YSQL DSN.

392

394 |:---------|:-----|:------------|:--------:|:--------|:--------|

396

397 #### Returns

398

371 -Aggregated query statistics from pg_stat_statements.

399 +Aggregated query statistics from `pg_stat_statements`. Each row represents a unique query pattern with cumulative metrics across all executions.

400

402 |:-------|:-----|:-----|:-----------|:------------|

414

415 ### Running Queries

416

389 -Currently running SQL statements from pg_stat_activity. WARNING: Query text may contain unmasked literals (potential PII).

417 +Retrieves currently executing statements from the PostgreSQL-compatible [pg_stat_activity](https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW) view in YSQL.

418 +

419 +This function queries `pg_stat_activity` to show all non-idle backend processes with their current query, state, and timing information. It excludes idle connections to focus on active workload.

420 +

421 +Use cases:

422 +- Identify long-running queries that may need investigation

423 +- Monitor active connections and their current state

424 +- Investigate blocked or waiting queries

425

391 -Reads pg_stat_activity and returns running statements sorted by the selected column.

426 +Query text is truncated at 4096 characters for display purposes.

427

428

429 | Aspect | Description |

430 |:-------|:------------|

431 | Name | `Yugabytedb:running-queries` |

397 -| Performance | Executes SQL queries and may be expensive on busy clusters; use top_queries_limit and sql_timeout. |

398 -| Security | Query text may contain unmasked literals (potential PII). |

399 -| Availability | Available when YSQL is accessible; returns errors if the SQL connection is unavailable. |

432 +| Require Cloud | yes |

433 +| Performance | Queries the `pg_stat_activity` view via YSQL connection: • Returns only non-idle connections to reduce result size • Default limit of 500 rows balances completeness with performance • Use `sql_timeout` to prevent long-running queries |

434 +| Security | Query text may contain unmasked literal values including potentially sensitive data: • Personal information in WHERE clauses or INSERT values • Business data embedded in queries • Access should be restricted to authorized personnel only |

435 +| Availability | Available when: • The collector has successfully connected to YSQL • Returns HTTP 503 if the SQL connection cannot be established • Returns HTTP 500 if the query fails • Returns HTTP 504 if the query times out |

436

437 #### Prerequisites

438

403 -##### Grant access to pg_stat_activity

439 +##### Grant access to all queries (optional)

440

405 -Configure a YSQL DSN and grant access to pg_stat_activity.

441 +By default, users can only see their own queries in `pg_stat_activity`. To view all users' queries, grant the `pg_read_all_stats` role:

442 +

443 +```sql

444 +GRANT pg_read_all_stats TO your_user;

445 +```

446 +

447 +:::info

448 +

449 +- The `yugabyte` superuser can see all queries by default

450 +- Without elevated privileges, only the user's own queries are visible

451 +- Idle connections are filtered out from results

452 +

453 +:::

454

455

456

@@ -410,25 +458,25 @@ Configure a YSQL DSN and grant access to pg_stat_activity.

458

460 |:---------|:-----|:------------|:--------:|:--------|:--------|

462

463 #### Returns

464

417 -Snapshot of currently running SQL statements.

465 +Currently running SQL statements from `pg_stat_activity`. Each row represents an active backend process with its current query and execution context.

466

468 |:-------|:-----|:-----|:-----------|:------------|

421 -| PID | string | | hidden | |

480

481

482