Embedded Prometheus metrics exporter plugin

Docs/prometheus_exporter.md

@@ -0,0 +1,65 @@
+# Prometheus Exporter Plugin
+
+Embedded Prometheus metrics exporter for VillageSQL.
+
+## Platform Support
+
+The plugin is built and supported on Linux only. The current implementation
+uses Linux-specific networking/thread wakeup primitives, so non-Linux builds do
+not compile the module.
+
+## Quick Start
+
+### 1. Verify the plugin can be loaded
+
+```sql
+INSTALL PLUGIN prometheus_exporter SONAME 'prometheus_exporter.so';
+SELECT PLUGIN_NAME, PLUGIN_STATUS
+FROM INFORMATION_SCHEMA.PLUGINS
+WHERE PLUGIN_NAME = 'prometheus_exporter';
+UNINSTALL PLUGIN prometheus_exporter;
+```
+
+This confirms the shared object is present and loadable, but it does not start
+the HTTP endpoint by itself.
+
+### 2. Enable the HTTP endpoint at server startup
+
+```ini
+[mysqld]
+plugin-load=prometheus_exporter=prometheus_exporter.so
+prometheus-exporter-enabled=ON
+prometheus-exporter-port=9104
+prometheus-exporter-bind-address=127.0.0.1
+```
+
+Use a numeric IPv4 bind address such as `127.0.0.1`. The current listener does
+not accept hostnames like `localhost`.
+
+Restart the server, then verify:
+
+```bash
+curl http://127.0.0.1:9104/metrics
+```
+
+## Replica Metrics
+
+Replica metrics are emitted from `SHOW REPLICA STATUS`.
+
+- Single-channel replication exposes one sample per metric family.
+- Multi-channel replication exposes one sample per named channel using a
+  `channel="..."` label.
+- The default unnamed channel remains unlabeled.
+
+Example:
+
+```text
+# TYPE mysql_replica_io_running gauge
+mysql_replica_io_running{channel="channel_1"} 1
+mysql_replica_io_running{channel="channel_3"} 1
+```
+
+## Reference
+
+For full configuration, architecture, and collector details, see
+[plugin/prometheus_exporter/README.md](../plugin/prometheus_exporter/README.md).

mysql-test/include/plugin.defs

@@ -192,3 +192,6 @@ component_test_execute_prepared_statement  plugin_output_directory  no  COMPONEN
 
 # component_test_execute_regular_statement
 component_test_execute_regular_statement  plugin_output_directory  no  COMPONENT_TEST_EXECUTE_REGULAR_STATEMENT
+
+# Prometheus exporter plugin
+prometheus_exporter                     plugin_output_directory  no PROMETHEUS_EXPORTER_PLUGIN    prometheus_exporter

mysql-test/suite/prometheus_exporter/inc/have_prometheus_exporter_plugin.inc

@@ -0,0 +1,5 @@
+--disable_query_log
+if (!$PROMETHEUS_EXPORTER_PLUGIN) {
+  --skip prometheus_exporter plugin is not built on this platform or not available in the mysql-test environment
+}
+--enable_query_log

mysql-test/suite/prometheus_exporter/r/basic.result

@@ -0,0 +1,17 @@
+# Install prometheus_exporter plugin
+INSTALL PLUGIN prometheus_exporter SONAME 'PROMETHEUS_EXPORTER_PLUGIN';
+# Verify system variables exist with correct defaults
+SHOW VARIABLES LIKE 'prometheus_exporter%';
+Variable_name	Value
+prometheus_exporter_bind_address	127.0.0.1
+prometheus_exporter_enabled	OFF
+prometheus_exporter_port	9104
+prometheus_exporter_security_user	root
+# Verify status variables exist (all zero when disabled)
+SHOW STATUS LIKE 'Prometheus_exporter%';
+Variable_name	Value
+Prometheus_exporter_errors_total	0
+Prometheus_exporter_requests_total	0
+Prometheus_exporter_scrape_duration_microseconds	0
+# Uninstall plugin
+UNINSTALL PLUGIN prometheus_exporter;

mysql-test/suite/prometheus_exporter/r/binlog.result

@@ -0,0 +1,6 @@
+# Verify binlog metrics are present
+# TYPE mysql_binlog_file_count gauge
+# Verify binlog size metric
+# TYPE mysql_binlog_size_bytes_total gauge
+# Verify values are numeric
+mysql_binlog_file_count NUM

mysql-test/suite/prometheus_exporter/r/format_validation.result

@@ -0,0 +1,2 @@
+# Fetching and validating /metrics output format
+OK: format validation passed

mysql-test/suite/prometheus_exporter/r/global_variables.result

@@ -0,0 +1,6 @@
+# Verify mysql_global_variables_ metrics are present
+# TYPE mysql_global_variables_max_connections gauge
+# Verify a buffer pool size variable is exported
+# TYPE mysql_global_variables_innodb_buffer_pool_size gauge
+# Verify the value is numeric
+mysql_global_variables_max_connections NUM

mysql-test/suite/prometheus_exporter/r/innodb_metrics.result

@@ -0,0 +1,8 @@
+# Verify InnoDB metrics are present
+# TYPE mysql_innodb_metrics_lock_deadlocks counter
+# TYPE mysql_innodb_metrics_lock_deadlock_false_positives counter
+# TYPE mysql_innodb_metrics_lock_deadlock_rounds counter
+# Verify a known gauge type metric exists (buffer_pool_reads is status_counter in InnoDB)
+# TYPE mysql_innodb_metrics_buffer_pool_reads gauge
+# Verify a known gauge type metric exists (buffer_pool_size is 'value' type in InnoDB)
+# TYPE mysql_innodb_metrics_buffer_pool_size gauge

mysql-test/suite/prometheus_exporter/r/metrics_endpoint.result

@@ -0,0 +1,19 @@
+SHOW VARIABLES LIKE 'prometheus_exporter_enabled';
+Variable_name	Value
+prometheus_exporter_enabled	ON
+# Verify SHOW GLOBAL STATUS metrics
+# TYPE mysql_global_status_threads_connected gauge
+# Verify SHOW GLOBAL VARIABLES metrics
+# TYPE mysql_global_variables_max_connections gauge
+# Verify INNODB_METRICS metrics
+# TYPE mysql_innodb_metrics_lock_deadlocks counter
+# Verify binlog metrics (binary logging is on by default)
+# TYPE mysql_binlog_file_count gauge
+# Verify metric value line is present and numeric
+mysql_global_status_threads_connected NUM
+# Test 404 for unknown paths
+404
+# Verify scrape counter incremented
+SHOW STATUS LIKE 'Prometheus_exporter_requests_total';
+Variable_name	Value
+Prometheus_exporter_requests_total	NUM

mysql-test/suite/prometheus_exporter/r/replica_channels.result

@@ -0,0 +1,13 @@
+include/rpl/init.inc [topology=1->2,3->2]
+include/rpl/start_replica.inc [FOR CHANNEL 'channel_1']
+include/rpl/start_replica.inc [FOR CHANNEL 'channel_3']
+# Verify multi-channel replica metrics carry a channel label
+1
+2
+1
+1
+mysql_replica_io_running{channel="channel_1"} 1
+mysql_replica_io_running{channel="channel_3"} 1
+mysql_replica_sql_running{channel="channel_1"} 1
+mysql_replica_sql_running{channel="channel_3"} 1
+include/rpl/deinit.inc

mysql-test/suite/prometheus_exporter/r/replica_null_lag.result

@@ -0,0 +1,9 @@
+include/rpl/init_source_replica.inc
+[connection master]
+include/rpl/stop_replica.inc
+# Stopped replicas still expose lag as NaN instead of dropping the series
+1
+mysql_replica_seconds_behind_source NaN
+mysql_replica_io_running 0
+mysql_replica_sql_running 0
+include/rpl/deinit.inc

mysql-test/suite/prometheus_exporter/r/replica_status.result

@@ -0,0 +1,4 @@
+# On a non-replica server, no mysql_replica_ metrics should appear
+0
+# But other metrics should still be present
+# TYPE mysql_global_status_uptime gauge

mysql-test/suite/prometheus_exporter/r/scrape_counter.result

@@ -0,0 +1,23 @@
+# Capture baseline counter
+SELECT VARIABLE_VALUE INTO @before FROM performance_schema.global_status
+WHERE VARIABLE_NAME = 'Prometheus_exporter_requests_total';
+# Issue exactly 3 scrapes
+# Capture counter after scrapes
+SELECT VARIABLE_VALUE INTO @after FROM performance_schema.global_status
+WHERE VARIABLE_NAME = 'Prometheus_exporter_requests_total';
+# Assert delta is exactly 3
+SELECT (@after - @before) = 3 AS counter_delta_is_three;
+counter_delta_is_three
+1
+# Also verify scrape_duration_microseconds is now > 0
+SELECT VARIABLE_VALUE > 0 AS scrape_duration_is_positive
+FROM performance_schema.global_status
+WHERE VARIABLE_NAME = 'Prometheus_exporter_scrape_duration_microseconds';
+scrape_duration_is_positive
+1
+# And verify errors_total is still 0 (no errors on successful scrapes)
+SELECT VARIABLE_VALUE = 0 AS errors_total_is_zero
+FROM performance_schema.global_status
+WHERE VARIABLE_NAME = 'Prometheus_exporter_errors_total';
+errors_total_is_zero
+1

mysql-test/suite/prometheus_exporter/r/scrape_error.result

@@ -0,0 +1,7 @@
+# Failed scrapes return HTTP 500 instead of a false-success 200
+500
+# Failed to set security context (user missing or lacks privileges?)
+# Failed scrapes increment the exporter error counter
+SHOW STATUS LIKE 'Prometheus_exporter_errors_total';
+Variable_name	Value
+Prometheus_exporter_errors_total	NUM

mysql-test/suite/prometheus_exporter/t/basic.test

@@ -0,0 +1,34 @@
+# =============================================================================
+# basic.test -- Prometheus Exporter Plugin: Install/Uninstall Lifecycle
+#
+# Verifies:
+# - Plugin can be dynamically installed and uninstalled
+# - System variables (enabled, port, bind_address) are registered
+# - Status variables (requests_total, errors_total, scrape_duration) exist
+# - Default values are correct (enabled=OFF, port=9104, bind=0.0.0.0)
+# =============================================================================
+
+--source include/not_windows.inc
+
+# Check that plugin is available
+disable_query_log;
+if (`SELECT @@have_dynamic_loading != 'YES'`) {
+  --skip prometheus_exporter plugin requires dynamic loading
+}
+if (!$PROMETHEUS_EXPORTER_PLUGIN) {
+  --skip prometheus_exporter plugin requires the environment variable \$PROMETHEUS_EXPORTER_PLUGIN to be set (normally done by mtr)
+}
+enable_query_log;
+
+--echo # Install prometheus_exporter plugin
+--replace_result $PROMETHEUS_EXPORTER_PLUGIN PROMETHEUS_EXPORTER_PLUGIN
+eval INSTALL PLUGIN prometheus_exporter SONAME '$PROMETHEUS_EXPORTER_PLUGIN';
+
+--echo # Verify system variables exist with correct defaults
+SHOW VARIABLES LIKE 'prometheus_exporter%';
+
+--echo # Verify status variables exist (all zero when disabled)
+SHOW STATUS LIKE 'Prometheus_exporter%';
+
+--echo # Uninstall plugin
+UNINSTALL PLUGIN prometheus_exporter;

mysql-test/suite/prometheus_exporter/t/binlog-master.opt

@@ -0,0 +1 @@
+$PROMETHEUS_EXPORTER_PLUGIN_OPT $PROMETHEUS_EXPORTER_PLUGIN_LOAD --loose-prometheus-exporter-enabled=ON --loose-prometheus-exporter-port=19108 --loose-prometheus-exporter-bind-address=127.0.0.1

mysql-test/suite/prometheus_exporter/t/binlog.test

@@ -0,0 +1,12 @@
+--source include/not_windows.inc
+--source suite/prometheus_exporter/inc/have_prometheus_exporter_plugin.inc
+
+--echo # Verify binlog metrics are present
+--exec curl -s http://127.0.0.1:19108/metrics | grep "^# TYPE mysql_binlog_file_count gauge" | head -1
+
+--echo # Verify binlog size metric
+--exec curl -s http://127.0.0.1:19108/metrics | grep "^# TYPE mysql_binlog_size_bytes_total gauge" | head -1
+
+--echo # Verify values are numeric
+--replace_regex /[0-9]+/NUM/
+--exec curl -s http://127.0.0.1:19108/metrics | grep "^mysql_binlog_file_count " | head -1

mysql-test/suite/prometheus_exporter/t/format_validation-master.opt

@@ -0,0 +1 @@
+$PROMETHEUS_EXPORTER_PLUGIN_OPT $PROMETHEUS_EXPORTER_PLUGIN_LOAD --loose-prometheus-exporter-enabled=ON --loose-prometheus-exporter-port=19109 --loose-prometheus-exporter-bind-address=127.0.0.1

mysql-test/suite/prometheus_exporter/t/format_validation.test

@@ -0,0 +1,92 @@
+# =============================================================================
+# format_validation.test -- Validates Prometheus exposition format correctness
+#
+# Uses a perl block to fetch /metrics and validate:
+# - Every # TYPE line has a valid type (counter, gauge, untyped)
+# - Every # TYPE line is followed by a metric line with matching name
+# - Metric lines may optionally include Prometheus labels
+# - Metric names match [a-z_][a-z0-9_]*
+# - Every metric value is numeric or NaN/+Inf/-Inf per Prometheus spec
+# =============================================================================
+
+--source include/not_windows.inc
+--source suite/prometheus_exporter/inc/have_prometheus_exporter_plugin.inc
+
+--echo # Fetching and validating /metrics output format
+
+--perl
+use strict;
+use warnings;
+
+my $output = `curl -s http://127.0.0.1:19109/metrics`;
+my @lines = split /\n/, $output;
+my $errors = 0;
+my $metrics_count = 0;
+my $expect_metric_name = undef;
+my %seen_types;
+
+for (my $i = 0; $i < scalar @lines; $i++) {
+  my $line = $lines[$i];
+
+  # Skip empty lines
+  next if $line =~ /^\s*$/;
+
+  # Check # TYPE lines
+  if ($line =~ /^# TYPE /) {
+    if (defined $expect_metric_name) {
+      print "FORMAT ERROR: missing metric line for TYPE '$expect_metric_name'\n";
+      $errors++;
+    }
+    if ($line =~ /^# TYPE ([a-z_][a-z0-9_]*) (counter|gauge|untyped)$/) {
+      if ($seen_types{$1}++) {
+        print "FORMAT ERROR: duplicate TYPE line for '$1'\n";
+        $errors++;
+      }
+      $expect_metric_name = $1;
+    } else {
+      print "FORMAT ERROR: invalid TYPE line: $line\n";
+      $errors++;
+      $expect_metric_name = undef;
+    }
+    next;
+  }
+
+  # Skip other comment lines
+  next if $line =~ /^#/;
+
+  # Metric value line
+  if ($line =~ /^([a-z_][a-z0-9_]*)(\{(?:[a-z_][a-z0-9_]*="(?:[^"\\]|\\["\\n])*"(?:,[a-z_][a-z0-9_]*="(?:[^"\\]|\\["\\n])*")*)\})? (.+)$/) {
+    my ($name, $value) = ($1, $3);
+    $metrics_count++;
+
+    # Check name matches expected from TYPE line
+    if (defined $expect_metric_name && $name ne $expect_metric_name) {
+      print "FORMAT ERROR: expected metric '$expect_metric_name' but got '$name'\n";
+      $errors++;
+    }
+    $expect_metric_name = undef;
+
+    # Check value is numeric (Prometheus exposition format: numeric or NaN/Inf)
+    unless ($value =~ /^(-?[0-9]+(\.[0-9]+)?([eE][+-]?[0-9]+)?|NaN|\+Inf|-Inf)$/) {
+      print "FORMAT ERROR: non-numeric value '$value' for metric '$name'\n";
+      $errors++;
+    }
+  } else {
+    print "FORMAT ERROR: unrecognized line: $line\n";
+    $errors++;
+  }
+}
+
+if (defined $expect_metric_name) {
+  print "FORMAT ERROR: missing metric line for TYPE '$expect_metric_name'\n";
+  $errors++;
+}
+
+if ($errors == 0 && $metrics_count > 0) {
+  print "OK: format validation passed\n";
+} elsif ($metrics_count == 0) {
+  print "ERROR: no metrics found in output\n";
+} else {
+  print "FAIL: $errors format errors found in $metrics_count metrics\n";
+}
+EOF

mysql-test/suite/prometheus_exporter/t/global_variables-master.opt

@@ -0,0 +1 @@
+$PROMETHEUS_EXPORTER_PLUGIN_OPT $PROMETHEUS_EXPORTER_PLUGIN_LOAD --loose-prometheus-exporter-enabled=ON --loose-prometheus-exporter-port=19105 --loose-prometheus-exporter-bind-address=127.0.0.1

mysql-test/suite/prometheus_exporter/t/global_variables.test

@@ -0,0 +1,12 @@
+--source include/not_windows.inc
+--source suite/prometheus_exporter/inc/have_prometheus_exporter_plugin.inc
+
+--echo # Verify mysql_global_variables_ metrics are present
+--exec curl -s http://127.0.0.1:19105/metrics | grep "^# TYPE mysql_global_variables_max_connections gauge" | head -1
+
+--echo # Verify a buffer pool size variable is exported
+--exec curl -s http://127.0.0.1:19105/metrics | grep "^# TYPE mysql_global_variables_innodb_buffer_pool_size gauge" | head -1
+
+--echo # Verify the value is numeric
+--replace_regex /[0-9]+/NUM/
+--exec curl -s http://127.0.0.1:19105/metrics | grep "^mysql_global_variables_max_connections " | head -1

mysql-test/suite/prometheus_exporter/t/innodb_metrics-master.opt

@@ -0,0 +1 @@
+$PROMETHEUS_EXPORTER_PLUGIN_OPT $PROMETHEUS_EXPORTER_PLUGIN_LOAD --loose-prometheus-exporter-enabled=ON --loose-prometheus-exporter-port=19106 --loose-prometheus-exporter-bind-address=127.0.0.1

mysql-test/suite/prometheus_exporter/t/innodb_metrics.test

@@ -0,0 +1,11 @@
+--source include/not_windows.inc
+--source suite/prometheus_exporter/inc/have_prometheus_exporter_plugin.inc
+
+--echo # Verify InnoDB metrics are present
+--exec curl -s http://127.0.0.1:19106/metrics | grep "^# TYPE mysql_innodb_metrics_" | head -3
+
+--echo # Verify a known gauge type metric exists (buffer_pool_reads is status_counter in InnoDB)
+--exec curl -s http://127.0.0.1:19106/metrics | grep "^# TYPE mysql_innodb_metrics_buffer_pool_reads " | head -1
+
+--echo # Verify a known gauge type metric exists (buffer_pool_size is 'value' type in InnoDB)
+--exec curl -s http://127.0.0.1:19106/metrics | grep "^# TYPE mysql_innodb_metrics_buffer_pool_size " | head -1

mysql-test/suite/prometheus_exporter/t/metrics_endpoint-master.opt

@@ -0,0 +1 @@
+$PROMETHEUS_EXPORTER_PLUGIN_OPT $PROMETHEUS_EXPORTER_PLUGIN_LOAD --loose-prometheus-exporter-enabled=ON --loose-prometheus-exporter-port=19104 --loose-prometheus-exporter-bind-address=127.0.0.1