@cryptotaxi247 / netdata-1 / commits / 1ca1e6007

docs(go.d): improve functions metadata (#21626)

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Ilya Mashchenko committed Jan 24, 2026 at 10:41 UTC 1ca1e6007f22f512704e69764c4d516f82b772fa
14 files changed +965 -492
src/go/plugin/go.d/collector/clickhouse/metadata.yaml
+52 -25
@@ -259,102 +259,129 @@ modules:
259 - id: top-queries
260 name: Top Queries
261 description: |
262 - Top SQL queries from ClickHouse system.query_log.
262 + Retrieves and aggregates SQL query performance metrics from ClickHouse [system.query_log](https://clickhouse.com/docs/en/operations/system-tables/query_log) table.
263
264 - Queries system.query_log, aggregates by query, and returns the top entries sorted by the selected column.
264 + 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.
265 +
266 + Use cases:
267 + - Identify slow queries that consume the most execution time
268 + - Find frequently executed queries that may benefit from optimization
269 + - Analyze I/O patterns by examining read/written rows and bytes
270 +
271 + Query text is truncated at 4096 characters for display purposes.
272 parameters:
273 - id: __sort
274 name: Filter By
268 - description: Select the primary sort column (options are derived from sortable columns in the response).
275 + description: Select the primary sort column. The available options include total execution time, number of calls, rows read, and more. Defaults to total execution time to focus on most resource-intensive queries.
276 type: select
277 required: true
278 default: totalTime
279 options: []
280 returns:
274 - description: Aggregated query statistics from system.query_log.
281 + description: 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.
282 columns:
283 - name: Query ID
284 type: string
285 unit: ""
286 visibility: hidden
280 - description: ""
287 + description: "Unique hash identifier for the normalized query pattern. Queries with identical structure but different literal values share the same hash."
288 - name: Query
289 type: string
290 unit: ""
284 - description: ""
291 + description: "SQL query text from one of the executions. Truncated to 4096 characters. Use this to identify the actual SQL being executed."
292 - name: Database
293 type: string
294 unit: ""
288 - description: ""
295 + description: "Database name where the query was executed. Empty string for queries without a database context or system queries."
296 - name: User
297 type: string
298 unit: ""
292 - description: ""
299 + description: "ClickHouse user that executed the query. Useful for identifying query sources and implementing per-user resource monitoring."
300 - name: Calls
301 type: integer
302 unit: ""
296 - description: ""
303 + description: "Total number of times this query pattern has been executed. High values indicate frequently run queries that impact overall server load."
304 - name: Total Time
305 type: duration
306 unit: "milliseconds"
300 - description: ""
307 + description: "Cumulative execution time across all executions. High values indicate queries that consume significant server resources over time."
308 - name: Avg Time
309 type: duration
310 unit: "milliseconds"
304 - description: ""
311 + description: "Average execution time per query run. Use this to compare typical performance across different query patterns."
312 - name: Min Time
313 type: duration
314 unit: "milliseconds"
315 visibility: hidden
309 - description: ""
316 + description: "Minimum execution time observed for a single execution. Helps identify best-case query performance."
317 - name: Max Time
318 type: duration
319 unit: "milliseconds"
320 visibility: hidden
314 - description: ""
321 + description: "Maximum execution time observed for a single execution. Large gaps between min and max may indicate data skew or resource contention."
322 - name: Read Rows
323 type: integer
324 unit: ""
318 - description: ""
325 + description: "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."
326 - name: Read Bytes
327 type: integer
328 unit: ""
322 - description: ""
329 + description: "Total bytes read from storage across all executions. Indicates I/O load and data transfer volume for the query pattern."
330 - name: Written Rows
331 type: integer
332 unit: ""
333 visibility: hidden
327 - description: ""
334 + description: "Total number of rows written across all executions. Relevant for INSERT, CREATE, or materialized view queries."
335 - name: Written Bytes
336 type: integer
337 unit: ""
338 visibility: hidden
332 - description: ""
339 + description: "Total bytes written across all executions. Indicates storage impact of write operations."
340 - name: Result Rows
341 type: integer
342 unit: ""
336 - description: ""
343 + description: "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."
344 - name: Result Bytes
345 type: integer
346 unit: ""
347 visibility: hidden
341 - description: ""
348 + description: "Total bytes returned to clients across all executions. Large values may indicate queries returning more data than necessary."
349 - name: Max Memory
350 type: float
351 unit: ""
352 visibility: hidden
346 - description: ""
353 + description: "Maximum memory used during any single execution. High values may indicate queries at risk of hitting memory limits under load."
354 performance: |
348 - Uses system.query_log and can be expensive on busy systems. Use limits to control response size.
355 + Queries `system.query_log` table and aggregates by `normalized_query_hash`:<br/>• On busy systems with high query throughput, the table can grow large<br/>• Default limit of 500 rows balances usefulness with performance
356 security: |
350 - Query text may include sensitive literals depending on server settings.
357 + Query text may contain unmasked literal values including potentially sensitive data:<br/>• Personal information in query parameters<br/>• Business data and internal identifiers<br/>• Access should be restricted to authorized personnel only
358 prerequisites:
359 list:
353 - - title: Grant access to system.query_log
360 + - title: Grant access to `system.query_log`
361 description: |
355 - Ensure the Netdata user can read system.query_log on the target ClickHouse instance.
362 + Ensure the Netdata user can read `system.query_log` on the target ClickHouse instance.
363 +
364 + 1. Verify `query_log` is enabled (enabled by default):
365 +
366 + ```sql
367 + SELECT * FROM system.query_log LIMIT 1;
368 + ```
369 +
370 + 2. If using a dedicated monitoring user, grant SELECT access:
371 +
372 + ```sql
373 + GRANT SELECT ON system.query_log TO netdata_user;
374 + ```
375 +
376 + :::info
377 +
378 + - The `query_log` table is enabled by default in ClickHouse
379 + - Only queries with `type='QueryFinish'` are included in the results
380 + - The `normalized_query_hash` column is used for grouping when available
381 +
382 + :::
383 availability: |
357 - Available when the collector can query system tables; returns 503 if system.query_log is not available.
384 + Available when:<br/>• The collector has successfully connected to ClickHouse<br/>• `system.query_log` table is accessible<br/>• Returns HTTP 503 if `system.query_log` is not accessible<br/>• Returns HTTP 500 if the query fails<br/>• Returns HTTP 504 if the query times out
385 metrics:
386 folding:
387 title: Metrics
src/go/plugin/go.d/collector/cockroachdb/metadata.yaml
+105 -53
@@ -26,7 +26,7 @@ modules:
26 method_description: |
27 It scrapes Prometheus metrics from the CockroachDB `/_status/vars` endpoint.
28
29 - It also provides `top-queries` and `running-queries` functions using SQL statement statistics (`crdb_internal.cluster_statement_statistics`) and `SHOW CLUSTER STATEMENTS`.
29 + It also provides `top-queries` and `running-queries` functions using SQL statement statistics (`crdb_internal.cluster_statement_statistics`) and the `SHOW CLUSTER STATEMENTS` command.
30 supported_platforms:
31 include: []
32 exclude: []
@@ -35,7 +35,7 @@ modules:
35 description: |
36 The `top-queries` and `running-queries` functions require:
37
38 - - A SQL user with `VIEWACTIVITY` (or `VIEWACTIVITYREDACTED`) privileges.
38 + - A SQL user with `VIEWACTIVITY` or `VIEWACTIVITYREDACTED` privileges.
39 - Access to `crdb_internal.cluster_statement_statistics` (may require `SET allow_unsafe_internals = on` on newer versions).
40 default_behavior:
41 auto_detection:
@@ -254,200 +254,252 @@ modules:
254 - id: top-queries
255 name: Top Queries
256 description: |
257 - Top SQL statements from crdb_internal.cluster_statement_statistics.
258 -
259 - Queries crdb_internal.cluster_statement_statistics and returns the top entries sorted by the selected column.
257 + 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.
258 +
259 + 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.
260 +
261 + Use cases:
262 + - Identify slow queries consuming the most total execution time
263 + - Find frequently executed queries that may benefit from optimization
264 + - Analyze row read/write patterns to detect inefficient queries
265 +
266 + Query text is truncated at 4096 characters for display purposes.
267 parameters:
268 - id: __sort
269 name: Filter By
263 - description: Select the primary sort column (options are derived from sortable columns in the response).
270 + description: Select the primary sort column. Options include total time, executions, rows read, rows written, and more. Defaults to total time to focus on most resource-intensive queries.
271 type: select
272 required: true
273 default: totalTime
274 options: []
275 returns:
269 - description: Aggregated SQL statement statistics.
276 + description: Aggregated SQL statement statistics grouped by fingerprint. Each row represents a unique query pattern with cumulative metrics across all executions.
277 columns:
278 - name: Fingerprint ID
279 type: string
280 unit: ""
281 visibility: hidden
275 - description: ""
282 + description: "Unique hash identifier for the normalized query pattern. Queries with identical structure but different literal values share the same fingerprint."
283 - name: Query
284 type: string
285 unit: ""
279 - description: ""
286 + description: "Normalized SQL statement text with literals replaced. Truncated to 4096 characters."
287 - name: Database
288 type: string
289 unit: ""
283 - description: ""
290 + description: "Database name where the query was executed. Empty for queries without database context."
291 - name: Application
292 type: string
293 unit: ""
287 - description: ""
294 + description: "Application name that executed the query. Useful for identifying query sources across services."
295 - name: Statement Type
296 type: string
297 unit: ""
298 visibility: hidden
292 - description: ""
299 + description: "Type of SQL statement (SELECT, INSERT, UPDATE, DELETE, etc.)."
300 - name: Distributed
301 type: string
302 unit: ""
303 visibility: hidden
297 - description: ""
304 + description: "Whether the query used DistSQL execution (true/false). Distributed queries span multiple nodes."
305 - name: Full Scan
306 type: string
307 unit: ""
308 visibility: hidden
302 - description: ""
309 + description: "Whether the query performed a full table scan (true/false). Full scans may indicate missing indexes."
310 - name: Implicit Txn
311 type: string
312 unit: ""
313 visibility: hidden
307 - description: ""
314 + description: "Whether the statement ran in an implicit transaction (true/false)."
315 - name: Vectorized
316 type: string
317 unit: ""
318 visibility: hidden
312 - description: ""
319 + description: "Whether the query used vectorized execution (true/false). Vectorized execution improves performance for analytical queries."
320 - name: Executions
321 type: integer
322 unit: ""
316 - description: ""
323 + description: "Total number of times this query pattern has been executed. High values indicate frequently run queries."
324 - name: Total Time
325 type: duration
326 unit: "milliseconds"
320 - description: ""
327 + description: "Cumulative service latency across all executions (mean time × executions). High values indicate queries consuming significant cluster resources."
328 - name: Mean Time
329 type: duration
330 unit: "milliseconds"
324 - description: ""
331 + description: "Average service latency per execution. Use this to compare typical performance across query patterns."
332 - name: Run Time
333 type: duration
334 unit: "milliseconds"
335 visibility: hidden
329 - description: ""
336 + description: "Average time spent executing the query after planning. Excludes parse and plan time."
337 - name: Plan Time
338 type: duration
339 unit: "milliseconds"
340 visibility: hidden
334 - description: ""
341 + description: "Average time spent generating the query execution plan. High values may indicate complex queries or stale statistics."
342 - name: Parse Time
343 type: duration
344 unit: "milliseconds"
345 visibility: hidden
339 - description: ""
346 + description: "Average time spent parsing the SQL statement."
347 - name: Rows Read
348 type: integer
349 unit: ""
343 - description: ""
350 + description: "Total rows read across all executions. High values relative to rows returned suggest missing indexes or inefficient scans."
351 - name: Rows Written
352 type: integer
353 unit: ""
347 - description: ""
354 + description: "Total rows written across all executions. Indicates write workload for INSERT, UPDATE, DELETE statements."
355 - name: Rows Returned
356 type: integer
357 unit: ""
351 - description: ""
358 + description: "Total rows returned to clients across all executions. Compare with rows read to assess query efficiency."
359 - name: Bytes Read
360 type: integer
361 unit: ""
362 visibility: hidden
356 - description: ""
363 + description: "Total bytes read from storage across all executions. Indicates I/O load for the query pattern."
364 - name: Max Retries
365 type: integer
366 unit: ""
367 visibility: hidden
361 - description: ""
368 + description: "Maximum number of automatic retries observed for this query pattern. High values indicate transaction contention."
369 performance: |
363 - Executes SQL queries against system tables and may be expensive on busy clusters.
370 + Queries the `crdb_internal.cluster_statement_statistics` table which aggregates data across the cluster:<br/>• On busy clusters with high query throughput, this query may take longer<br/>• Default limit of 500 rows balances usefulness with performance
371 security: |
365 - Query text may contain unmasked literals (potential PII).
372 + Query text may contain unmasked literal values including potentially sensitive data:<br/>• Personal information in WHERE clauses or INSERT values<br/>• Business data and internal identifiers<br/>• Access should be restricted to authorized personnel only
373 prerequisites:
374 list:
368 - - title: Grant VIEWACTIVITY access to cluster statement stats
375 + - title: Grant `VIEWACTIVITY` access to cluster statement stats
376 description: |
370 - Use a SQL user with VIEWACTIVITY (or VIEWACTIVITYREDACTED) and access to crdb_internal.cluster_statement_statistics.
377 + The SQL user must have appropriate privileges to access statement statistics.
378 +
379 + 1. Grant `VIEWACTIVITY` (shows full query text) or `VIEWACTIVITYREDACTED` (masks literals):
380 +
381 + ```sql
382 + GRANT SYSTEM VIEWACTIVITY TO netdata_user;
383 + -- OR for privacy:
384 + GRANT SYSTEM VIEWACTIVITYREDACTED TO netdata_user;
385 + ```
386 +
387 + 2. On newer CockroachDB versions, access to `crdb_internal` may require:
388 +
389 + ```sql
390 + SET allow_unsafe_internals = on;
391 + ```
392 +
393 + :::info
394 +
395 + - The collector automatically sets `allow_unsafe_internals = on` for the session when querying `crdb_internal` tables (required on newer versions)
396 + - `VIEWACTIVITYREDACTED` replaces literal values with underscores for privacy
397 + - Statement statistics are collected by default but can be disabled via cluster settings
398 +
399 + :::
400 availability: |
372 - Requires SQL DSN configuration and access to system tables; returns errors if DSN is missing or SQL is unavailable.
401 + Available when:<br/>• The collector has successfully connected to CockroachDB<br/>• The SQL user has `VIEWACTIVITY` or `VIEWACTIVITYREDACTED` privileges<br/>• Returns HTTP 503 if the SQL connection cannot be established<br/>• Returns HTTP 500 if the query fails<br/>• Returns HTTP 504 if the query times out
402 - id: running-queries
403 name: Running Queries
404 description: |
376 - Currently running SQL statements from SHOW CLUSTER STATEMENTS.
377 -
378 - Queries SHOW CLUSTER STATEMENTS and returns running statements sorted by the selected column.
405 + Retrieves currently executing SQL statements across the CockroachDB cluster using [SHOW CLUSTER STATEMENTS](https://www.cockroachlabs.com/docs/stable/show-statements).
406 +
407 + 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.
408 +
409 + Use cases:
410 + - Identify long-running queries that may be blocking other operations
411 + - Monitor active workload distribution across the cluster
412 + - Debug stuck or slow queries in real-time
413 +
414 + Query text is truncated at 4096 characters for display purposes.
415 parameters:
416 - id: __sort
417 name: Filter By
382 - description: Select the primary sort column (options are derived from sortable columns in the response).
418 + description: Select the primary sort column. Defaults to elapsed time to show longest-running queries first.
419 type: select
420 required: true
421 default: elapsedMs
422 options: []
423 returns:
388 - description: Snapshot of currently running SQL statements.
424 + description: Real-time snapshot of currently executing SQL statements across all cluster nodes. Each row represents a single active query.
425 columns:
426 - name: Query ID
427 type: string
428 unit: ""
429 visibility: hidden
394 - description: ""
430 + description: "Unique identifier for this specific query execution. Can be used with CANCEL QUERY if needed."
431 - name: Query
432 type: string
433 unit: ""
398 - description: ""
434 + description: "The SQL statement currently being executed. Truncated to 4096 characters."
435 - name: User
436 type: string
437 unit: ""
402 - description: ""
438 + description: "Database user executing the query. Useful for identifying workload by user."
439 - name: Application
440 type: string
441 unit: ""
406 - description: ""
442 + description: "Application name from the client connection. Helps identify which service is running the query."
443 - name: Client Address
444 type: string
445 unit: ""
446 visibility: hidden
411 - description: ""
447 + description: "IP address of the client connection. Useful for identifying query sources."
448 - name: Node ID
449 type: string
450 unit: ""
451 visibility: hidden
416 - description: ""
452 + description: "CockroachDB node currently executing the query. Helps identify workload distribution."
453 - name: Session ID
454 type: string
455 unit: ""
456 visibility: hidden
421 - description: ""
457 + description: "Session identifier for the connection. Multiple queries may share a session."
458 - name: Phase
459 type: string
460 unit: ""
425 - description: ""
461 + description: "Current execution phase (executing, preparing, etc.). Indicates query progress."
462 - name: Distributed
463 type: string
464 unit: ""
465 visibility: hidden
430 - description: ""
466 + description: "Whether the query is using distributed execution across multiple nodes."
467 - name: Start Time
468 type: string
469 unit: ""
470 visibility: hidden
435 - description: ""
471 + description: "Timestamp when the query started executing."
472 - name: Elapsed
473 type: duration
474 unit: "milliseconds"
439 - description: ""
475 + description: "Time elapsed since query started. High values indicate long-running queries that may need investigation."
476 performance: |
441 - Executes SQL queries against system tables and may be expensive on busy clusters.
477 + Executes the `SHOW CLUSTER STATEMENTS` command which queries all nodes in the cluster:<br/>• Lightweight operation with minimal overhead<br/>• Returns only currently active queries, typically a small result set
478 security: |
443 - Query text may contain unmasked literals (potential PII).
479 + Query text may contain unmasked literal values including potentially sensitive data:<br/>• Personal information in WHERE clauses or VALUES<br/>• Session tokens or credentials<br/>• Access should be restricted to authorized personnel only
480 prerequisites:
481 list:
446 - - title: Grant VIEWACTIVITY access to system tables
482 + - title: Grant `VIEWACTIVITY` access to system tables
483 description: |
448 - Use a SQL user with VIEWACTIVITY (or VIEWACTIVITYREDACTED) and access to system tables.
484 + The SQL user must have appropriate privileges to view running statements.
485 +
486 + 1. Grant `VIEWACTIVITY` (shows full query text) or `VIEWACTIVITYREDACTED` (masks literals):
487 +
488 + ```sql
489 + GRANT SYSTEM VIEWACTIVITY TO netdata_user;
490 + -- OR for privacy:
491 + GRANT SYSTEM VIEWACTIVITYREDACTED TO netdata_user;
492 + ```
493 +
494 + :::info
495 +
496 + - `SHOW CLUSTER STATEMENTS` shows queries across all nodes, not just the connected node
497 + - `VIEWACTIVITYREDACTED` replaces literal values with underscores for privacy
498 + - Queries shown are point-in-time snapshots and may complete between retrieval and display
499 +
500 + :::
501 availability: |
450 - Requires SQL DSN configuration and access to system tables; returns errors if DSN is missing or SQL is unavailable.
502 + Available when:<br/>• The collector has successfully connected to CockroachDB<br/>• The SQL user has `VIEWACTIVITY` or `VIEWACTIVITYREDACTED` privileges<br/>• Returns HTTP 503 if the SQL connection cannot be established<br/>• Returns HTTP 500 if the query fails<br/>• Returns HTTP 504 if the query times out
503 metrics:
504 folding:
505 title: Metrics
src/go/plugin/go.d/collector/couchbase/metadata.yaml
+49 -20
@@ -198,80 +198,109 @@ modules:
198 - id: top-queries
199 name: Top Queries
200 description: |
201 - Top N1QL requests from system:completed_requests.
201 + 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.
202
203 - Queries the system:completed_requests keyspace and returns the top entries sorted by the selected column.
203 + 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.
204 +
205 + Use cases:
206 + - Identify slow N1QL queries consuming the most elapsed time
207 + - Find queries with high error or warning counts
208 + - Analyze query patterns by user to understand workload distribution
209 +
210 + Statement text is truncated at 4096 characters for display purposes.
211 parameters:
212 - id: __sort
213 name: Filter By
207 - description: Select the primary sort column (options are derived from sortable columns in the response).
214 + description: Select the primary sort column. Options include elapsed time, service time, request time, and result count. Defaults to elapsed time to focus on slowest queries.
215 type: select
216 required: true
217 default: elapsedTime
218 options: []
219 returns:
213 - description: Completed N1QL request statistics.
220 + description: Completed N1QL request statistics. Each row represents a single completed query with its timing and result metrics.
221 columns:
222 - name: Request ID
223 type: string
224 unit: ""
225 visibility: hidden
219 - description: ""
226 + description: "Unique identifier for the N1QL request. Can be used for correlation with Couchbase logs."
227 - name: Request Time
228 type: timestamp
229 unit: ""
223 - description: ""
230 + description: "Timestamp when the request was received by the query service."
231 - name: Statement
232 type: string
233 unit: ""
227 - description: ""
234 + description: "The N1QL statement that was executed. Truncated to 4096 characters."
235 - name: Elapsed Time
236 type: duration
237 unit: "milliseconds"
231 - description: ""
238 + description: "Total time from request receipt to response completion, including queue time, planning, execution, and result streaming."
239 - name: Service Time
240 type: duration
241 unit: "milliseconds"
235 - description: ""
242 + description: "Time spent actively processing the request, excluding network latency and queue wait time. Compare with elapsed time to identify network or queueing delays."
243 - name: Result Count
244 type: integer
245 unit: ""
239 - description: ""
246 + description: "Number of documents/rows returned by the query. High values may indicate queries returning excessive data."
247 - name: Result Size
248 type: integer
249 unit: ""
250 visibility: hidden
244 - description: ""
251 + description: "Total size of the result set in bytes. Large result sizes may indicate inefficient queries or missing projections."
252 - name: Error Count
253 type: integer
254 unit: ""
255 visibility: hidden
249 - description: ""
256 + description: "Number of errors encountered during query execution. Non-zero values require investigation."
257 - name: Warning Count
258 type: integer
259 unit: ""
260 visibility: hidden
254 - description: ""
261 + description: "Number of warnings generated during query execution. Warnings may indicate suboptimal query patterns or index usage."
262 - name: User
263 type: string
264 unit: ""
258 - description: ""
265 + description: "Couchbase user who executed the query. Useful for identifying workload by user or application."
266 - name: Client Context ID
267 type: string
268 unit: ""
269 visibility: hidden
263 - description: ""
270 + description: "Client-provided context identifier for request tracking and correlation."
271 performance: |
265 - Runs N1QL queries against system keyspaces; use top_queries_limit to control response size.
272 + Queries `system:completed_requests` via the N1QL query service:<br/>• The `completed_requests` keyspace has a configurable size limit (`completed-limit` setting)<br/>• Default limit of 500 rows balances usefulness with performance
273 security: |
267 - Query text may include sensitive literals depending on workload.
274 + Query text may contain unmasked literal values including potentially sensitive data:<br/>• Personal information in WHERE clauses or INSERT values<br/>• Business data embedded in queries<br/>• Access should be restricted to authorized personnel only
275 prerequisites:
276 list:
270 - - title: Grant access to system:completed_requests
277 + - title: Grant access to `system:completed_requests`
278 description: |
272 - Ensure the user can query system:completed_requests and the N1QL service is available.
279 + The user must have appropriate privileges to query system keyspaces and the N1QL service must be available.
280 +
281 + 1. Ensure the N1QL (Query) service is running on the cluster
282 +
283 + 2. Grant query system catalog privileges to the monitoring user:
284 +
285 + ```sql
286 + GRANT QUERY_SYSTEM_CATALOG TO netdata_user;
287 + ```
288 +
289 + 3. Verify access to `completed_requests`:
290 +
291 + ```sql
292 + SELECT * FROM system:completed_requests LIMIT 1;
293 + ```
294 +
295 + :::info
296 +
297 + - The `system:completed_requests` keyspace stores recently completed queries based on Couchbase server settings `completed-limit` and `completed-threshold`
298 + - Only queries exceeding `completed-threshold` (default 1000ms) are logged to `completed_requests`
299 + - Adjust `completed-threshold` in Couchbase Query Settings to capture faster queries if needed
300 +
301 + :::
302 availability: |
274 - Available when the collector can query system keyspaces; returns 503 until the collector is initialized.
303 + Available when:<br/>• The collector has successfully connected to Couchbase<br/>• The N1QL (Query) service is running<br/>• Returns HTTP 503 if collector is still initializing<br/>• Returns HTTP 500 if the query fails<br/>• Returns HTTP 504 if the query times out
304 metrics:
305 folding:
306 title: Metrics
src/go/plugin/go.d/collector/elasticsearch/metadata.yaml
+50 -18
@@ -283,70 +283,102 @@ modules:
283 - id: top-queries
284 name: Top Queries
285 description: |
286 - Running queries from the Elasticsearch Tasks API.
287 -
288 - Calls the Tasks API and returns running task details sorted by the selected column.
286 + Retrieves currently running search tasks from the Elasticsearch [Tasks API](https://www.elastic.co/guide/en/elasticsearch/reference/current/tasks.html).
287 +
288 + 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.
289 +
290 + Use cases:
291 + - Identify long-running search queries that may be impacting cluster performance
292 + - Monitor active search workload distribution across cluster nodes
293 + - Debug slow or stuck search operations in real-time
294 parameters:
295 - id: __sort
296 name: Filter By
292 - description: Select the primary sort column (options are derived from sortable columns in the response).
297 + description: Select the primary sort column. Options include running time, start time, and task ID. Defaults to running time to show longest-running searches first.
298 type: select
299 required: true
300 default: runningTime
301 options: []
302 returns:
298 - description: Snapshot of running tasks from the Tasks API.
303 + description: Real-time snapshot of currently executing search tasks across all cluster nodes. Each row represents a single active search operation.
304 columns:
305 - name: Task ID
306 type: string
307 unit: ""
308 visibility: hidden
304 - description: ""
309 + description: "Unique identifier for the task in format `nodeId:taskId`. Can be used with the Task Management API to cancel long-running tasks."
310 - name: Node ID
311 type: string
312 unit: ""
308 - description: ""
313 + description: "Internal identifier of the node executing this search task."
314 - name: Node Name
315 type: string
316 unit: ""
312 - description: ""
317 + description: "Human-readable name of the node executing the search. Useful for identifying workload distribution across the cluster."
318 - name: Action
319 type: string
320 unit: ""
316 - description: ""
321 + description: "The search action being performed (e.g., `indices:data/read/search`). Indicates the type of search operation."
322 - name: Type
323 type: string
324 unit: ""
325 visibility: hidden
321 - description: ""
326 + description: "Task type classification (typically `transport` for search tasks)."
327 - name: Description
328 type: string
329 unit: ""
325 - description: ""
330 + description: "Detailed description of the search task including indices being searched and query details. Truncated to 4096 characters."
331 - name: Start Time
332 type: timestamp
333 unit: ""
329 - description: ""
334 + description: "Timestamp when the search task started executing."
335 - name: Running Time
336 type: duration
337 unit: "milliseconds"
333 - description: ""
338 + description: "Time elapsed since the search started. High values indicate long-running searches that may need investigation or cancellation."
339 - name: Cancellable
340 type: boolean
341 unit: ""
342 visibility: hidden
338 - description: ""
343 + description: "Whether the task supports cancellation via the Task Management API."
344 - name: Cancelled
345 type: boolean
346 unit: ""
347 visibility: hidden
343 - description: ""
348 + description: "Whether a cancellation request has been issued for this task."
349 performance: |
345 - Queries the Tasks API; on large clusters this may return many rows.
350 + Queries the `/_tasks` API filtered for search actions:<br/>• Lightweight operation with minimal cluster overhead<br/>• Returns only currently active search tasks, typically a small result set
351 security: |
347 - Task descriptions may include query details.
352 + Task descriptions may contain query details including potentially sensitive information:<br/>• Index names and search patterns<br/>• Query terms and filter values<br/>• Access should be restricted to authorized personnel only
353 + prerequisites:
354 + list:
355 + - title: Ensure access to Tasks API
356 + description: |
357 + The user must have appropriate privileges to access the Tasks API.
358 +
359 + 1. For secured clusters, grant the `monitor` or `manage` cluster privilege:
360 +
361 + ```json
362 + {
363 + "cluster": ["monitor"]
364 + }
365 + ```
366 +
367 + 2. Verify access to the Tasks API:
368 +
369 + ```bash
370 + curl -u user:password "http://localhost:9200/_tasks?actions=*search"
371 + ```
372 +
373 + :::info
374 +
375 + - The Tasks API returns only currently running tasks; completed tasks are not stored
376 + - Search tasks can be cancelled using `POST /_tasks/{task_id}/_cancel` if they are cancellable
377 + - Works with both Elasticsearch and OpenSearch clusters
378 +
379 + :::
380 availability: |
349 - Available when the collector can query the Tasks API; returns 503 until the collector is initialized.
381 + Available when:<br/>• The collector has successfully connected to Elasticsearch/OpenSearch<br/>• The user has `monitor` or `manage` cluster privileges<br/>• Returns HTTP 503 if collector is still initializing<br/>• Returns HTTP 500 if the Tasks API query fails<br/>• Returns HTTP 504 if the query times out
382 metrics:
383 folding:
384 title: Metrics
src/go/plugin/go.d/collector/mongodb/metadata.yaml
+80 -36
@@ -172,159 +172,203 @@ modules:
172 - id: top-queries
173 name: Top Queries
174 description: |
175 - Top queries from MongoDB Profiler (system.profile). WARNING: Query text may contain unmasked literals (potential PII).
175 + Retrieves profiled query statistics from MongoDB [system.profile](https://www.mongodb.com/docs/manual/reference/database-profiler/) collection.
176
177 - Reads from system.profile and returns the top profiled queries sorted by the selected column.
177 + 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.
178 +
179 + Use cases:
180 + - Identify slow queries that exceed the profiling threshold
181 + - Analyze query patterns by examining docs examined vs docs returned ratios
182 + - Detect collection scans (COLLSCAN) that may need index optimization
183 +
184 + Query text is truncated at 4096 characters for display purposes.
185 parameters:
186 - id: __sort
187 name: Filter By
181 - description: Select the primary sort column (options are derived from sortable columns in the response).
188 + description: Select the primary sort column. Options include execution time, docs examined, keys examined, and more. Defaults to execution time to focus on slowest queries.
189 type: select
190 required: true
191 default: execution_time
192 options: []
193 returns:
187 - description: Profiled query statistics from system.profile.
194 + description: Profiled query statistics from `system.profile`. Each row represents a single profiled operation with execution metrics and plan details.
195 columns:
196 - name: Timestamp
197 type: timestamp
198 unit: ""
192 - description: ""
199 + description: "When the operation was profiled. Useful for correlating slow queries with application events."
200 - name: Namespace
201 type: string
202 unit: ""
196 - description: ""
203 + description: "Database and collection name in format `database.collection`. Identifies which collection the operation targeted."
204 - name: Operation
205 type: string
206 unit: ""
200 - description: ""
207 + description: "Type of operation: query, insert, update, remove, command, getmore. Helps categorize workload patterns."
208 - name: Query
209 type: string
210 unit: ""
204 - description: ""
211 + description: "The command document as JSON showing the query filter, projection, and options. Truncated to 4096 characters."
212 - name: Execution Time
213 type: duration
214 unit: "seconds"
208 - description: ""
215 + description: "Total execution time of the operation. High values indicate slow queries that may need optimization."
216 - name: Docs Examined
217 type: integer
218 unit: ""
212 - description: ""
219 + description: "Number of documents scanned during execution. A high ratio of docs examined to docs returned suggests missing or inefficient indexes."
220 - name: Keys Examined
221 type: integer
222 unit: ""
216 - description: ""
223 + description: "Number of index keys scanned. Compare with docs examined to assess index efficiency."
224 - name: Docs Returned
225 type: integer
226 unit: ""
220 - description: ""
227 + description: "Number of documents returned to the client. Compare with docs examined to identify inefficient queries."
228 - name: Plan Summary
229 type: string
230 unit: ""
224 - description: ""
231 + description: "Execution plan summary (e.g., IXSCAN, COLLSCAN, SORT). COLLSCAN indicates a full collection scan that may need an index."
232 - name: Client
233 type: string
234 unit: ""
228 - description: ""
235 + description: "Client IP address or hostname that executed the operation. Useful for identifying query sources."
236 - name: User
237 type: string
238 unit: ""
232 - description: ""
239 + description: "Authenticated user who executed the operation. Empty for unauthenticated connections."
240 - name: Docs Deleted
241 type: integer
242 unit: ""
243 visibility: hidden
237 - description: ""
244 + description: "Number of documents deleted by the operation. Relevant for remove operations."
245 - name: Docs Inserted
246 type: integer
247 unit: ""
248 visibility: hidden
242 - description: ""
249 + description: "Number of documents inserted by the operation. Relevant for insert operations."
250 - name: Docs Modified
251 type: integer
252 unit: ""
253 visibility: hidden
247 - description: ""
254 + description: "Number of documents modified by the operation. Relevant for update operations."
255 - name: Response Length
256 type: integer
257 unit: ""
258 visibility: hidden
252 - description: ""
259 + description: "Size of the response in bytes. Large responses may indicate queries returning excessive data."
260 - name: Num Yield
261 type: integer
262 unit: ""
263 visibility: hidden
257 - description: ""
264 + description: "Number of times the operation yielded to allow other operations to proceed. High yields may indicate lock contention."
265 - name: App Name
266 type: string
267 unit: ""
261 - description: ""
268 + description: "Application name from the client connection string. Useful for identifying which application generated the query."
269 - name: Cursor Exhausted
270 type: string
271 unit: ""
272 visibility: hidden
266 - description: ""
273 + description: "Whether the cursor was fully exhausted (Yes/No)."
274 - name: Has Sort Stage
275 type: string
276 unit: ""
277 visibility: hidden
271 - description: ""
278 + description: "Whether the query required an in-memory sort stage (Yes/No). In-memory sorts are slower than index-based sorts."
279 - name: Uses Disk
280 type: string
281 unit: ""
282 visibility: hidden
276 - description: ""
283 + description: "Whether the operation used disk for sorting or aggregation (Yes/No). Indicates memory pressure."
284 - name: From Multi Planner
285 type: string
286 unit: ""
287 visibility: hidden
281 - description: ""
288 + description: "Whether multiple query plans were evaluated (Yes/No)."
289 - name: Replanned
290 type: string
291 unit: ""
292 visibility: hidden
286 - description: ""
293 + description: "Whether the query was replanned due to plan cache eviction (Yes/No)."
294 - name: Query Hash
295 type: string
296 unit: ""
297 visibility: hidden
291 - description: ""
298 + description: "Hash of the query shape for identifying similar queries. Available in MongoDB 4.2+."
299 - name: Plan Cache Key
300 type: string
301 unit: ""
302 visibility: hidden
296 - description: ""
303 + description: "Key used for plan cache lookup. Available in MongoDB 4.2+."
304 - name: Planning Time
305 type: duration
306 unit: "seconds"
307 visibility: hidden
301 - description: ""
308 + description: "Time spent planning the query execution. Available in MongoDB 6.2+."
309 - name: CPU Time
310 type: duration
311 unit: "seconds"
312 visibility: hidden
306 - description: ""
313 + description: "CPU time consumed by the operation. Available in MongoDB 6.3+ on Linux only."
314 - name: Query Framework
315 type: string
316 unit: ""
317 visibility: hidden
311 - description: ""
318 + description: "Query execution framework used (classic or SBE). Available in MongoDB 7.0+."
319 - name: Query Shape Hash
320 type: string
321 unit: ""
322 visibility: hidden
316 - description: ""
323 + description: "Hash representing the query shape for grouping similar queries. Available in MongoDB 8.0+."
324 performance: |
318 - Requires profiling and reads from system.profile; may add load on busy systems.
325 + Reads from `system.profile` collection across all user databases:<br/>• Profiling itself adds overhead to MongoDB operations (typically 1-5%)<br/>• Default limit of 500 rows balances usefulness with performance
326 security: |
320 - Query text may contain unmasked literals (potential PII).
327 + Query text may contain unmasked literal values including potentially sensitive data:<br/>• Document field values in query filters<br/>• Personal information in inserted/updated documents<br/>• Access should be restricted to authorized personnel only
328 prerequisites:
329 list:
330 - title: Enable MongoDB profiling
331 description: |
325 - Enable profiling on the target databases and set top_queries_function_enabled to true.
332 + Database profiling must be enabled on each database you want to monitor, and the function must be enabled in the collector configuration.
333 +
334 + 1. Enable profiling on a database (profile slow queries > 100ms):
335 +
336 + ```javascript
337 + use myDatabase
338 + db.setProfilingLevel(1, { slowms: 100 })
339 + ```
340 +
341 + 2. Or profile all operations (level 2, use with caution):
342 +
343 + ```javascript
344 + db.setProfilingLevel(2)
345 + ```
346 +
347 + 3. Verify profiling status:
348 +
349 + ```javascript
350 + db.getProfilingStatus()
351 + ```
352 +
353 + 4. Enable the function in Netdata collector config:
354 +
355 + ```yaml
356 + jobs:
357 + - name: local
358 + uri: mongodb://localhost:27017
359 + top_queries_function_enabled: true
360 + ```
361 +
362 + :::info
363 +
364 + - Profiling level 0 = off, 1 = slow operations only, 2 = all operations
365 + - The `slowms` threshold determines which queries are captured at level 1
366 + - `system.profile` is a capped collection; old entries are automatically removed
367 + - System databases (admin, local, config) are excluded from profiling queries
368 +
369 + :::
370 availability: |
327 - Available when profiling is enabled and the collector is initialized; returns 403 if disabled in config.
371 + Available when:<br/>• The collector has successfully connected to MongoDB<br/>• Profiling is enabled on at least one user database<br/>• Returns HTTP 503 if collector is still initializing or profiling is disabled on all databases<br/>• Returns HTTP 500 if the query fails<br/>• Returns HTTP 504 if the query times out
372 metrics:
373 folding:
374 title: Metrics
src/go/plugin/go.d/collector/mssql/metadata.yaml
+108 -71
@@ -233,317 +233,354 @@ modules:
233 - id: top-queries
234 name: Top Queries
235 description: |
236 - Top SQL queries from Query Store.
237 -
238 - Queries Query Store runtime statistics and returns the top entries sorted by the selected column.
236 + 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.
237 +
238 + 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.
239 +
240 + Use cases:
241 + - Identify slow or resource-intensive queries consuming excessive CPU time or memory
242 + - Analyze I/O patterns (logical reads, physical reads, writes) to detect bottlenecks
243 + - Monitor parallelism (DOP) and tempdb usage for capacity planning
244 +
245 + 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+).
246 parameters:
247 - id: __sort
248 name: Filter By
242 - description: Select the primary sort column (options are derived from sortable columns in the response).
249 + description: 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.
250 type: select
251 required: true
252 default: totalTime
253 options: []
254 returns:
248 - description: Query Store statistics for top queries.
255 + description: 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.
256 columns:
257 - name: Query Hash
258 type: string
259 unit: ""
260 visibility: hidden
254 - description: ""
261 + description: Unique hash identifier for the normalized query pattern. Queries with identical structure but different literal values share the same digest.
262 - name: Query
263 type: string
264 unit: ""
258 - description: ""
265 + description: 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.
266 - name: Database
267 type: string
268 unit: ""
262 - description: ""
269 + description: Database name where the query was executed. Essential for multi-database analysis to identify which database is experiencing query load.
270 - name: Calls
271 type: integer
272 unit: ""
266 - description: ""
273 + description: Total number of times this query pattern has been executed. High values indicate frequently run queries that may impact server performance significantly.
274 - name: Total Time
275 type: duration
276 unit: "milliseconds"
270 - description: ""
277 + description: 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.
278 - name: Avg Time
279 type: duration
280 unit: "milliseconds"
274 - description: ""
281 + description: 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.
282 - name: Last Time
283 type: duration
284 unit: "milliseconds"
285 visibility: hidden
279 - description: ""
286 + description: Execution time of the most recent execution for this query pattern. Useful for identifying recent performance changes or individual outlier executions.
287 - name: Min Time
288 type: duration
289 unit: "milliseconds"
290 visibility: hidden
284 - description: ""
291 + description: Minimum execution time observed. Helps identify variability in query performance and spot potential optimization opportunities for outliers.
292 - name: Max Time
293 type: duration
294 unit: "milliseconds"
295 visibility: hidden
289 - description: ""
296 + description: Maximum execution time observed. Large gaps between Min Time and Max Time may indicate performance instability due to parameter sniffing, data skew, or lock contention.
297 - name: StdDev Time
298 type: duration
299 unit: "milliseconds"
300 visibility: hidden
294 - description: ""
301 + description: Standard deviation of execution time. High values indicate inconsistent query performance, making capacity planning difficult and suggesting need for query optimization or consistent indexing.
302 - name: Avg CPU
303 type: duration
304 unit: "milliseconds"
298 - description: ""
305 + description: 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+.
306 - name: Last CPU
307 type: duration
308 unit: "milliseconds"
309 visibility: hidden
303 - description: ""
310 + description: CPU time of the most recent execution. Useful for identifying recent changes in query patterns and resource usage.
311 - name: Min CPU
312 type: duration
313 unit: "milliseconds"
314 visibility: hidden
308 - description: ""
315 + description: Minimum CPU time observed. Helps identify variability in CPU consumption and spot efficient vs. inefficient query executions.
316 - name: Max CPU
317 type: duration
318 unit: "milliseconds"
319 visibility: hidden
313 - description: ""
320 + description: Maximum CPU time observed. Spikes may indicate complex queries, large result sets, or parallelism issues.
321 - name: StdDev CPU
322 type: duration
323 unit: "milliseconds"
324 visibility: hidden
318 - description: ""
325 + description: Standard deviation of CPU time. High variability suggests inconsistent performance due to varying data volumes, plan cache hit rates, or changing execution contexts.
326 - name: Avg Logical Reads
327 type: float
328 unit: ""
322 - description: ""
329 + description: 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.
330 - name: Last Logical Reads
331 type: integer
332 unit: ""
333 visibility: hidden
327 - description: ""
334 + description: Logical reads from the most recent execution. Useful for identifying immediate query patterns and recent performance changes.
335 - name: Min Logical Reads
336 type: integer
337 unit: ""
338 visibility: hidden
332 - description: ""
339 + description: Minimum logical reads observed. Helps identify data access patterns and spot outliers.
340 - name: Max Logical Reads
341 type: integer
342 unit: ""
343 visibility: hidden
337 - description: ""
344 + description: Maximum logical reads observed. Very high values may indicate full table scans, missing indexes, or inefficient join operations requiring excessive data access.
345 - name: StdDev Logical Reads
346 type: float
347 unit: ""
348 visibility: hidden
342 - description: ""
349 + description: Standard deviation of logical reads. High variability suggests inconsistent access patterns, potentially indicating performance issues with certain queries or data volumes.
350 - name: Avg Logical Writes
351 type: float
352 unit: ""
346 - description: ""
353 + description: Average number of logical write operations per execution. High values indicate heavy write workloads that may benefit from batching or optimization.
354 - name: Last Logical Writes
355 type: integer
356 unit: ""
357 visibility: hidden
351 - description: ""
358 + description: Logical writes from the most recent execution. Helps track recent write activity and identify immediate performance impact.
359 - name: Min Logical Writes
360 type: integer
361 unit: ""
362 visibility: hidden
356 - description: ""
363 + description: Minimum logical writes observed. Helps identify read-heavy vs. write-heavy query patterns and data access characteristics.
364 - name: Max Logical Writes
365 type: integer
366 unit: ""
367 visibility: hidden
361 - description: ""
368 + description: Maximum logical writes observed. Spikes may indicate bulk insert/update operations, large transactions, or data migration activities.
369 - name: StdDev Logical Writes
370 type: float
371 unit: ""
372 visibility: hidden
366 - description: ""
373 + description: Standard deviation of logical writes. High values indicate write performance variability, potentially suggesting inconsistent transaction sizes or periodic bulk operations.
374 - name: Avg Physical Reads
375 type: float
376 unit: ""
370 - description: ""
377 + description: 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.
378 - name: Last Physical Reads
379 type: integer
380 unit: ""
381 visibility: hidden
375 - description: ""
382 + description: Physical reads from the most recent execution. Useful for identifying immediate I/O patterns and recent storage subsystem pressure.
383 - name: Min Physical Reads
384 type: integer
385 unit: ""
386 visibility: hidden
380 - description: ""
387 + description: Minimum physical reads observed. Helps baseline I/O patterns and identify read-intensive query scenarios.
388 - name: Max Physical Reads
389 type: integer
390 unit: ""
391 visibility: hidden
385 - description: ""
392 + description: 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.
393 - name: StdDev Physical Reads
394 type: float
395 unit: ""
396 visibility: hidden
390 - description: ""
397 + description: Standard deviation of physical reads. High variability suggests inconsistent disk access patterns, potentially indicating intermittent I/O performance issues or storage contention.
398 - name: Avg CLR Time
399 type: duration
400 unit: "milliseconds"
394 - visibility: hidden
395 - description: ""
401 + description: 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+.
402 - name: Last CLR Time
403 type: duration
404 unit: "milliseconds"
405 visibility: hidden
400 - description: ""
406 + description: CLR time of the most recent execution. Useful for identifying recent managed code performance changes and detecting inefficient code deployments.
407 - name: Min CLR Time
408 type: duration
409 unit: "milliseconds"
410 visibility: hidden
405 - description: ""
411 + description: Minimum CLR time observed. Helps identify efficient managed code executions and spot expensive CLR operations.
412 - name: Max CLR Time
413 type: duration
414 unit: "milliseconds"
415 visibility: hidden
410 - description: ""
416 + description: Maximum CLR time observed. Spikes may indicate complex managed code operations, large object allocations, or expensive .NET framework method calls.
417 - name: StdDev CLR Time
418 type: duration
419 unit: "milliseconds"
420 visibility: hidden
415 - description: ""
421 + description: Standard deviation of CLR time. High variability suggests inconsistent managed code execution patterns, potentially varying by execution parameters, data volumes, or different code paths being taken.
422 - name: Avg DOP
423 type: float
424 unit: ""
419 - description: ""
425 + description: 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.
426 - name: Last DOP
427 type: integer
428 unit: ""
429 visibility: hidden
424 - description: ""
430 + description: DOP of the most recent execution. Helps track recent parallelism patterns and identify changes in query execution behavior.
431 - name: Min DOP
432 type: integer
433 unit: ""
434 visibility: hidden
429 - description: ""
435 + description: Minimum DOP observed. Values of 0 may indicate serial execution; values above 1 suggest parallel query execution within individual queries.
436 - name: Max DOP
437 type: integer
438 unit: ""
439 visibility: hidden
434 - description: ""
440 + description: Maximum DOP observed. Very high values (>4) may indicate aggressive parallelism consuming excessive resources and potentially affecting concurrent workloads. Available in SQL Server 2016+.
441 - name: StdDev DOP
442 type: float
443 unit: ""
444 visibility: hidden
439 - description: ""
445 + description: Standard deviation of DOP. High variability suggests inconsistent parallelism patterns across executions, potentially indicating performance variability based on data characteristics or query complexity.
446 - name: Avg Memory (8KB pages)
447 type: float
448 unit: ""
443 - description: ""
449 + description: 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.
450 - name: Last Memory (8KB pages)
451 type: integer
452 unit: ""
453 visibility: hidden
448 - description: ""
454 + description: Memory grant from the most recent execution. Useful for identifying recent memory pressure and tracking immediate impact of resource-intensive queries.
455 - name: Min Memory (8KB pages)
456 type: integer
457 unit: ""
458 visibility: hidden
453 - description: ""
459 + description: Minimum memory grant observed. Helps identify memory-efficient queries and baseline memory requirements for common operations.
460 - name: Max Memory (8KB pages)
461 type: integer
462 unit: ""
463 visibility: hidden
458 - description: ""
464 + description: Maximum memory grant observed. Spikes may indicate queries with large sort operations, hash joins, temporary table creation, or excessive parameter lengths consuming working memory.
465 - name: StdDev Memory
466 type: float
467 unit: ""
468 visibility: hidden
463 - description: ""
469 + description: 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.
470 - name: Avg Rows
471 type: float
472 unit: ""
467 - description: ""
473 + description: 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.
474 - name: Last Rows
475 type: integer
476 unit: ""
477 visibility: hidden
472 - description: ""
478 + description: Row count from the most recent execution. Helps identify recent query patterns and track immediate data processing requirements.
479 - name: Min Rows
480 type: integer
481 unit: ""
482 visibility: hidden
477 - description: ""
483 + description: Minimum rows observed. Helps identify data access patterns and spot outliers in result set sizes.
484 - name: Max Rows
485 type: integer
486 unit: ""
487 visibility: hidden
482 - description: ""
488 + description: Maximum rows observed. Extremely high values may indicate full table scans without WHERE clauses, missing or inefficient filters, or data export operations.
489 - name: StdDev Rows
490 type: float
491 unit: ""
492 visibility: hidden
487 - description: ""
493 + description: 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.
494 - name: Avg Log Bytes
495 type: float
496 unit: ""
491 - description: ""
497 + description: 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.
498 - name: Last Log Bytes
499 type: integer
500 unit: ""
501 visibility: hidden
496 - description: ""
502 + description: Transaction log bytes from the most recent execution. Useful for tracking recent write activity.
503 - name: Min Log Bytes
504 type: integer
505 unit: ""
506 visibility: hidden
501 - description: ""
507 + description: Minimum transaction log bytes observed. Helps identify write-efficient queries and baseline requirements.
508 - name: Max Log Bytes
509 type: integer
510 unit: ""
511 visibility: hidden
506 - description: ""
512 + description: Maximum transaction log bytes observed. Spikes may indicate bulk operations, large transactions, or queries affecting many rows.
513 - name: StdDev Log Bytes
514 type: float
515 unit: ""
516 visibility: hidden
511 - description: ""
517 + description: Standard deviation of transaction log bytes. High variability suggests inconsistent write patterns, potentially varying by the number of rows affected or transaction sizes.
518 - name: Avg TempDB (8KB pages)
519 type: float
520 unit: ""
515 - description: ""
521 + description: 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.
522 - name: Last TempDB (8KB pages)
523 type: integer
524 unit: ""
525 visibility: hidden
520 - description: ""
526 + description: Tempdb space from the most recent execution. Useful for identifying recent tempdb pressure and tracking immediate disk I/O impact of resource-intensive queries.
527 - name: Min TempDB (8KB pages)
528 type: integer
529 unit: ""
530 visibility: hidden
525 - description: ""
531 + description: Minimum tempdb space observed. Helps identify tempdb-efficient queries and baseline temporary object requirements for common operations.
532 - name: Max TempDB (8KB pages)
533 type: integer
534 unit: ""
535 visibility: hidden
530 - description: ""
536 + description: 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.
537 - name: StdDev TempDB
538 type: float
539 unit: ""
540 visibility: hidden
535 - description: ""
541 + description: 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.
542 performance: |
537 - Uses Query Store and can be expensive on busy instances.
543 + Executes dynamic SQL to aggregate Query Store data across all enabled databases:<br/>• Execution time depends on Query Store workload and number of monitored databases<br/>• Default limit of 500 rows balances completeness with performance
544 security: |
539 - Query Store may contain unmasked literals (potential PII).
545 + Query text may contain unmasked literal values including potentially sensitive data:<br/>• Personal information in WHERE clauses or INSERT values<br/>• Business data and internal identifiers<br/>• Access should be restricted to authorized personnel only
546 prerequisites:
547 list:
542 - - title: Enable Query Store functions
548 + - title: Enable Query Store
549 description: |
544 - Enable Query Store and set query_store_function_enabled to true.
550 + Query Store must be enabled on each database you want to monitor.
551 +
552 + 1. Verify Query Store is enabled on your databases:
553 +
554 + ```sql
555 + SELECT name, is_query_store_on
556 + FROM sys.databases
557 + WHERE name NOT IN ('master', 'tempdb', 'model', 'msdb');
558 + ```
559 +
560 + 2. Enable Query Store on databases where it is disabled:
561 +
562 + ```sql
563 + ALTER DATABASE [YourDatabaseName] SET QUERY_STORE = ON;
564 + ```
565 +
566 + 3. Enable the function in Netdata collector config:
567 +
568 + ```yaml
569 + jobs:
570 + - name: local
571 + dsn: "sqlserver://user:pass@localhost:1433"
572 + query_store_function_enabled: true
573 + ```
574 +
575 + :::info
576 +
577 + - Query Store is available in SQL Server 2016+ and Azure SQL Database
578 + - Requires ALTER DATABASE permission to enable Query Store
579 + - System databases (master, tempdb, model, msdb) are excluded from queries
580 +
581 + :::
582 availability: |
546 - Available when Query Store is enabled and the collector is initialized; returns 403 if disabled in config.
583 + Available when:<br/>• The collector has successfully connected to SQL Server<br/>• Query Store is enabled on at least one user database<br/>• Returns HTTP 503 if collector is still initializing<br/>• Returns HTTP 500 if the query fails<br/>• Returns HTTP 504 if the query times out
584 metrics:
585 folding:
586 title: Metrics
src/go/plugin/go.d/collector/mysql/metadata.yaml
+117 -47
@@ -236,199 +236,269 @@ modules:
236 - id: top-queries
237 name: Top Queries
238 description: |
239 - Top SQL queries from performance_schema.
239 + 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.
240
241 - Reads performance_schema statement digest tables and returns the top entries sorted by the selected column.
241 + 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.
242 +
243 + Use cases:
244 + - Identify slow queries that consume the most execution time
245 + - Find frequently executed queries that may benefit from optimization
246 + - Detect queries with high lock time, errors, or table scans
247 +
248 + Query text is truncated at 4096 characters for display purposes.
249 parameters:
250 - id: __sort
251 name: Filter By
245 - description: Select the primary sort column (options are derived from sortable columns in the response).
252 + description: 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.
253 type: select
254 required: true
255 default: totalTime
256 options: []
257 returns:
251 - description: Aggregated statement statistics from performance_schema.
258 + description: Aggregated statement statistics from Performance Schema, grouped by query digest. Each row represents a unique query pattern with cumulative metrics across all executions.
259 columns:
260 - name: Digest
261 type: string
262 unit: ""
263 visibility: hidden
257 - description: ""
264 + description: "Unique hash identifier for the normalized query pattern. Queries with the same structure (different literal values) share the same digest."
265 - name: Query
266 type: string
267 unit: ""
261 - description: ""
268 + description: "Normalized SQL query text with literals replaced by placeholders (e.g., '?' for values). Truncated to 4096 characters."
269 - name: Schema
270 type: string
271 unit: ""
265 - description: ""
272 + description: "Database schema name where the query was executed. Empty string for queries without a schema context."
273 - name: Calls
274 type: integer
275 unit: ""
269 - description: ""
276 + description: "Total number of times this query pattern has been executed since server startup or since the digest table was last truncated."
277 - name: Total Time
278 type: duration
279 unit: "milliseconds"
273 - description: ""
280 + description: "Cumulative execution time across all executions. High values indicate queries that consume significant server resources."
281 - name: Min Time
282 type: duration
283 unit: "milliseconds"
284 visibility: hidden
278 - description: ""
285 + description: "Minimum execution time observed for a single execution. Helps identify variability in query performance."
286 - name: Avg Time
287 type: duration
288 unit: "milliseconds"
282 - description: ""
289 + description: "Average execution time (total time divided by calls). Use this to compare performance across different query patterns."
290 - name: Max Time
291 type: duration
292 unit: "milliseconds"
293 visibility: hidden
287 - description: ""
294 + description: "Maximum execution time observed for a single execution. Large gaps between min and max may indicate performance instability."
295 - name: Lock Time
296 type: duration
297 unit: "milliseconds"
291 - description: ""
298 + description: "Total time spent waiting for table locks across all executions. High lock time may indicate contention from concurrent transactions."
299 - name: Errors
300 type: integer
301 unit: ""
295 - description: ""
302 + description: "Total number of times this query pattern resulted in an error. Non-zero values require investigation into the underlying issue."
303 - name: Warnings
304 type: integer
305 unit: ""
299 - description: ""
306 + description: "Total number of times this query pattern generated warnings. Warnings may indicate data type conversions, NULL handling issues, or other non-critical problems."
307 - name: Rows Affected
308 type: integer
309 unit: ""
303 - description: ""
310 + description: "Total number of rows modified by INSERT, UPDATE, DELETE, or REPLACE statements. Useful for tracking write workloads."
311 - name: Rows Sent
312 type: integer
313 unit: ""
307 - description: ""
314 + description: "Total number of rows returned to the client by SELECT statements. High values may indicate result sets that are too large."
315 - name: Rows Examined
316 type: integer
317 unit: ""
311 - description: ""
318 + description: "Total number of rows read during query execution. A high ratio of rows examined to rows sent suggests missing or inefficient indexes."
319 - name: Temp Disk Tables
320 type: integer
321 unit: ""
315 - description: ""
322 + description: "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."
323 - name: Temp Tables
324 type: integer
325 unit: ""
319 - description: ""
326 + description: "Total number of temporary tables created (both in-memory and on-disk). High values suggest frequent sorting, grouping, or DISTINCT operations."
327 - name: Full Joins
328 type: integer
329 unit: ""
323 - description: ""
330 + description: "Total number of joins that performed a full table scan without using an index. These are typically very expensive operations that should be optimized."
331 - name: Full Range Joins
332 type: integer
333 unit: ""
334 visibility: hidden
328 - description: ""
335 + description: "Total number of joins that used a range scan on the first table. Less efficient than indexed joins but better than full scans."
336 - name: Select Range
337 type: integer
338 unit: ""
339 visibility: hidden
333 - description: ""
340 + description: "Total number of joins that used a range on the first table for row selection."
341 - name: Select Range Check
342 type: integer
343 unit: ""
344 visibility: hidden
338 - description: ""
345 + description: "Total number of joins that checked each row after scanning for key ranges. Very inefficient operation."
346 - name: Select Scan
347 type: integer
348 unit: ""
342 - description: ""
349 + description: "Total number of joins that performed a full scan of the first table. Indicates missing indexes or suboptimal join order."
350 - name: Sort Merge Passes
351 type: integer
352 unit: ""
353 visibility: hidden
347 - description: ""
354 + description: "Total number of merge passes performed during sort operations. More passes indicate larger datasets that exceed sort buffer size."
355 - name: Sort Range
356 type: integer
357 unit: ""
358 visibility: hidden
352 - description: ""
359 + description: "Total number of sorts that used a range scan."
360 - name: Sort Rows
361 type: integer
362 unit: ""
356 - description: ""
363 + description: "Total number of rows sorted across all executions. High values indicate frequent sorting operations on large datasets."
364 - name: Sort Scan
365 type: integer
366 unit: ""
367 visibility: hidden
361 - description: ""
368 + description: "Total number of sorts that required a full table scan."
369 - name: No Index Used
370 type: integer
371 unit: ""
365 - description: ""
372 + description: "Total number of executions where no index was used for table access. These queries are prime candidates for index optimization."
373 - name: No Good Index Used
374 type: integer
375 unit: ""
376 visibility: hidden
370 - description: ""
377 + description: "Total number of executions where a non-optimal index was used. Indicates that while an index exists, a better one might improve performance."
378 - name: First Seen
379 type: string
380 unit: ""
381 visibility: hidden
375 - description: ""
382 + description: "Timestamp when this query pattern was first observed. Helps identify new queries that may have been introduced by application changes."
383 - name: Last Seen
384 type: string
385 unit: ""
386 visibility: hidden
380 - description: ""
387 + description: "Timestamp when this query pattern was last executed. Can help identify stale queries that are no longer in use."
388 - name: P95 Time
389 type: duration
390 unit: "milliseconds"
384 - description: ""
391 + description: "95th percentile execution time. 95% of executions completed within this time. Available in MySQL 8.0+. Useful for understanding typical performance."
392 - name: P99 Time
393 type: duration
394 unit: "milliseconds"
388 - description: ""
395 + description: "99th percentile execution time. 99% of executions completed within this time. Available in MySQL 8.0+. Helps identify outlier slow executions."
396 - name: P99.9 Time
397 type: duration
398 unit: "milliseconds"
399 visibility: hidden
393 - description: ""
400 + description: "99.9th percentile execution time. Available in MySQL 8.0+. Identifies extreme outliers in query performance."
401 - name: Sample Query
402 type: string
403 unit: ""
404 visibility: hidden
398 - description: ""
405 + description: "Example of an actual query execution with literal values preserved. Available in MySQL 8.0+. Helpful for understanding the exact queries being executed."
406 - name: Sample Seen
407 type: string
408 unit: ""
409 visibility: hidden
403 - description: ""
410 + description: "Timestamp when the sample query was captured. Available in MySQL 8.0+."
411 - name: Sample Time
412 type: duration
413 unit: "milliseconds"
414 visibility: hidden
408 - description: ""
415 + description: "Execution time of the captured sample query. Available in MySQL 8.0+."
416 - name: CPU Time
417 type: duration
418 unit: "milliseconds"
412 - description: ""
419 + description: "Total CPU time consumed across all executions. Available in MySQL 8.0.28+. Helps identify CPU-intensive queries."
420 - name: Max Controlled Memory
421 type: integer
422 unit: ""
416 - description: ""
423 + description: "Maximum memory controlled by the query executor for this query pattern. Available in MySQL 8.0.31+. Helps identify memory-intensive operations."
424 - name: Max Total Memory
425 type: integer
426 unit: ""
420 - description: ""
427 + description: "Maximum total memory used by this query pattern including both controlled and uncontrolled allocations. Available in MySQL 8.0.31+."
428 performance: |
422 - Requires performance_schema and can be expensive on busy servers.
429 + Queries the `events_statements_summary_by_digest` table:<br/>• On busy servers with high query throughput, the digest table can grow large<br/>• Default limit of 500 rows balances usefulness with performance
430 security: |
424 - Query text may contain unmasked literals (potential PII).
431 + Query text may contain unmasked literal values including potentially sensitive data:<br/>• Personal information in WHERE clauses or INSERT values<br/>• Business data and internal identifiers<br/>• Access should be restricted to authorized personnel only
432 prerequisites:
433 list:
427 - - title: Enable performance_schema digest tables
434 + - title: Enable performance_schema statement digest collection
435 + description: |
436 + Performance Schema must be enabled and statement instrumentation must be configured to collect digest statistics.
437 +
438 + 1. Check if Performance Schema is enabled:
439 + ```sql
440 + SELECT @@performance_schema;
441 + ```
442 +
443 + 2. Check statement instrumentation configuration:
444 + ```sql
445 + SELECT * FROM performance_schema.setup_consumers
446 + WHERE NAME LIKE '%statement%';
447 + ```
448 +
449 + 3. The following consumers should be enabled:
450 + - `events_statements_current`
451 + - `events_statements_summary_by_digest`
452 +
453 + 4. Enable statement consumers if needed:
454 + ```sql
455 + UPDATE performance_schema.setup_consumers
456 + SET ENABLED = 'YES'
457 + WHERE NAME LIKE 'events_statements%';
458 + ```
459 +
460 + :::info
461 +
462 + - Changes to `setup_consumers` take effect immediately without requiring a server restart.
463 + - 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.
464 +
465 + :::
466 +
467 + 5. Verify digest table contains data:
468 + ```sql
469 + SELECT COUNT(*) FROM performance_schema.events_statements_summary_by_digest;
470 + ```
471 +
472 + Note: Statement digest data is accumulated since server startup or since the table was last truncated. To reset statistics:
473 + ```sql
474 + TRUNCATE TABLE performance_schema.events_statements_summary_by_digest;
475 + ```
476 +
477 + 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.
478 + - title: Grant SELECT permission on Performance Schema tables
479 description: |
429 - Enable performance_schema and grant access to events_statements_summary_by_digest.
480 + The netdata user must have SELECT permission on Performance Schema tables. The standard collector permissions
481 + (USAGE, REPLICATION CLIENT, PROCESS) do not automatically include Performance Schema access.
482 +
483 + 1. Grant the required permission:
484 + ```sql
485 + GRANT SELECT ON performance_schema.* TO 'netdata'@'localhost';
486 + FLUSH PRIVILEGES;
487 + ```
488 +
489 + :::info
490 +
491 + 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.
492 +
493 + :::
494 +
495 + 2. Verify access:
496 + ```sql
497 + -- As the netdata user:
498 + SELECT COUNT(*) FROM performance_schema.events_statements_summary_by_digest;
499 + ```
500 availability: |
431 - Available when performance_schema tables are accessible and the collector is initialized.
501 + Available when:<br/>• The collector has successfully connected to MySQL<br/>• Performance Schema is enabled with statement digest collection<br/>• Returns HTTP 503 if collector is still initializing<br/>• Returns HTTP 500 if the query fails<br/>• Returns HTTP 504 if the query times out
502 metrics:
503 folding:
504 title: Metrics
src/go/plugin/go.d/collector/oracledb/metadata.yaml
+106 -43
@@ -157,175 +157,238 @@ modules:
157 - id: top-queries
158 name: Top Queries
159 description: |
160 - Top SQL statements from V$SQLSTATS. WARNING: Query text may contain unmasked literals (potential PII).
161 -
162 - Queries V$SQLSTATS and returns the top entries sorted by the selected column.
160 + 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.
161 +
162 + 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.
163 +
164 + Use cases:
165 + - Identify slow queries consuming the most total execution time
166 + - Find queries with high buffer gets or disk reads for I/O optimization
167 + - Analyze CPU-intensive queries for resource tuning
168 +
169 + Query text is truncated at 4096 characters for display purposes.
170 parameters:
171 - id: __sort
172 name: Filter By
166 - description: Select the primary sort column (options are derived from sortable columns in the response).
173 + description: Select the primary sort column. Options include total time, CPU time, executions, buffer gets, disk reads, and more. Defaults to total time to focus on most resource-intensive queries.
174 type: select
175 required: true
176 default: totalTime
177 options: []
178 returns:
172 - description: Aggregated SQL statistics from V$SQLSTATS.
179 + description: Aggregated SQL statistics from `V$SQLSTATS`. Each row represents a unique SQL statement with cumulative metrics across all executions.
180 columns:
181 - name: SQL ID
182 type: string
183 unit: ""
184 visibility: hidden
178 - description: ""
185 + description: "Unique identifier for the SQL statement in the shared pool. Can be used to find execution plans in `V$SQL_PLAN`."
186 - name: Query
187 type: string
188 unit: ""
182 - description: ""
189 + description: "SQL statement text. Truncated to 4096 characters for display purposes."
190 - name: Schema
191 type: string
192 unit: ""
186 - description: ""
193 + description: "Schema under which the SQL was parsed. Useful for identifying which application or user generated the query."
194 - name: Executions
195 type: integer
196 unit: ""
190 - description: ""
197 + description: "Total number of times this SQL statement has been executed. High values indicate frequently run queries."
198 - name: Total Time
199 type: duration
200 unit: "milliseconds"
194 - description: ""
201 + description: "Cumulative elapsed time across all executions. High values indicate queries consuming significant database resources."
202 - name: Avg Time
203 type: duration
204 unit: "milliseconds"
198 - description: ""
205 + description: "Average elapsed time per execution. Use this to compare typical performance across different SQL statements."
206 - name: CPU Time
207 type: duration
208 unit: "milliseconds"
202 - description: ""
209 + description: "Cumulative CPU time consumed across all executions. Compare with total time to identify I/O-bound vs CPU-bound queries."
210 - name: Buffer Gets
211 type: integer
212 unit: ""
206 - description: ""
213 + description: "Total number of logical reads from the buffer cache. High values relative to rows processed may indicate inefficient queries."
214 - name: Disk Reads
215 type: integer
216 unit: ""
210 - description: ""
217 + description: "Total number of physical reads from disk. High values indicate queries that cannot be satisfied from the buffer cache."
218 - name: Rows Processed
219 type: integer
220 unit: ""
214 - description: ""
221 + description: "Total number of rows processed across all executions. Compare with buffer gets to assess query efficiency."
222 - name: Parse Calls
223 type: integer
224 unit: ""
225 visibility: hidden
219 - description: ""
226 + description: "Number of times the SQL was parsed (hard + soft parses). High values may indicate lack of bind variables."
227 - name: Module
228 type: string
229 unit: ""
230 visibility: hidden
224 - description: ""
231 + description: "Application module name set via `DBMS_APPLICATION_INFO`. Useful for identifying which application component generated the query."
232 - name: Action
233 type: string
234 unit: ""
235 visibility: hidden
229 - description: ""
236 + description: "Application action name set via `DBMS_APPLICATION_INFO`. Provides finer-grained identification within a module."
237 - name: Last Active
238 type: string
239 unit: ""
240 visibility: hidden
234 - description: ""
241 + description: "Timestamp when this SQL statement was last executed. Helps identify recently active vs historical queries."
242 performance: |
236 - Queries system views and may be expensive on busy databases.
243 + Queries `V$SQLSTATS` which is a lightweight view optimized for statistics retrieval:<br/>• On busy databases with many SQL statements, the query may take longer<br/>• Default limit of 500 rows balances usefulness with performance
244 security: |
238 - Query text may contain unmasked literals (potential PII).
245 + Query text may contain unmasked literal values including potentially sensitive data:<br/>• Personal information in WHERE clauses or INSERT values<br/>• Business data and internal identifiers<br/>• Access should be restricted to authorized personnel only
246 prerequisites:
247 list:
248 - title: Grant access to V$SQLSTATS
249 description: |
243 - Use a SQL user with access to V$SQLSTATS and a working SQL connection.
250 + The monitoring user must have SELECT privilege on `V$SQLSTATS` and related views.
251 +
252 + 1. Grant the required privileges:
253 +
254 + ```sql
255 + -- Note: Use V_$ (with underscore) for GRANT - this is the base fixed view
256 + -- Queries use the V$ public synonym
257 + GRANT SELECT ON V_$SQLSTATS TO netdata;
258 + -- Or grant the broader role:
259 + GRANT SELECT_CATALOG_ROLE TO netdata;
260 + ```
261 +
262 + 2. Verify access:
263 +
264 + ```sql
265 + SELECT COUNT(*) FROM V$SQLSTATS WHERE ROWNUM <= 1;
266 + ```
267 +
268 + :::info
269 +
270 + - `V$SQLSTATS` is available in Oracle 10g and later
271 + - The view aggregates statistics across all child cursors for each SQL statement
272 + - Some columns like `MODULE` and `ACTION` require applications to set them via `DBMS_APPLICATION_INFO`
273 +
274 + :::
275 availability: |
245 - Available when the collector can query Oracle system views; returns errors if SQL is unavailable.
276 + Available when:<br/>• The collector has successfully connected to Oracle DB<br/>• The user has SELECT privilege on `V$SQLSTATS`<br/>• Returns HTTP 503 if the connection cannot be established<br/>• Returns HTTP 500 if the query fails<br/>• Returns HTTP 504 if the query times out
277 - id: running-queries
278 name: Running Queries
279 description: |
249 - Currently running SQL statements from V$SESSION. WARNING: Query text may contain unmasked literals (potential PII).
280 + Retrieves currently executing SQL statements from Oracle [V$SESSION](https://docs.oracle.com/en/database/oracle/oracle-database/19/refrn/V-SESSION.html) view.
281
251 - Queries V$SESSION and returns running statements sorted by the selected column.
282 + 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.
283 +
284 + Use cases:
285 + - Identify long-running queries that may be blocking other sessions
286 + - Monitor active workload and session distribution
287 + - Debug stuck or slow queries in real-time
288 +
289 + Query text is truncated at 4096 characters for display purposes.
290 parameters:
291 - id: __sort
292 name: Filter By
255 - description: Select the primary sort column (options are derived from sortable columns in the response).
293 + description: Select the primary sort column. Defaults to elapsed time to show longest-running queries first.
294 type: select
295 required: true
296 default: lastCallMs
297 options: []
298 returns:
261 - description: Snapshot of currently running SQL sessions.
299 + description: Real-time snapshot of currently executing SQL statements. Each row represents an active user session with its current SQL.
300 columns:
301 - name: Session
302 type: string
303 unit: ""
266 - description: ""
304 + description: "Session identifier in format `SID,SERIAL#`. Can be used with `ALTER SYSTEM KILL SESSION` if needed."
305 - name: User
306 type: string
307 unit: ""
270 - description: ""
308 + description: "Oracle username of the session. Useful for identifying workload by user."
309 - name: Status
310 type: string
311 unit: ""
274 - description: ""
312 + description: "Session status (ACTIVE for currently executing). Only active sessions with SQL are shown."
313 - name: Type
314 type: string
315 unit: ""
316 visibility: hidden
279 - description: ""
317 + description: "Session type (USER or BACKGROUND). This function filters to USER sessions only."
318 - name: SQL ID
319 type: string
320 unit: ""
321 visibility: hidden
284 - description: ""
322 + description: "Identifier of the currently executing SQL. Can be used to find the statement in `V$SQL`."
323 - name: Query
324 type: string
325 unit: ""
288 - description: ""
326 + description: "SQL statement text currently being executed. Truncated to 4096 characters."
327 - name: Elapsed
328 type: duration
329 unit: "milliseconds"
292 - description: ""
330 + description: "Time elapsed since the session's last call started. High values indicate long-running operations that may need investigation."
331 - name: SQL Exec Start
332 type: string
333 unit: ""
334 visibility: hidden
297 - description: ""
335 + description: "Timestamp when the current SQL execution started."
336 - name: Module
337 type: string
338 unit: ""
339 visibility: hidden
302 - description: ""
340 + description: "Application module name set via `DBMS_APPLICATION_INFO`. Identifies which application is running the query."
341 - name: Action
342 type: string
343 unit: ""
344 visibility: hidden
307 - description: ""
345 + description: "Application action name set via `DBMS_APPLICATION_INFO`."
346 - name: Program
347 type: string
348 unit: ""
349 visibility: hidden
312 - description: ""
350 + description: "Client program name that established the session (e.g., sqlplus, JDBC Thin Client)."
351 - name: Machine
352 type: string
353 unit: ""
354 visibility: hidden
317 - description: ""
355 + description: "Client machine name or IP address. Useful for identifying query sources."
356 performance: |
319 - Queries system views and may be expensive on busy databases.
357 + Queries `V$SESSION` joined with `V$SQL` for currently active sessions:<br/>• Lightweight operation as it only returns currently active user sessions<br/>• Default limit of 500 rows (rarely reached for running queries)
358 security: |
321 - Query text may contain unmasked literals (potential PII).
359 + Query text may contain unmasked literal values including potentially sensitive data:<br/>• Personal information in WHERE clauses or INSERT values<br/>• Business data and credentials in query parameters<br/>• Access should be restricted to authorized personnel only
360 prerequisites:
361 list:
362 - title: Grant access to V$SESSION
363 description: |
326 - Use a SQL user with access to V$SESSION and a working SQL connection.
364 + The monitoring user must have SELECT privilege on `V$SESSION` and `V$SQL`.
365 +
366 + 1. Grant the required privileges:
367 +
368 + ```sql
369 + -- Note: Use V_$ (with underscore) for GRANT - this is the base fixed view
370 + -- Queries use the V$ public synonym
371 + GRANT SELECT ON V_$SESSION TO netdata;
372 + GRANT SELECT ON V_$SQL TO netdata;
373 + -- Or grant the broader role:
374 + GRANT SELECT_CATALOG_ROLE TO netdata;
375 + ```
376 +
377 + 2. Verify access:
378 +
379 + ```sql
380 + SELECT COUNT(*) FROM V$SESSION WHERE ROWNUM <= 1;
381 + ```
382 +
383 + :::info
384 +
385 + - Only USER sessions with ACTIVE status and a current SQL ID are returned
386 + - The elapsed time is based on `LAST_CALL_ET` which resets when a new SQL starts
387 + - BACKGROUND sessions (Oracle internal processes) are filtered out
388 +
389 + :::
390 availability: |
328 - Available when the collector can query Oracle system views; returns errors if SQL is unavailable.
391 + Available when:<br/>• The collector has successfully connected to Oracle DB<br/>• The user has SELECT privilege on `V$SESSION` and `V$SQL`<br/>• Returns HTTP 503 if the connection cannot be established<br/>• Returns HTTP 500 if the query fails<br/>• Returns HTTP 504 if the query times out
392 metrics:
393 folding:
394 title: Metrics
src/go/plugin/go.d/collector/postgres/metadata.yaml
+84 -50
@@ -229,228 +229,262 @@ modules:
229 - id: top-queries
230 name: Top Queries
231 description: |
232 - Top SQL queries from pg_stat_statements.
232 + Retrieves aggregated SQL query performance metrics from PostgreSQL [pg_stat_statements](https://www.postgresql.org/docs/current/pgstatstatements.html) extension.
233
234 - Reads pg_stat_statements and returns the top entries sorted by the selected column.
234 + 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.
235 +
236 + Use cases:
237 + - Identify slow queries consuming the most total execution time
238 + - Find queries with high shared block reads for I/O optimization
239 + - Analyze temp block usage to detect queries needing memory tuning
240 +
241 + Query text is truncated at 4096 characters for display purposes.
242 parameters:
243 - id: __sort
244 name: Filter By
238 - description: Select the primary sort column (options are derived from sortable columns in the response).
245 + description: Select the primary sort column. Options include total time, mean time, calls, rows, shared blocks hit/read, and temp blocks written. Defaults to total time to focus on most resource-intensive queries.
246 type: select
247 required: true
248 default: totalTime
249 options: []
250 returns:
244 - description: Aggregated query statistics from pg_stat_statements.
251 + description: Aggregated query statistics from `pg_stat_statements`. Each row represents a unique query pattern with cumulative metrics across all executions.
252 columns:
253 - name: Query ID
254 type: string
255 unit: ""
256 visibility: hidden
250 - description: ""
257 + description: "Internal hash identifier for the normalized query. Can be used to track queries across statistics resets."
258 - name: Query
259 type: string
260 unit: ""
254 - description: ""
261 + description: "Normalized SQL query text with literals replaced by parameter placeholders. Truncated to 4096 characters."
262 - name: Database
263 type: string
264 unit: ""
258 - description: ""
265 + description: "Database name where the query was executed."
266 - name: User
267 type: string
268 unit: ""
262 - description: ""
269 + description: "PostgreSQL user who executed the query."
270 - name: Calls
271 type: integer
272 unit: ""
266 - description: ""
273 + description: "Total number of times this query pattern has been executed. High values indicate frequently run queries."
274 - name: Total Time
275 type: duration
276 unit: "milliseconds"
270 - description: ""
277 + description: "Cumulative execution time across all executions. High values indicate queries consuming significant database resources."
278 - name: Mean Time
279 type: duration
280 unit: "milliseconds"
274 - description: ""
281 + description: "Average execution time per call. Use this to compare typical performance across different query patterns."
282 - name: Min Time
283 type: duration
284 unit: "milliseconds"
285 visibility: hidden
279 - description: ""
286 + description: "Minimum execution time observed for a single execution."
287 - name: Max Time
288 type: duration
289 unit: "milliseconds"
290 visibility: hidden
284 - description: ""
291 + description: "Maximum execution time observed for a single execution. Large gaps between min and max may indicate performance variability."
292 - name: Stddev Time
293 type: duration
294 unit: "milliseconds"
295 visibility: hidden
289 - description: ""
296 + description: "Standard deviation of execution time. High values indicate inconsistent query performance."
297 - name: Plans
298 type: integer
299 unit: ""
300 visibility: hidden
294 - description: ""
301 + description: "Number of times the query was planned. Available in PostgreSQL 13+."
302 - name: Total Plan Time
303 type: duration
304 unit: "milliseconds"
305 visibility: hidden
299 - description: ""
306 + description: "Cumulative time spent planning the query. Available in PostgreSQL 13+."
307 - name: Mean Plan Time
308 type: duration
309 unit: "milliseconds"
310 visibility: hidden
304 - description: ""
311 + description: "Average time spent planning per execution. Available in PostgreSQL 13+."
312 - name: Min Plan Time
313 type: duration
314 unit: "milliseconds"
315 visibility: hidden
309 - description: ""
316 + description: "Minimum planning time observed. Available in PostgreSQL 13+."
317 - name: Max Plan Time
318 type: duration
319 unit: "milliseconds"
320 visibility: hidden
314 - description: ""
321 + description: "Maximum planning time observed. Available in PostgreSQL 13+."
322 - name: Stddev Plan Time
323 type: duration
324 unit: "milliseconds"
325 visibility: hidden
319 - description: ""
326 + description: "Standard deviation of planning time. Available in PostgreSQL 13+."
327 - name: Rows
328 type: integer
329 unit: ""
323 - description: ""
330 + description: "Total number of rows retrieved or affected across all executions."
331 - name: Shared Blocks Hit
332 type: integer
333 unit: ""
327 - description: ""
334 + description: "Total shared buffer cache hits. High values indicate good cache utilization."
335 - name: Shared Blocks Read
336 type: integer
337 unit: ""
331 - description: ""
338 + description: "Total shared blocks read from disk. High values indicate queries that bypass the cache and may benefit from more `shared_buffers`."
339 - name: Shared Blocks Dirtied
340 type: integer
341 unit: ""
342 visibility: hidden
336 - description: ""
343 + description: "Total shared blocks dirtied by the query."
344 - name: Shared Blocks Written
345 type: integer
346 unit: ""
347 visibility: hidden
341 - description: ""
348 + description: "Total shared blocks written by the query."
349 - name: Local Blocks Hit
350 type: integer
351 unit: ""
352 visibility: hidden
346 - description: ""
353 + description: "Total local buffer cache hits (temporary tables)."
354 - name: Local Blocks Read
355 type: integer
356 unit: ""
357 visibility: hidden
351 - description: ""
358 + description: "Total local blocks read from disk."
359 - name: Local Blocks Dirtied
360 type: integer
361 unit: ""
362 visibility: hidden
356 - description: ""
363 + description: "Total local blocks dirtied."
364 - name: Local Blocks Written
365 type: integer
366 unit: ""
367 visibility: hidden
361 - description: ""
368 + description: "Total local blocks written."
369 - name: Temp Blocks Read
370 type: integer
371 unit: ""
365 - description: ""
372 + description: "Total temp blocks read. Non-zero values indicate queries spilling to disk due to insufficient `work_mem`."
373 - name: Temp Blocks Written
374 type: integer
375 unit: ""
369 - description: ""
376 + description: "Total temp blocks written. High values suggest increasing `work_mem` may improve performance."
377 - name: Block Read Time
378 type: duration
379 unit: "milliseconds"
373 - description: ""
380 + description: "Time spent reading blocks from disk. Requires `track_io_timing` to be enabled."
381 - name: Block Write Time
382 type: duration
383 unit: "milliseconds"
377 - description: ""
384 + description: "Time spent writing blocks to disk. Requires `track_io_timing` to be enabled."
385 - name: WAL Records
386 type: integer
387 unit: ""
388 visibility: hidden
382 - description: ""
389 + description: "Total number of WAL records generated. Available in PostgreSQL 13+."
390 - name: WAL Full Page Images
391 type: integer
392 unit: ""
393 visibility: hidden
387 - description: ""
394 + description: "Total number of WAL full page images generated. Available in PostgreSQL 13+."
395 - name: WAL Bytes
396 type: integer
397 unit: ""
398 visibility: hidden
392 - description: ""
399 + description: "Total bytes of WAL generated. Available in PostgreSQL 13+."
400 - name: JIT Functions
401 type: integer
402 unit: ""
403 visibility: hidden
397 - description: ""
404 + description: "Total number of functions JIT-compiled. Available in PostgreSQL 15+."
405 - name: JIT Generation Time
406 type: duration
407 unit: "milliseconds"
408 visibility: hidden
402 - description: ""
409 + description: "Time spent generating JIT code. Available in PostgreSQL 15+."
410 - name: JIT Inlining Count
411 type: integer
412 unit: ""
413 visibility: hidden
407 - description: ""
414 + description: "Number of times JIT inlining was performed. Available in PostgreSQL 15+."
415 - name: JIT Inlining Time
416 type: duration
417 unit: "milliseconds"
418 visibility: hidden
412 - description: ""
419 + description: "Time spent on JIT inlining. Available in PostgreSQL 15+."
420 - name: JIT Optimization Count
421 type: integer
422 unit: ""
423 visibility: hidden
417 - description: ""
424 + description: "Number of times JIT optimization was performed. Available in PostgreSQL 15+."
425 - name: JIT Optimization Time
426 type: duration
427 unit: "milliseconds"
428 visibility: hidden
422 - description: ""
429 + description: "Time spent on JIT optimization. Available in PostgreSQL 15+."
430 - name: JIT Emission Count
431 type: integer
432 unit: ""
433 visibility: hidden
427 - description: ""
434 + description: "Number of times JIT code was emitted. Available in PostgreSQL 15+."
435 - name: JIT Emission Time
436 type: duration
437 unit: "milliseconds"
438 visibility: hidden
432 - description: ""
439 + description: "Time spent emitting JIT code. Available in PostgreSQL 15+."
440 - name: Temp Block Read Time
441 type: duration
442 unit: "milliseconds"
443 visibility: hidden
437 - description: ""
444 + description: "Time spent reading temp blocks. Available in PostgreSQL 15+. Requires `track_io_timing`."
445 - name: Temp Block Write Time
446 type: duration
447 unit: "milliseconds"
448 visibility: hidden
442 - description: ""
449 + description: "Time spent writing temp blocks. Available in PostgreSQL 15+. Requires `track_io_timing`."
450 performance: |
444 - Requires pg_stat_statements and can be expensive on busy servers.
451 + Queries `pg_stat_statements` which maintains statistics in shared memory:<br/>• On busy servers with many unique queries, the extension may consume significant memory<br/>• Default limit of 500 rows balances usefulness with performance
452 security: |
446 - Query text may contain unmasked literals (potential PII).
453 + Query text may contain unmasked literal values including potentially sensitive data:<br/>• Personal information in WHERE clauses or INSERT values<br/>• Business data and internal identifiers<br/>• Access should be restricted to authorized personnel only
454 prerequisites:
455 list:
456 - title: Enable pg_stat_statements
457 description: |
451 - Install and enable the pg_stat_statements extension.
458 + The `pg_stat_statements` extension must be installed and configured.
459 +
460 + 1. Add to `postgresql.conf`:
461 +
462 + ```ini
463 + shared_preload_libraries = 'pg_stat_statements'
464 + ```
465 +
466 + 2. Restart PostgreSQL, then create the extension:
467 +
468 + ```sql
469 + CREATE EXTENSION pg_stat_statements;
470 + ```
471 +
472 + 3. Verify the extension is working:
473 +
474 + ```sql
475 + SELECT COUNT(*) FROM pg_stat_statements;
476 + ```
477 +
478 + :::info
479 +
480 + - `pg_stat_statements` requires a server restart to load the shared library
481 + - Statistics can be reset with `SELECT pg_stat_statements_reset()`
482 + - The `pg_stat_statements.max` parameter controls maximum tracked statements (default 5000)
483 + - Enable `track_io_timing` for block read/write timing metrics (may add slight overhead)
484 +
485 + :::
486 availability: |
453 - Available when pg_stat_statements is available and the collector is initialized.
487 + Available when:<br/>• The `pg_stat_statements` extension is installed in the database<br/>• The collector has successfully connected to PostgreSQL<br/>• Returns HTTP 503 if extension is not installed (with instructions to install)<br/>• Returns HTTP 500 if the query fails<br/>• Returns HTTP 504 if the query times out
488 metrics:
489 folding:
490 title: Metrics
src/go/plugin/go.d/collector/proxysql/metadata.yaml
+30 -28
@@ -130,102 +130,104 @@ modules:
130 - id: top-queries
131 name: Top Queries
132 description: |
133 - Top SQL queries from ProxySQL query digest stats.
133 + Retrieves aggregated query statistics from ProxySQL's [stats_mysql_query_digest](https://proxysql.com/documentation/stats-statistics/#stats_mysql_query_digest) table.
134
135 - Queries stats_mysql_query_digest and returns the top entries sorted by the selected column.
135 + 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.
136 +
137 + Use cases:
138 + - Identify slow queries consuming excessive total execution time
139 + - Find high-frequency queries that may benefit from caching
140 + - Monitor query error rates across backends
141 +
142 + Query text is truncated at 4096 characters for display purposes.
143 parameters:
144 - id: __sort
145 name: Filter By
139 - description: Select the primary sort column (options are derived from sortable columns in the response).
146 + description: Select the primary sort column. Options include total execution time, number of calls, rows affected, rows sent, errors, and warnings. Defaults to total time to focus on most resource-intensive queries.
147 type: select
148 required: true
149 default: totalTime
150 options: []
151 returns:
145 - description: Query digest statistics from ProxySQL.
152 + description: 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.
153 columns:
154 - name: Digest
155 type: string
156 unit: ""
157 visibility: hidden
151 - description: ""
158 + description: Unique hash identifier for normalized query pattern. Queries with identical structure but different literal values share the same digest.
159 - name: Query
160 type: string
161 unit: ""
155 - description: ""
162 + description: 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.
163 - name: Schema
164 type: string
165 unit: ""
159 - description: ""
166 + description: Database name where the query was executed. Essential for multi-database analysis to identify which database or backend is experiencing query load.
167 - name: User
168 type: string
169 unit: ""
170 visibility: hidden
164 - description: ""
171 + description: MySQL username used to execute the query. Useful for identifying application users or connection pool attribution.
172 - name: Hostgroup
173 type: integer
174 unit: ""
175 visibility: hidden
169 - description: ""
176 + description: Backend hostgroup identifier from ProxySQL configuration. Allows grouping queries by backend server for multi-backend analysis.
177 - name: Calls
178 type: integer
179 unit: ""
173 - description: ""
180 + description: Total number of times this query pattern has been executed. High values indicate frequently run queries that may impact server performance significantly.
181 - name: Total Time
182 type: duration
183 unit: "milliseconds"
177 - description: ""
184 + description: 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.
185 - name: Avg Time
186 type: duration
187 unit: "milliseconds"
181 - description: ""
188 + description: Average execution time per query run. Compare with Total Time to determine if individual executions or high frequency drives resource usage.
189 - name: Min Time
190 type: duration
191 unit: "milliseconds"
192 visibility: hidden
186 - description: ""
193 + description: Minimum execution time observed. Helps identify variability in query performance and spot potential optimization opportunities for outliers.
194 - name: Max Time
195 type: duration
196 unit: "milliseconds"
197 visibility: hidden
191 - description: ""
198 + description: Maximum execution time observed. Large gaps between Min Time and Max Time may indicate performance instability due to parameter sniffing, data skew, or lock contention.
199 - name: Rows Affected
200 type: integer
201 unit: ""
195 - description: ""
202 + description: Total number of rows modified by INSERT, UPDATE, DELETE, or REPLACE statements. Useful for tracking write workloads and data modification patterns.
203 - name: Rows Sent
204 type: integer
205 unit: ""
199 - description: ""
206 + description: 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.
207 - name: Errors
208 type: integer
209 unit: ""
203 - description: ""
210 + description: 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.
211 - name: Warnings
212 type: integer
213 unit: ""
207 - description: ""
214 + description: 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.
215 - name: First Seen
216 type: string
217 unit: ""
218 visibility: hidden
212 - description: ""
219 + description: Timestamp when this query pattern was first observed. Helps identify new queries that may have been introduced by application changes or code deployments.
220 - name: Last Seen
221 type: string
222 unit: ""
223 visibility: hidden
217 - description: ""
224 + description: Timestamp when this query pattern was last executed. Can help identify stale queries that are no longer in use or to track recent query activity.
225 performance: |
219 - Uses ProxySQL stats tables and can be expensive on busy systems.
226 + Queries ProxySQL admin interface for digest statistics:<br/>• Reads from in-memory `stats_mysql_query_digest` table<br/>• Default limit of 500 rows balances completeness with performance<br/>• Data is aggregated in-memory by ProxySQL from active connections
227 security: |
221 - Query text may contain unmasked literals (potential PII).
222 - prerequisites:
223 - list:
224 - - title: Grant access to stats_mysql_query_digest
225 - description: |
226 - Ensure the ProxySQL user can read stats_mysql_query_digest.
228 + Query text may contain unmasked literal values including potentially sensitive data:<br/>• Personal information in WHERE clauses or INSERT values<br/>• Business data embedded in queries<br/>• Access should be restricted to authorized personnel only
229 availability: |
228 - Available when the collector can query ProxySQL stats; returns errors if the SQL connection is unavailable.
230 + Available when:<br/>• The collector has successfully connected to ProxySQL admin interface<br/>• Returns HTTP 503 if the connection cannot be established<br/>• Returns HTTP 500 if the query fails<br/>• Returns HTTP 504 if the query times out
231 metrics:
232 folding:
233 title: Metrics
src/go/plugin/go.d/collector/redis/metadata.yaml
+22 -15
@@ -191,57 +191,64 @@ modules:
191 - id: top-queries
192 name: Top Queries
193 description: |
194 - Slow commands from Redis SLOWLOG. WARNING: Command arguments may contain unmasked literals (potential PII).
195 -
196 - Reads Redis SLOWLOG and returns the top entries sorted by the selected column.
194 + Retrieves slow command entries from Redis [SLOWLOG](https://redis.io/docs/latest/commands/slowlog/).
195 +
196 + 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.
197 +
198 + Use cases:
199 + - Identify slow commands that may need optimization
200 + - Analyze command patterns to detect performance hotspots
201 + - Investigate client sources of slow commands
202 +
203 + Command text is truncated at 4096 characters for display purposes.
204 parameters:
205 - id: __sort
206 name: Filter By
200 - description: Select the primary sort column (options are derived from sortable columns in the response).
207 + description: Select the primary sort column. Options include duration, timestamp, ID, and command name. Defaults to duration to focus on slowest commands.
208 type: select
209 required: true
210 default: duration
211 options: []
212 returns:
206 - description: Slowlog entries with command timing and metadata.
213 + description: 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.
214 columns:
215 - name: ID
216 type: integer
217 unit: ""
218 visibility: hidden
212 - description: ""
219 + description: Unique identifier for the slowlog entry. Allows tracking individual command executions.
220 - name: Timestamp
221 type: timestamp
222 unit: ""
216 - description: ""
223 + description: Date and time when the slow command was executed. Useful for correlating slow commands with application events or system changes.
224 - name: Command
225 type: string
226 unit: ""
220 - description: ""
227 + description: Full command text including all arguments. May contain sensitive data (keys, values) depending on application implementation. Truncated to 4096 characters.
228 - name: Command Name
229 type: string
230 unit: ""
224 - description: ""
231 + description: The Redis command name (e.g., SET, GET, HGETALL, ZADD). Useful for grouping and analyzing slow commands by type.
232 - name: Duration
233 type: duration
234 unit: "milliseconds"
228 - description: ""
235 + description: Execution time that exceeded the slowlog threshold. Higher values indicate slower commands that may need optimization or investigation.
236 - name: Client Address
237 type: string
238 unit: ""
239 visibility: hidden
233 - description: ""
240 + description: IP address of the client that executed the slow command. Useful for identifying problematic clients or network segments.
241 - name: Client Name
242 type: string
243 unit: ""
244 visibility: hidden
238 - description: ""
245 + description: Client identifier or name reported by Redis. Useful for identifying specific applications or services generating slow commands.
246 performance: |
240 - Uses SLOWLOG GET and may return many entries; use top_queries_limit to control size.
247 + Executes `SLOWLOG GET` command to retrieve entries from Redis memory:<br/>• Minimal overhead as SLOWLOG is stored in memory<br/>• Default limit of 500 entries balances completeness with performance<br/>• Large slowlogs with many entries may take slightly longer to transfer
248 security: |
242 - Command arguments may contain unmasked literals (potential PII).
249 + Command arguments may contain unmasked literal values including potentially sensitive data:<br/>• Redis keys and values in command arguments<br/>• Application-specific identifiers or session tokens<br/>• Access should be restricted to authorized personnel only
250 availability: |
244 - Available when the collector is initialized; returns 503 if the collector is still connecting.
251 + Available when:<br/>• The collector has successfully connected to Redis<br/>• SLOWLOG is enabled (`slowlog-log-slower-than` > 0)<br/>• Returns HTTP 503 if collector is still initializing<br/>• Returns HTTP 500 if the command fails<br/>• Returns HTTP 504 if the command times out
252 metrics:
253 folding:
254 title: Metrics
src/go/plugin/go.d/collector/rethinkdb/metadata.yaml
+41 -18
@@ -140,67 +140,90 @@ modules:
140 - id: running-queries
141 name: Running Queries
142 description: |
143 - Currently running queries from rethinkdb.jobs. WARNING: Query text may contain unmasked literals (potential PII).
144 -
145 - Queries rethinkdb.jobs and returns running queries sorted by the selected column.
143 + Retrieves currently executing queries from the RethinkDB [rethinkdb.jobs](https://rethinkdb.com/docs/system-jobs/) system table.
144 +
145 + 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.
146 +
147 + Use cases:
148 + - Identify long-running queries that may be blocking resources
149 + - Monitor active query load across the cluster
150 + - Investigate client connections generating heavy workloads
151 +
152 + Query text is truncated at 4096 characters for display purposes.
153 parameters:
154 - id: __sort
155 name: Filter By
149 - description: Select the primary sort column (options are derived from sortable columns in the response).
156 + description: Select the primary sort column. Defaults to duration to focus on longest-running queries.
157 type: select
158 required: true
159 default: durationMs
160 options: []
161 returns:
155 - description: Snapshot of running queries from rethinkdb.jobs.
162 + description: Currently running queries from the `rethinkdb.jobs` system table. Each row represents a single active query with its execution context.
163 columns:
164 - name: Job ID
165 type: string
166 unit: ""
167 visibility: hidden
161 - description: ""
168 + description: Unique identifier for the job entry. Can be used to track or kill specific queries.
169 - name: Query
170 type: string
171 unit: ""
165 - description: ""
172 + description: The ReQL query text being executed. Truncated to 4096 characters. May contain literal values from application code.
173 - name: Duration
174 type: duration
175 unit: "milliseconds"
169 - description: ""
176 + description: Time elapsed since the query started executing. High values indicate long-running queries that may need investigation.
177 - name: Type
178 type: string
179 unit: ""
173 - description: ""
180 + description: Job type (e.g., query, index_construction, disk_compaction). Useful for distinguishing user queries from background tasks.
181 - name: User
182 type: string
183 unit: ""
177 - description: ""
184 + description: RethinkDB user account that initiated the query. Useful for identifying workload by user or application.
185 - name: Client Address
186 type: string
187 unit: ""
188 visibility: hidden
182 - description: ""
189 + description: IP address of the client connection that submitted the query.
190 - name: Client Port
191 type: integer
192 unit: ""
193 visibility: hidden
187 - description: ""
194 + description: Port number of the client connection.
195 - name: Servers
196 type: string
197 unit: ""
198 visibility: hidden
192 - description: ""
199 + description: Comma-separated list of servers involved in executing this query.
200 performance: |
194 - Uses system tables and may be expensive on busy clusters.
201 + Queries the `rethinkdb.jobs` system table:<br/>• Minimal overhead as it reads from an in-memory system table<br/>• Default limit of 500 rows balances completeness with performance<br/>• Returns only currently active queries (no historical data)
202 security: |
196 - Query text may contain unmasked literals (potential PII).
203 + Query text may contain unmasked literal values including potentially sensitive data:<br/>• Document field values in filter conditions<br/>• User-provided data in insert/update operations<br/>• Access should be restricted to authorized personnel only
204 prerequisites:
205 list:
199 - - title: Grant admin access to rethinkdb.jobs
206 + - title: Grant admin access to `rethinkdb.jobs`
207 description: |
201 - Use an admin user with access to rethinkdb.jobs and ensure the connection is working.
208 + The user must have admin privileges to query the `rethinkdb.jobs` system table.
209 +
210 + 1. Connect with an admin user account that has access to system tables
211 +
212 + 2. Verify access to `rethinkdb.jobs`:
213 +
214 + ```javascript
215 + r.db('rethinkdb').table('jobs').run(conn)
216 + ```
217 +
218 + :::info
219 +
220 + - The `rethinkdb.jobs` table is only accessible to admin users
221 + - Non-admin users will receive a permission error when attempting to query this table
222 + - The collector's regular metrics do not require admin access
223 +
224 + :::
225 availability: |
203 - Available when the collector is initialized; returns 503 if the collector is still connecting.
226 + Available when:<br/>• The collector has successfully connected to RethinkDB<br/>• The user has admin access to `rethinkdb.jobs` table<br/>• Returns HTTP 503 if collector is still initializing<br/>• Returns HTTP 500 if the query fails<br/>• Returns HTTP 504 if the query times out
227 metrics:
228 folding:
229 title: Metrics
src/go/plugin/go.d/collector/snmp/metadata.yaml
+33 -26
@@ -490,13 +490,20 @@ modules:
490 - id: interfaces
491 name: Network Interfaces
492 description: |
493 - Network interface traffic and status metrics.
493 + Provides detailed network interface traffic and status metrics from SNMP-enabled devices.
494
495 - Uses the latest cached SNMP interface data, filters by the selected type group, and sorts by the default column.
495 + 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.
496 +
497 + Use cases:
498 + - Identify top bandwidth-consuming interfaces on routers, switches, and access points
499 + - Monitor interface operational and administrative status for network health
500 + - Investigate packet errors, discards, and unusual traffic patterns
501 +
502 + 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.
503 parameters:
504 - id: if_type_group
505 name: Type Group
499 - description: Filter by interface type group.
506 + description: Filter interfaces by their type classification group. Custom mapping categorizes IANA interface types into practical groups for easier filtering.
507 type: select
508 required: true
509 default: ethernet
@@ -511,98 +518,98 @@ modules:
518 - id: other
519 name: Other
520 returns:
514 - description: Table of interface traffic and status from cached SNMP data.
521 + description: 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.
522 columns:
523 - name: Interface
524 type: string
525 unit: ""
519 - description: ""
526 + description: Network interface name or identifier (e.g., eth0, GigabitEthernet1/0/1, Vlan100)
527 - name: Type
528 type: string
529 unit: ""
523 - description: ""
530 + description: IANA-assigned interface type from IF-MIB (e.g., ethernetCsmacd, ieee80211, softwareLoopback)
531 - name: Type Group
532 type: string
533 unit: ""
527 - description: ""
534 + description: "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)"
535 - name: Admin Status
536 type: string
537 unit: ""
531 - description: ""
538 + description: "Administrative state configured on the interface: up (enabled for use), down (administratively disabled), or testing (currently in test mode). Different from operational status."
539 - name: Oper Status
540 type: string
541 unit: ""
535 - description: ""
542 + description: "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)"
543 - name: Traffic In
544 type: float
545 unit: "Mbits"
539 - description: ""
546 + description: Inbound network traffic rate in megabits per second. High values indicate heavy inbound data flow that may require capacity planning.
547 - name: Traffic Out
548 type: float
549 unit: "Mbits"
543 - description: ""
550 + description: Outbound network traffic rate in megabits per second. High values indicate heavy outbound data flow. Compare with Traffic In to identify asymmetric usage patterns.
551 - name: Unicast In
552 type: float
553 unit: "Kpps"
554 visibility: hidden
548 - description: ""
555 + description: Rate of unicast packets (destined for a single recipient) received per second in thousands. Normal traffic pattern for point-to-point communications.
556 - name: Unicast Out
557 type: float
558 unit: "Kpps"
559 visibility: hidden
553 - description: ""
560 + description: Rate of unicast packets (addressed to a single destination) transmitted per second in thousands.
561 - name: Broadcast In
562 type: float
563 unit: "Kpps"
564 visibility: hidden
558 - description: ""
565 + description: Rate of broadcast packets (sent to all nodes on network) received per second in thousands. High values may indicate network storms, ARP flooding, or misconfigured devices.
566 - name: Broadcast Out
567 type: float
568 unit: "Kpps"
569 visibility: hidden
563 - description: ""
570 + description: Rate of broadcast packets transmitted per second in thousands. Consistently high broadcast rates can degrade network performance.
571 - name: Packets In
572 type: float
573 unit: "Kpps"
567 - description: ""
574 + description: Total inbound packet rate (sum of unicast, broadcast, and multicast) per second in thousands. Useful for overall interface load assessment.
575 - name: Packets Out
576 type: float
577 unit: "Kpps"
571 - description: ""
578 + description: Total outbound packet rate (sum of unicast, broadcast, and multicast) per second in thousands.
579 - name: Errors In
580 type: float
581 unit: "packets/s"
582 visibility: hidden
576 - description: ""
583 + description: Rate of inbound packets with errors that prevented delivery. Non-zero values indicate physical layer issues (cable problems, signal integrity) or buffer overruns.
584 - name: Errors Out
585 type: float
586 unit: "packets/s"
587 visibility: hidden
581 - description: ""
588 + description: Rate of outbound packets with transmission errors. Non-zero values may indicate interface hardware issues, cabling problems, or duplex mismatches.
589 - name: Discards In
590 type: float
591 unit: "packets/s"
585 - description: ""
592 + description: 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.
593 - name: Discards Out
594 type: float
595 unit: "packets/s"
589 - description: ""
596 + description: Rate of outbound packets deliberately discarded. Can indicate output queue overflows, ACL drops, or security policy rejections.
597 - name: Multicast In
598 type: float
599 unit: "Kpps"
600 visibility: hidden
594 - description: ""
601 + description: Rate of multicast packets (destined for a group) received per second in thousands. Common in video streaming, multicast applications, and routing protocols.
602 - name: Multicast Out
603 type: float
604 unit: "Kpps"
605 visibility: hidden
599 - description: ""
606 + description: Rate of multicast packets transmitted per second in thousands.
607 performance: |
601 - Uses cached data only and does not trigger additional SNMP requests. Large devices may return many rows.
608 + Uses cached SNMP data only, no additional SNMP requests are triggered:<br/>• Responses are instantaneous from memory cache<br/>• Large devices with many interfaces may return many rows
609 security: |
603 - Exposes interface names and counters only.
610 + Exposes interface names, operational status, and traffic counters only:<br/>• No packet payloads or authentication credentials are exposed<br/>• No device configuration details are exposed
611 availability: |
605 - Available after the collector has completed at least one data collection; returns 503 until cache is ready.
612 + Available when:<br/>• The collector has completed at least one data collection cycle<br/>• Interface data is cached from the last successful SNMP collection<br/>• Returns HTTP 503 if cache is not ready yet
613 metrics:
614 folding:
615 title: Metrics
src/go/plugin/go.d/collector/yugabytedb/metadata.yaml
+88 -42
@@ -248,157 +248,203 @@ modules:
248 - id: top-queries
249 name: Top Queries
250 description: |
251 - Top SQL queries from pg_stat_statements. WARNING: Query text may contain unmasked literals (potential PII).
252 -
253 - Reads pg_stat_statements and returns the top entries sorted by the selected column.
251 + 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.
252 +
253 + 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.
254 +
255 + Use cases:
256 + - Identify slow queries consuming excessive total execution time
257 + - Find high-frequency queries that may benefit from optimization
258 + - Analyze query patterns by database and user
259 +
260 + Query text is truncated at 4096 characters for display purposes.
261 parameters:
262 - id: __sort
263 name: Filter By
257 - description: Select the primary sort column (options are derived from sortable columns in the response).
264 + description: Select the primary sort column. Options include total time, mean time, max time, calls, and rows. Defaults to total time to focus on most resource-intensive queries.
265 type: select
266 required: true
267 default: totalTime
268 options: []
269 returns:
263 - description: Aggregated query statistics from pg_stat_statements.
270 + description: Aggregated query statistics from `pg_stat_statements`. Each row represents a unique query pattern with cumulative metrics across all executions.
271 columns:
272 - name: Query ID
273 type: string
274 unit: ""
275 visibility: hidden
269 - description: ""
276 + description: Internal hash identifier for the normalized query pattern.
277 - name: Query
278 type: string
279 unit: ""
273 - description: ""
280 + description: Normalized SQL query text with literals replaced by parameter placeholders. Truncated to 4096 characters.
281 - name: Database
282 type: string
283 unit: ""
277 - description: ""
284 + description: Database name where the query was executed. Useful for multi-database workload analysis.
285 - name: User
286 type: string
287 unit: ""
281 - description: ""
288 + description: YSQL user who executed the query. Useful for identifying workload by user or application.
289 - name: Calls
290 type: integer
291 unit: ""
285 - description: ""
292 + description: Total number of times this query pattern has been executed. High values indicate frequently run queries.
293 - name: Total Time
294 type: duration
295 unit: "milliseconds"
289 - description: ""
296 + description: Cumulative execution time across all calls. Primary metric for identifying resource-intensive queries.
297 - name: Mean Time
298 type: duration
299 unit: "milliseconds"
293 - description: ""
300 + description: Average execution time per call. Compare with total time to distinguish slow queries from frequently called ones.
301 - name: Min Time
302 type: duration
303 unit: "milliseconds"
304 visibility: hidden
298 - description: ""
305 + description: Minimum execution time observed for this query pattern.
306 - name: Max Time
307 type: duration
308 unit: "milliseconds"
309 visibility: hidden
303 - description: ""
310 + description: Maximum execution time observed. Large gaps between min and max may indicate parameter sensitivity or lock contention.
311 - name: Rows
312 type: integer
313 unit: ""
307 - description: ""
314 + description: Total number of rows retrieved or affected by the query across all executions.
315 - name: Stddev Time
316 type: duration
317 unit: "milliseconds"
318 visibility: hidden
312 - description: ""
319 + description: Standard deviation of execution times. High values indicate inconsistent query performance.
320 performance: |
314 - Executes SQL queries and may be expensive on busy clusters; use top_queries_limit and sql_timeout.
321 + Queries the `pg_stat_statements` view via YSQL connection:<br/>• Default limit of 500 rows balances completeness with performance<br/>• Use `sql_timeout` to prevent long-running queries
322 security: |
316 - Query text may contain unmasked literals (potential PII).
323 + Query text may contain unmasked literal values including potentially sensitive data:<br/>• Personal information in WHERE clauses or INSERT values<br/>• Business data embedded in queries<br/>• Access should be restricted to authorized personnel only
324 prerequisites:
325 list:
319 - - title: Enable pg_stat_statements for YSQL
326 + - title: Enable pg_stat_statements extension
327 description: |
321 - Install and enable pg_stat_statements and configure a YSQL DSN.
328 + The `pg_stat_statements` extension must be installed in the target YSQL database.
329 +
330 + 1. Install the extension:
331 +
332 + ```sql
333 + CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
334 + ```
335 +
336 + 2. Verify access:
337 +
338 + ```sql
339 + SELECT * FROM pg_stat_statements LIMIT 1;
340 + ```
341 +
342 + :::info
343 +
344 + - The extension tracks statistics for all SQL statements executed
345 + - Statistics can be reset with `SELECT pg_stat_statements_reset()`
346 + - YugabyteDB uses PostgreSQL-compatible extensions
347 +
348 + :::
349 availability: |
323 - Available when YSQL is accessible; returns errors if the SQL connection is unavailable.
350 + Available when:<br/>• The collector has successfully connected to YSQL<br/>• The `pg_stat_statements` extension is installed<br/>• Returns HTTP 503 if the SQL connection cannot be established or extension is not installed<br/>• Returns HTTP 500 if the query fails<br/>• Returns HTTP 504 if the query times out
351 - id: running-queries
352 name: Running Queries
353 description: |
327 - Currently running SQL statements from pg_stat_activity. WARNING: Query text may contain unmasked literals (potential PII).
328 -
329 - Reads pg_stat_activity and returns running statements sorted by the selected column.
354 + 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.
355 +
356 + 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.
357 +
358 + Use cases:
359 + - Identify long-running queries that may need investigation
360 + - Monitor active connections and their current state
361 + - Investigate blocked or waiting queries
362 +
363 + Query text is truncated at 4096 characters for display purposes.
364 parameters:
365 - id: __sort
366 name: Filter By
333 - description: Select the primary sort column (options are derived from sortable columns in the response).
367 + description: Select the primary sort column. Defaults to elapsed time to focus on longest-running queries.
368 type: select
369 required: true
370 default: elapsedMs
371 options: []
372 returns:
339 - description: Snapshot of currently running SQL statements.
373 + description: Currently running SQL statements from `pg_stat_activity`. Each row represents an active backend process with its current query and execution context.
374 columns:
375 - name: PID
376 type: string
377 unit: ""
378 visibility: hidden
345 - description: ""
379 + description: Backend process ID. Can be used with pg_terminate_backend() to cancel a query.
380 - name: Query
381 type: string
382 unit: ""
349 - description: ""
383 + description: The SQL statement currently being executed. Truncated to 4096 characters.
384 - name: Database
385 type: string
386 unit: ""
353 - description: ""
387 + description: Database name the backend is connected to.
388 - name: User
389 type: string
390 unit: ""
357 - description: ""
391 + description: YSQL user name of the backend process.
392 - name: State
393 type: string
394 unit: ""
361 - description: ""
395 + description: Current state of the backend (active, idle in transaction, fastpath function call, etc.).
396 - name: Wait Event Type
397 type: string
398 unit: ""
399 visibility: hidden
366 - description: ""
400 + description: Type of event the backend is waiting for (Lock, LWLock, IO, etc.). Null if not waiting.
401 - name: Wait Event
402 type: string
403 unit: ""
404 visibility: hidden
371 - description: ""
405 + description: Specific wait event name. Useful for diagnosing lock contention or I/O bottlenecks.
406 - name: Application
407 type: string
408 unit: ""
409 visibility: hidden
376 - description: ""
410 + description: Application name set by the client connection. Useful for identifying which application is running the query.
411 - name: Client Address
412 type: string
413 unit: ""
414 visibility: hidden
381 - description: ""
415 + description: IP address of the client connection.
416 - name: Query Start
417 type: string
418 unit: ""
419 visibility: hidden
386 - description: ""
420 + description: Timestamp when the current query began execution.
421 - name: Elapsed
422 type: duration
423 unit: "milliseconds"
390 - description: ""
424 + description: Time elapsed since the query started. High values indicate long-running queries that may need investigation.
425 performance: |
392 - Executes SQL queries and may be expensive on busy clusters; use top_queries_limit and sql_timeout.
426 + Queries the `pg_stat_activity` view via YSQL connection:<br/>• Returns only non-idle connections to reduce result size<br/>• Default limit of 500 rows balances completeness with performance<br/>• Use `sql_timeout` to prevent long-running queries
427 security: |
394 - Query text may contain unmasked literals (potential PII).
428 + Query text may contain unmasked literal values including potentially sensitive data:<br/>• Personal information in WHERE clauses or INSERT values<br/>• Business data embedded in queries<br/>• Access should be restricted to authorized personnel only
429 prerequisites:
430 list:
397 - - title: Grant access to pg_stat_activity
431 + - title: Grant access to all queries (optional)
432 description: |
399 - Configure a YSQL DSN and grant access to pg_stat_activity.
433 + 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:
434 +
435 + ```sql
436 + GRANT pg_read_all_stats TO your_user;
437 + ```
438 +
439 + :::info
440 +
441 + - The `yugabyte` superuser can see all queries by default
442 + - Without elevated privileges, only the user's own queries are visible
443 + - Idle connections are filtered out from results
444 +
445 + :::
446 availability: |
401 - Available when YSQL is accessible; returns errors if the SQL connection is unavailable.
447 + Available when:<br/>• The collector has successfully connected to YSQL<br/>• Returns HTTP 503 if the SQL connection cannot be established<br/>• Returns HTTP 500 if the query fails<br/>• Returns HTTP 504 if the query times out
448 metrics:
449 folding:
450 title: Metrics