24874d5fa · cryptotaxi247/netdata-1

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

234

235 ### Top Queries

236

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

237 +Retrieves aggregated SQL query performance metrics from PostgreSQL using either [pg_stat_monitor](https://docs.percona.com/pg-stat-monitor/) (preferred) or [pg_stat_statements](https://www.postgresql.org/docs/current/pgstatstatements.html).

238

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

239 +The collector automatically detects which extension is available:

240 +- **pg_stat_monitor** (Percona): Enhanced statistics with additional columns like application name, client IP, CPU time, error info, and query classification

241 +- **pg_stat_statements** (standard): Core execution statistics available in all PostgreSQL installations

242 +

243 +Statistics include execution counts, timing metrics, I/O operations, and resource consumption. Columns are dynamically detected based on your PostgreSQL version and available extension.

244

245 Use cases:

246 - Identify slow queries consuming the most total execution time

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

248 - Analyze temp block usage to detect queries needing memory tuning

249 +- With pg_stat_monitor: Track queries by application, identify error patterns

250

251 Query text is truncated at 4096 characters for display purposes.

252

@@ -250,15 +255,17 @@ Query text is truncated at 4096 characters for display purposes.

255 |:-------|:------------|

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

257 | Require Cloud | yes |

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

258 +| Performance | Queries `pg_stat_statements` or `pg_stat_monitor` which maintain statistics in shared memory: • On busy servers with many unique queries, the extension may consume significant memory • Default limit of 500 rows balances usefulness with performance • pg_stat_monitor uses time-based buckets which may have different memory characteristics |

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

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

260 +| Availability | Available when: • Either `pg_stat_statements` or `pg_stat_monitor` extension is installed • The collector has successfully connected to PostgreSQL • Returns HTTP 503 if no query statistics extension is installed • Returns HTTP 500 if the query fails • Returns HTTP 504 if the query times out |

261

262 #### Prerequisites

263

259 -##### Enable pg_stat_statements

264 +##### Enable pg_stat_statements or pg_stat_monitor

265 +

266 +Either `pg_stat_statements` (standard) or `pg_stat_monitor` (Percona) must be installed. The collector auto-detects which is available, preferring pg_stat_monitor when both are present.

267

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

268 +**Option 1: pg_stat_statements (standard PostgreSQL)**

269

270 1. Add to `postgresql.conf`:

271

@@ -272,18 +279,29 @@ The `pg_stat_statements` extension must be installed and configured.

279 CREATE EXTENSION pg_stat_statements;

280 ```

281

275 -3. Verify the extension is working:

282 +**Option 2: pg_stat_monitor (Percona - recommended)**

283 +

284 +Provides additional columns: application name, client IP, CPU time, error tracking, and query classification.

285 +

286 +1. Install pg_stat_monitor (available in Percona distribution or as separate package)

287 +

288 +2. Add to `postgresql.conf`:

289 +

290 + ```ini

291 + shared_preload_libraries = 'pg_stat_monitor'

292 + ```

293 +

294 +3. Restart PostgreSQL, then create the extension:

295

296 ```sql

278 - SELECT COUNT(*) FROM pg_stat_statements;

297 + CREATE EXTENSION pg_stat_monitor;

298 ```

299

300 :::info

301

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

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

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

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

302 +- Both extensions require a server restart to load the shared library

303 +- Statistics can be reset with `SELECT pg_stat_statements_reset()` or `SELECT pg_stat_monitor_reset()`

304 +- Enable `track_io_timing` for block read/write timing metrics

305

306 :::

307

@@ -297,7 +315,7 @@ The `pg_stat_statements` extension must be installed and configured.

315

316 #### Returns

317

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

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

319

321 |:-------|:-----|:-----|:-----------|:------------|

@@ -343,6 +361,91 @@ Aggregated query statistics from `pg_stat_statements`. Each row represents a uni

376 +

377 +### Running Queries

378 +

379 +Retrieves currently executing queries from PostgreSQL [pg_stat_activity](https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW) system view.

380 +

381 +This function queries `pg_stat_activity` which shows real-time information about each server process including the SQL query being executed, wait events, and session state. Unlike Top Queries which shows aggregated historical statistics, Running Queries shows live snapshots of active queries.

382 +

383 +Use cases:

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

385 +- Debug stuck transactions or hanging connections

386 +- Monitor active workload during performance issues

387 +- Investigate wait events and lock contention in real-time

388 +

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

390 +

391 +

392 +| Aspect | Description |

393 +|:-------|:------------|

394 +| Name | `Postgres:running-queries` |

395 +| Require Cloud | yes |

396 +| Performance | Queries `pg_stat_activity` which is a live system view: • Very lightweight query, no impact on database performance • Returns only active queries by default (state = 'active') • Limited to 500 rows |

397 +| Security | Query text contains actual SQL being executed, which may include: • Personal information in WHERE clauses or INSERT values • Business data and internal identifiers • Access should be restricted to authorized personnel only |

398 +| Availability | Available when: • The collector has successfully connected to PostgreSQL • Returns HTTP 503 if collector is still initializing • Returns HTTP 500 if the query fails • Returns HTTP 504 if the query times out |

399 +

400 +#### Prerequisites

401 +

402 +##### Database user permissions

403 +

404 +The monitoring user needs `pg_monitor` role to view all sessions:

405 +

406 +```sql

407 +GRANT pg_monitor TO netdata;

408 +```

409 +

410 +Without this role, the user can only see their own sessions.

411 +

412 +

413 +

414 +#### Parameters

415 +

417 +|:---------|:-----|:------------|:--------:|:--------|:--------|

419 +

420 +#### Returns

421 +

422 +Live query data from `pg_stat_activity`. Each row represents a currently active backend process.

423 +

425 +|:-------|:-----|:-----|:-----------|:------------|

433 +| PID | integer | | | Process ID of this backend. Use with pg_terminate_backend() to kill a query. |

449

450

451

Regenerate integrations docs (#21663)