wp-prometheus/CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.5.1] - 2026-03-07

Fixed

• Custom metric name sanitization: sanitize_key() was stripping colons and lowercasing names, silently mangling valid Prometheus metric names (e.g. my:Custom_metric became mycustom_metric). Added dedicated sanitize_metric_name() that preserves valid Prometheus characters.

Changed

• Consolidated 3 separate transient COUNT queries into a single query with conditional aggregation for better database performance.
• Deduplicated inline HPOS check in WooCommerce customer metrics to use existing is_hpos_enabled() method.
• Added license domain binding for authorized deployment domains.

[0.5.0] - 2026-02-26

Added

• Comprehensive PHPUnit test suite with 189 tests and 329 assertions:
  • CustomMetricBuilderTest (35 tests) - validation, CRUD, import/export
  • AuthenticationTest (13 tests) - Bearer token, query param, header extraction
  • StorageFactoryTest (25 tests) - adapter config, env vars, connection testing
  • RuntimeCollectorTest (22 tests) - endpoint normalization, histograms, singleton
  • DashboardProviderTest (27 tests) - registration validation, path traversal security
  • InstallerTest (11 tests) - activation, deactivation, uninstall cleanup
  • CollectorTest (10 tests) - registry, metric registration, render output
  • MetricsEndpointTest (5 tests) - rewrite rules, request routing
• Test bootstrap with WordPress function stubs and GlobalFunctionState helper
• CI/CD test job in Gitea release workflow that gates release builds
• php-mock/php-mock-phpunit dependency for mocking WordPress functions in namespaced code

Changed

• Release pipeline now requires passing tests before building release packages

[0.4.9] - 2026-02-26

Security

• Fixed XSS vulnerability: replaced all jQuery .html() injections with safe .text() DOM construction in admin.js
• Fixed insecure token generation: replaced Math.random() with crypto.getRandomValues() (Web Crypto API)
• Fixed XSS via string interpolation in updateValueRows(): replaced HTML string building with jQuery DOM construction
• Added 1 MB import size limit to prevent DoS via large JSON payloads in CustomMetricBuilder
• Removed site_url from metric export data to prevent information disclosure
• Added import mode validation (allowlist check) in CustomMetricBuilder

Changed

• Extracted shared authentication logic (wp_prometheus_authenticate_request()) to eliminate code duplication between MetricsEndpoint and isolated mode handler
• Extracted showNotice() helper in admin.js to DRY up 10+ duplicated AJAX response handling patterns
• Extracted is_hpos_enabled() helper method in Collector to DRY up WooCommerce HPOS checks
• Optimized WooCommerce product type counting: uses paginate: true COUNT query instead of loading all product IDs into memory
• Added missing options to Installer::uninstall() cleanup (isolated_mode, storage adapter, Redis/APCu config)

[0.4.8] - 2026-02-07

Fixed

• Fixed _load_textdomain_just_in_time notice on admin pages (WordPress 6.7+ compatibility)
• Deferred load_plugin_textdomain() to init action instead of plugins_loaded
• Deferred Settings tab label and DashboardProvider initialization to avoid early translation loading

[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

• Dashboard extension hook wp_prometheus_register_dashboards for third-party plugins
• Third-party plugins can now register their own Grafana dashboard templates
• Support for file-based and inline JSON dashboard registration
• "Extension" badge for third-party dashboards in admin UI
• Plugin attribution display for third-party dashboards
• Security: Path traversal protection for registered dashboard files
• Isolated mode support for dashboard registration hook

Changed

• DashboardProvider now supports both built-in and third-party registered dashboards
• Dashboard cards show source (built-in vs extension) with visual distinction

[0.4.5] - 2026-02-02

Fixed

• Settings now persist correctly across Metrics sub-tabs
• Auth token no longer gets cleared when saving from Selection sub-tab
• Enabled metrics no longer get cleared when saving from Endpoint sub-tab
• Isolated mode setting no longer gets cleared when saving from other sub-tabs

Changed

• Split Metrics settings into separate WordPress option groups per sub-tab
• Each sub-tab now uses its own settings group to prevent cross-tab overwrites

[0.4.4] - 2026-02-02

Added

• Safe mode for metrics collection (default):
  • Removes problematic content filters early
  • Allows third-party plugins to register wp_prometheus_collect_metrics hooks
  • Wraps custom hooks in output buffering and try-catch for protection
• Isolated mode option for maximum compatibility:
  • Outputs metrics before other plugins fully load
  • Use only if Safe mode causes issues
• WP_PROMETHEUS_ISOLATED_MODE environment variable support
• Mode comparison table in admin settings

Changed

• Replaced "early mode" with two clear modes: Safe (default) and Isolated
• Custom metrics hooks now fire by default with protection against recursion
• Filter removal now also includes the_content_feed and comment_text
• Updated admin UI with clearer explanations of each mode

Fixed

• Third-party plugins can now add custom metrics without memory issues
• Twig-based plugins (like wp-fedistream) no longer cause recursion

[0.4.3] - 2026-02-02

Added

• Sub-tabs navigation within Metrics tab (Endpoint, Selection, Runtime, Advanced)
• Option to disable early mode in admin settings (Metrics → Advanced)
• Support for WP_PROMETHEUS_DISABLE_EARLY_MODE environment variable
• Early mode status display in settings

Fixed

• Early mode setting now saves correctly (moved into form with proper settings group)

Changed

• Reorganized Metrics tab into logical sub-sections for better usability
• Early mode can now be disabled for users who need the wp_prometheus_collect_metrics hook
• Updated translations with sub-tab and early mode strings (English and German)

[0.4.1] - 2026-02-02

Fixed

• Fixed memory exhaustion when wp-fedistream (Twig-based) plugin is active
• Added early metrics endpoint handler that intercepts /metrics requests before full WordPress initialization
• Removed content filters (the_content, the_excerpt, get_the_excerpt, the_title) during metrics collection to prevent recursion
• Skip third-party extensibility hooks during early metrics mode to avoid conflicts
• Changed template_redirect hook to parse_request for earlier request interception

[0.4.0] - 2026-02-02

Added

• Persistent Storage Support:
  • Redis storage adapter for shared metrics across multiple instances
  • APCu storage adapter for single-server high-performance caching
  • StorageFactory class for automatic adapter selection and fallback
  • Connection testing with detailed error messages
• New "Storage" tab in admin settings:
  • Storage adapter selection (In-Memory, Redis, APCu)
  • Redis configuration (host, port, password, database, key prefix)
  • APCu configuration (key prefix)
  • Connection test button
  • Environment variables documentation
• Environment variable configuration for Docker/containerized environments:
  • WP_PROMETHEUS_STORAGE_ADAPTER - Select storage adapter
  • WP_PROMETHEUS_REDIS_HOST - Redis server hostname
  • WP_PROMETHEUS_REDIS_PORT - Redis server port
  • WP_PROMETHEUS_REDIS_PASSWORD - Redis authentication
  • WP_PROMETHEUS_REDIS_DATABASE - Redis database index (0-15)
  • WP_PROMETHEUS_REDIS_PREFIX - Redis key prefix
  • WP_PROMETHEUS_APCU_PREFIX - APCu key prefix
• Automatic fallback to In-Memory storage if configured adapter fails
• Docker Compose example in admin settings

Changed

• Settings page now has 6 tabs: License, Metrics, Storage, Custom Metrics, Dashboards, Help
• Updated translations with all new strings (English and German)
• Collector now uses StorageFactory for storage adapter instantiation

[0.3.0] - 2026-02-02

Added

• Custom Metrics Builder:
  • Admin UI to define custom gauge metrics
  • Support for static values and WordPress option-based values
  • Label support with up to 5 labels and 50 value combinations
  • Metric validation following Prometheus naming conventions
• Metric Export/Import:
  • JSON-based configuration export for backup
  • Import with three modes: skip existing, overwrite, or rename duplicates
  • Version tracking in export format
• Grafana Dashboard Templates:
  • WordPress Overview dashboard (users, posts, comments, cron, transients)
  • WordPress Runtime dashboard (HTTP requests, database queries)
  • WordPress WooCommerce dashboard (orders, revenue, products, customers)
  • Easy download and import instructions
• New "Custom Metrics" tab in admin settings
• New "Dashboards" tab in admin settings
• Reset runtime metrics button to clear accumulated data

Changed

• Settings page now has 5 tabs: License, Metrics, Custom Metrics, Dashboards, Help
• Updated translations with all new strings

[0.2.2] - 2026-02-02

Fixed

• Fixed wc_orders_count() call missing required status parameter in WooCommerce orders metrics

[0.2.1] - 2026-02-02

Added

• Localhost license bypass for development environments (localhost, 127.0.0.1, ::1, *.localhost, *.local)
• Automatic rewrite rules flush when license status changes

Fixed

• Fixed 404 error on /metrics endpoint when license becomes valid after plugin activation

[0.2.0] - 2026-02-02

Added

• WooCommerce integration metrics (when WooCommerce is active):
  • wordpress_woocommerce_products_total - Products by status and type
  • wordpress_woocommerce_orders_total - Orders by status
  • wordpress_woocommerce_revenue_total - Revenue (all time, today, month)
  • wordpress_woocommerce_customers_total - Customers (registered, guest)
• Cron job metrics:
  • wordpress_cron_events_total - Scheduled cron events by hook
  • wordpress_cron_overdue_total - Number of overdue cron events
  • wordpress_cron_next_run_timestamp - Unix timestamp of next scheduled cron
• Transient cache metrics:
  • wordpress_transients_total - Transients by type (total, with_expiration, persistent, expired)
• WooCommerce metrics section in settings (only visible when WooCommerce is active)
• Support for WooCommerce HPOS (High-Performance Order Storage)

Changed

• Updated Help tab with new metrics reference

[0.1.1] - 2026-02-02

Changed

• Reorganized settings page with tabbed interface (License, Metrics, Help tabs)
• Moved Prometheus configuration help to dedicated Help tab
• Separated static and runtime metrics in settings with descriptions
• Added admin CSS for improved tab styling

Added

• New Help tab with endpoint information, curl examples, and metrics reference table
• Custom code examples section in Help tab

[0.1.0] - 2026-02-02

Added

• HTTP request metrics:
  • wordpress_http_requests_total - Counter of HTTP requests by method, status code, and endpoint
  • wordpress_http_request_duration_seconds - Histogram of request durations
• Database query metrics:
  • wordpress_db_queries_total - Counter of database queries by endpoint
  • wordpress_db_query_duration_seconds - Histogram of query durations (requires SAVEQUERIES)
• RuntimeCollector class for collecting metrics during WordPress request lifecycle
• New settings options for enabling/disabling runtime metrics
• Translation files (.pot, .po, .mo) for German (Switzerland)

Changed

• Metrics are now categorized into static metrics (users, posts, etc.) and runtime metrics (HTTP, database)
• Runtime metrics only collected when explicitly enabled and license is valid

[0.0.2] - 2026-02-01

Fixed

• Fixed composer.json dependency version constraint for wc-licensed-product-client (^0.2.2 instead of dev-main)
• Changed minimum-stability back to stable

[0.0.1] - 2026-02-01

Added

• Initial plugin structure and bootstrap
• Main plugin class with singleton pattern
• License management integration with wc-licensed-product-client
• Prometheus metrics collector with default WordPress metrics:
  • wordpress_info - WordPress installation information
  • wordpress_users_total - Total users by role
  • wordpress_posts_total - Total posts by type and status
  • wordpress_comments_total - Total comments by status
  • wordpress_plugins_total - Total plugins by status
• Authenticated /metrics endpoint with Bearer token
• Admin settings page under Settings > Metrics
• Extensibility via wp_prometheus_collect_metrics action hook
• Gitea CI/CD pipeline for automated releases
• Comprehensive documentation (README.md, PLAN.md, CLAUDE.md)

Security

• Bearer token authentication for metrics endpoint
• Nonce verification for all AJAX requests
• Capability checks for admin operations
• Input sanitization and output escaping