test(integration): add Compose-based MySQL harness and collector test runner; docs

sklochkov · sklochkov · commit e627d71f0b10 · 2025-09-11T16:47:21.000+01:00
Add a self-contained integration test that spins up MySQL 8.4 with
performance_schema, seeds a small workload, and validates collectors
via a locally-built exporter image.

What's included:
- docker-compose.yml (fixed network name: mysql-test)
- mysql/conf.d/perf-schema.cnf
- mysql/initdb/01-users.sql (exporter/app users, grants)
- seed/seed.sh (INSERT/SELECT/UPDATE/SLEEP loop)
- test_compose_collectors.sh:
  * builds mysqld-exporter:local
  * ensures users (caching_sha2_password)
  * runs exporter per --collect.* flag (no host port binding)
  * curls /metrics from inside the network
  * per-flag log files under ./_testlogs/
  * robust readiness + failure diagnostics
  * optional auto-discovery of collector flags from --help

Docs (README.md):
- Document new flags:
  --collect.sys.user_summary_by_statement_latency
  --collect.sys.user_summary_by_statement_type
  * list emitted metric families and units
- Note clamping behavior in --collect.sys.user_summary
- Add "Docker Compose integration test" section with usage

Usage:
  ./test_compose_collectors.sh
Artifacts:
  _testlogs/exporter_&lt;flag&gt;.log

License:
  Added the mandatory license comments to the newly-committed source files.

This commit touches only test infra and docs; no exporter runtime code changes.

Signed-off-by: Sergei Klochkov &lt;sklochko@thousandeyes.com&gt;
diff --git a/.gitignore b/.gitignore
@@ -9,3 +9,4 @@
 .idea
 *.iml
 /vendor
+_testlogs/
diff --git a/README.md b/README.md
@@ -206,6 +206,30 @@ docker run -d \
   prom/mysqld-exporter
 ```
 
+## Docker Compose integration test
+
+A self-contained test harness is included to validate collectors against a local MySQL:
+
+- Spins up **MySQL 8.4** with `performance_schema` on
+- Seeds basic workload so `sys` summaries have data
+- Builds and runs your **local** exporter image per collector flag
+- Captures exporter logs per test under `_testlogs/`
+- Verifies metrics via in-network HTTP (no host port binding)
+
+**Prereqs:** Docker & Docker Compose v2.
+
+**Files:**
+- `docker-compose.yml` (MySQL service + one-shot seeder)
+- `mysql/conf.d/perf-schema.cnf` (ensures P_S consumers on)
+- `mysql/initdb/01-users.sql` (creates `exporter` & `app`; grants)
+- `seed/seed.sh` (simple INSERT/SELECT/UPDATE/SLEEP loop)
+- `test_compose_collectors.sh` (runner)
+
+**Run:**
+```bash
+./test_compose_collectors.sh
+```
+
 ## heartbeat
 
 With `collect.heartbeat` enabled, mysqld_exporter will scrape replication delay
diff --git a/collector/sys_user_summary_by_statement_latency.go b/collector/sys_user_summary_by_statement_latency.go
@@ -1,3 +1,16 @@
+// Copyright 2022 The Prometheus Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package collector
 
 import (
diff --git a/collector/sys_user_summary_by_statement_latency_test.go b/collector/sys_user_summary_by_statement_latency_test.go
@@ -1,3 +1,16 @@
+// Copyright 2022 The Prometheus Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package collector
 
 import (
diff --git a/collector/sys_user_summary_by_statement_type.go b/collector/sys_user_summary_by_statement_type.go
@@ -1,3 +1,16 @@
+// Copyright 2022 The Prometheus Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package collector
 
 import (
diff --git a/collector/sys_user_summary_by_statement_type_test.go b/collector/sys_user_summary_by_statement_type_test.go
@@ -1,3 +1,16 @@
+// Copyright 2022 The Prometheus Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package collector
 
 import (
diff --git a/collector/sys_user_summary_test.go b/collector/sys_user_summary_test.go
@@ -100,8 +100,8 @@ func TestScrapeSysUserSummary(t *testing.T) {
 				value = value / picoSeconds
 			}
 			if (i == 9 || i == 10) && value < 0 {
-		                value = 0
-	                }
+				value = 0
+			}
 			expectedMetrics = append(expectedMetrics, MetricResult{
 				labels:     labelMap{"user": user.(string)},
 				value:      value,
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -0,0 +1,43 @@
+services:
+  mysql:
+    image: mysql:8.4
+    environment:
+      MYSQL_ROOT_PASSWORD: rootpass
+      MYSQL_DATABASE: testdb
+      MYSQL_USER: app
+      MYSQL_PASSWORD: app
+    command: ["--performance_schema=ON"]
+    healthcheck:
+      test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -uroot -prootpass || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 30
+    volumes:
+      - ./test-files/mysql/conf.d:/etc/mysql/conf.d:ro
+      - ./test-files/mysql/initdb:/docker-entrypoint-initdb.d:ro
+    networks:
+      mysql-test:
+        aliases:
+          - mysql   # ensure 'mysql' DNS name exists on this network
+
+  seed:
+    image: mysql:8.4
+    depends_on:
+      mysql:
+        condition: service_healthy
+    environment:
+      MYSQL_HOST: mysql
+      MYSQL_USER: app
+      MYSQL_PASSWORD: app
+      MYSQL_DATABASE: testdb
+    volumes:
+      - ./test-files/seed/seed.sh:/seed/seed.sh:ro
+    entrypoint: ["/bin/bash", "/seed/seed.sh"]
+    networks: [mysql-test]
+
+networks:
+  mysql-test:
+    name: mysql-test
+    driver: bridge
+    external: true
+
diff --git a/test-files/mysql/conf.d/perf-schema.cnf b/test-files/mysql/conf.d/perf-schema.cnf
@@ -0,0 +1,6 @@
+[mysqld]
+performance_schema=ON
+# The following consumers are typically on by default in 8.x; keeping explicit for clarity.
+performance_schema_consumer_events_statements_history=ON
+performance_schema_consumer_events_statements_history_long=ON
+performance_schema_consumer_events_statements_current=ON
diff --git a/test-files/mysql/initdb/01-users.sql b/test-files/mysql/initdb/01-users.sql
@@ -0,0 +1,11 @@
+CREATE USER IF NOT EXISTS 'exporter'@'%' IDENTIFIED BY 'exporter';
+-- Force the plugin in case the user existed from a previous run with a different plugin
+ALTER USER 'exporter'@'%' IDENTIFIED WITH caching_sha2_password BY 'exporter';
+GRANT PROCESS, REPLICATION CLIENT, SELECT ON *.* TO 'exporter'@'%';
+
+-- App user for seeding
+CREATE USER IF NOT EXISTS 'app'@'%' IDENTIFIED BY 'app';
+CREATE DATABASE IF NOT EXISTS testdb;
+GRANT ALL PRIVILEGES ON testdb.* TO 'app'@'%';
+
+FLUSH PRIVILEGES;
diff --git a/test-files/seed/seed.sh b/test-files/seed/seed.sh
@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+host="${MYSQL_HOST:-mysql}"
+user="${MYSQL_USER:-app}"
+pass="${MYSQL_PASSWORD:-app}"
+db="${MYSQL_DATABASE:-testdb}"
+
+# Helper to run mysql client quietly
+mysqlq() {
+  mysql -h "$host" -u "$user" "-p$pass" -D "$db" -ss -N -e "$1" >/dev/null 2>&1
+}
+
+echo "Seed: waiting for DNS for host '${host}'…"
+for i in {1..60}; do
+  if getent hosts "$host" > /dev/null 2>&1; then
+    echo "Seed: DNS OK ($(getent hosts "$host" | awk '{print $1}' | head -n1))"
+    break
+  fi
+  sleep 1
+  [[ $i -eq 60 ]] && { echo "Seed: DNS for '$host' not found"; exit 1; }
+done
+
+echo "Seed: waiting for MySQL TCP on ${host}:3306…"
+for i in {1..60}; do
+  if mysqladmin ping -h "$host" -u"$user" -p"$pass" --silent 2>/dev/null; then
+    echo "Seed: MySQL is up."
+    break
+  fi
+  sleep 1
+  [[ $i -eq 60 ]] && { echo "Seed: MySQL not reachable"; exit 1; }
+done
+
+# Ensure table exists (idempotent)
+mysqlq "CREATE TABLE IF NOT EXISTS t1 (id INT PRIMARY KEY AUTO_INCREMENT, v INT, ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP) ENGINE=InnoDB;"
+
+# Generate some mixed statements under the 'app' user
+for i in $(seq 1 200); do
+  mysqlq "INSERT INTO t1 (v) VALUES (FLOOR(RAND()*1000));"
+  mysqlq "SELECT COUNT(*) FROM t1;"
+  mysqlq "UPDATE t1 SET v = v + 1 WHERE id % 10 = 0;"
+  mysqlq "SELECT SLEEP(0.01);"
+done
+
+echo "Seed workload finished."
diff --git a/test_compose_collectors.sh b/test_compose_collectors.sh

-Original file line number
+Diff line change
 .idea
 *.iml
 /vendor
 +_testlogs/