diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3be76a3..dd50902 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.4.7] - 2026-02-03
+
+### Added
+
+- Database query duration distribution panel in Grafana Runtime dashboard
+- `wordpress_db_query_duration_seconds` metric now listed in Help tab
+- Documentation for enabling `SAVEQUERIES` constant for query timing
+
+### Changed
+
+- Updated README with instructions for enabling database query timing
+- Grafana Runtime dashboard now includes bucket distribution chart for DB queries
+
## [0.4.6] - 2026-02-03
### Added
diff --git a/CLAUDE.md b/CLAUDE.md
index 7990fee..0777ed2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -292,6 +292,18 @@ add_action( 'wp_prometheus_collect_metrics', function( $collector ) {
## Session History
+### 2026-02-03 - Database Query Timing Documentation (v0.4.7)
+
+- Added database query duration distribution panel to Grafana Runtime dashboard
+- Added `wordpress_db_query_duration_seconds` metric to Help tab metrics reference
+- Added documentation in README explaining how to enable `SAVEQUERIES` for query timing
+- Updated translation files (.pot and .po) with new strings
+- **Key Learning**: WordPress `SAVEQUERIES` constant
+ - Enables `$wpdb->queries` array with query strings, timing, and call stacks
+ - Required for `wordpress_db_query_duration_seconds` histogram metric
+ - Has performance overhead - recommended for development, use cautiously in production
+ - Without it, only query counts are available (not timing data)
+
### 2026-02-03 - Dashboard Extension Hook (v0.4.6)
- Added `wp_prometheus_register_dashboards` action hook for third-party plugins
diff --git a/README.md b/README.md
index 64f7768..ca3d66e 100644
--- a/README.md
+++ b/README.md
@@ -98,6 +98,21 @@ scrape_configs:
**Note:** Runtime metrics aggregate data across requests. Enable only the metrics you need to minimize performance impact.
+#### Enabling Database Query Timing
+
+The `wordpress_db_query_duration_seconds` histogram requires WordPress's `SAVEQUERIES` constant to be enabled. Add this to your `wp-config.php`:
+
+```php
+define( 'SAVEQUERIES', true );
+```
+
+**Important considerations:**
+
+- `SAVEQUERIES` has a performance overhead as it logs all queries with timing and call stacks
+- Recommended for development/staging environments, use with caution in production
+- Without `SAVEQUERIES`, only query counts (`wordpress_db_queries_total`) are available
+- The histogram shows total query time per request, grouped by endpoint
+
### Cron Metrics (v0.2.0+)
| Metric | Type | Labels | Description |
diff --git a/assets/dashboards/wordpress-runtime.json b/assets/dashboards/wordpress-runtime.json
index 7f1bbc3..45a9c6c 100644
--- a/assets/dashboards/wordpress-runtime.json
+++ b/assets/dashboards/wordpress-runtime.json
@@ -946,6 +946,95 @@
],
"title": "Average Query Duration (Overall)",
"type": "stat"
+ },
+ {
+ "datasource": {
+ "type": "prometheus",
+ "uid": "${DS_PROMETHEUS}"
+ },
+ "fieldConfig": {
+ "defaults": {
+ "color": {
+ "mode": "palette-classic"
+ },
+ "custom": {
+ "axisBorderShow": false,
+ "axisCenteredZero": false,
+ "axisColorMode": "text",
+ "axisLabel": "",
+ "axisPlacement": "auto",
+ "fillOpacity": 80,
+ "gradientMode": "none",
+ "hideFrom": {
+ "legend": false,
+ "tooltip": false,
+ "viz": false
+ },
+ "lineWidth": 1,
+ "scaleDistribution": {
+ "type": "linear"
+ },
+ "thresholdsStyle": {
+ "mode": "off"
+ }
+ },
+ "mappings": [],
+ "thresholds": {
+ "mode": "absolute",
+ "steps": [
+ {
+ "color": "green",
+ "value": null
+ }
+ ]
+ }
+ },
+ "overrides": []
+ },
+ "gridPos": {
+ "h": 8,
+ "w": 24,
+ "x": 0,
+ "y": 39
+ },
+ "id": 15,
+ "options": {
+ "barRadius": 0,
+ "barWidth": 0.97,
+ "fullHighlight": false,
+ "groupWidth": 0.7,
+ "legend": {
+ "calcs": [],
+ "displayMode": "list",
+ "placement": "bottom",
+ "showLegend": true
+ },
+ "orientation": "horizontal",
+ "showValue": "auto",
+ "stacking": "none",
+ "tooltip": {
+ "mode": "single",
+ "sort": "none"
+ },
+ "xTickLabelRotation": 0,
+ "xTickLabelSpacing": 0
+ },
+ "targets": [
+ {
+ "datasource": {
+ "type": "prometheus",
+ "uid": "${DS_PROMETHEUS}"
+ },
+ "editorMode": "code",
+ "expr": "sum(wordpress_db_query_duration_seconds_bucket) by (le)",
+ "format": "table",
+ "instant": true,
+ "legendFormat": "{{le}}",
+ "refId": "A"
+ }
+ ],
+ "title": "Query Duration Distribution (Buckets)",
+ "type": "barchart"
}
],
"refresh": "30s",
diff --git a/languages/wp-prometheus-de_CH.po b/languages/wp-prometheus-de_CH.po
index b34e09b..e43e1b0 100644
--- a/languages/wp-prometheus-de_CH.po
+++ b/languages/wp-prometheus-de_CH.po
@@ -317,6 +317,10 @@ msgstr "HTTP-Anfragedauer-Verteilung"
msgid "Database queries by endpoint"
msgstr "Datenbank-Abfragen nach Endpunkt"
+#: src/Admin/Settings.php
+msgid "Database query duration distribution (requires SAVEQUERIES)"
+msgstr "Datenbank-Abfragedauer-Verteilung (erfordert SAVEQUERIES)"
+
#: src/Admin/Settings.php
msgid "Scheduled cron events by hook"
msgstr "Geplante Cron-Ereignisse nach Hook"
diff --git a/languages/wp-prometheus.pot b/languages/wp-prometheus.pot
index 50dece5..0f6681b 100644
--- a/languages/wp-prometheus.pot
+++ b/languages/wp-prometheus.pot
@@ -314,6 +314,10 @@ msgstr ""
msgid "Database queries by endpoint"
msgstr ""
+#: src/Admin/Settings.php
+msgid "Database query duration distribution (requires SAVEQUERIES)"
+msgstr ""
+
#: src/Admin/Settings.php
msgid "Scheduled cron events by hook"
msgstr ""
diff --git a/src/Admin/Settings.php b/src/Admin/Settings.php
index 7ada569..adf38de 100644
--- a/src/Admin/Settings.php
+++ b/src/Admin/Settings.php
@@ -1365,6 +1365,11 @@ class Settings {
|
|
+
+ wordpress_db_query_duration_seconds |
+ |
+ |
+
wordpress_cron_events_total |
|
diff --git a/wp-prometheus.php b/wp-prometheus.php
index b95d33b..9265b11 100644
--- a/wp-prometheus.php
+++ b/wp-prometheus.php
@@ -3,7 +3,7 @@
* Plugin Name: WP Prometheus
* Plugin URI: https://src.bundespruefstelle.ch/magdev/wp-prometheus
* Description: Prometheus metrics endpoint for WordPress with extensible hooks for custom metrics.
- * Version: 0.4.6
+ * Version: 0.4.7
* Requires at least: 6.4
* Requires PHP: 8.3
* Author: Marco Graetsch
@@ -169,7 +169,7 @@ wp_prometheus_early_metrics_check();
*
* @var string
*/
-define( 'WP_PROMETHEUS_VERSION', '0.4.6' );
+define( 'WP_PROMETHEUS_VERSION', '0.4.7' );
/**
* Plugin file path.