diff --git a/composites/ebean-clickhouse/pom.xml b/composites/ebean-clickhouse/pom.xml
index bc8ccc0e9..1f76f437f 100644
--- a/composites/ebean-clickhouse/pom.xml
+++ b/composites/ebean-clickhouse/pom.xml
@@ -4,7 +4,7 @@
ebean-parent
io.ebean
- 16.8.0
+ 16.9.0
../..
@@ -17,13 +17,13 @@
io.ebean
ebean-api
- 16.8.0
+ 16.9.0
io.ebean
ebean-core
- 16.8.0
+ 16.9.0
@@ -42,13 +42,13 @@
io.ebean
ebean-querybean
- 16.8.0
+ 16.9.0
io.ebean
ebean-platform-clickhouse
- 16.8.0
+ 16.9.0
diff --git a/composites/ebean-cockroach/pom.xml b/composites/ebean-cockroach/pom.xml
index 45b30c311..6c7241ece 100644
--- a/composites/ebean-cockroach/pom.xml
+++ b/composites/ebean-cockroach/pom.xml
@@ -4,7 +4,7 @@
ebean-parent
io.ebean
- 16.8.0
+ 16.9.0
../..
@@ -17,13 +17,13 @@
io.ebean
ebean-api
- 16.8.0
+ 16.9.0
io.ebean
ebean-core
- 16.8.0
+ 16.9.0
@@ -42,13 +42,13 @@
io.ebean
ebean-querybean
- 16.8.0
+ 16.9.0
io.ebean
ebean-platform-postgres
- 16.8.0
+ 16.9.0
diff --git a/composites/ebean-db2/pom.xml b/composites/ebean-db2/pom.xml
index 7bcb410cb..ceb4666af 100644
--- a/composites/ebean-db2/pom.xml
+++ b/composites/ebean-db2/pom.xml
@@ -4,7 +4,7 @@
ebean-parent
io.ebean
- 16.8.0
+ 16.9.0
../..
@@ -17,13 +17,13 @@
io.ebean
ebean-api
- 16.8.0
+ 16.9.0
io.ebean
ebean-core
- 16.8.0
+ 16.9.0
@@ -42,13 +42,13 @@
io.ebean
ebean-querybean
- 16.8.0
+ 16.9.0
io.ebean
ebean-platform-db2
- 16.8.0
+ 16.9.0
diff --git a/composites/ebean-h2/pom.xml b/composites/ebean-h2/pom.xml
index 500e10071..181f680b9 100644
--- a/composites/ebean-h2/pom.xml
+++ b/composites/ebean-h2/pom.xml
@@ -4,7 +4,7 @@
ebean-parent
io.ebean
- 16.8.0
+ 16.9.0
../..
@@ -17,13 +17,13 @@
io.ebean
ebean-api
- 16.8.0
+ 16.9.0
io.ebean
ebean-core
- 16.8.0
+ 16.9.0
@@ -42,13 +42,13 @@
io.ebean
ebean-querybean
- 16.8.0
+ 16.9.0
io.ebean
ebean-platform-h2
- 16.8.0
+ 16.9.0
diff --git a/composites/ebean-hana/pom.xml b/composites/ebean-hana/pom.xml
index 9ac12cb9d..16bb06d8e 100644
--- a/composites/ebean-hana/pom.xml
+++ b/composites/ebean-hana/pom.xml
@@ -4,7 +4,7 @@
ebean-parent
io.ebean
- 16.8.0
+ 16.9.0
../..
@@ -17,13 +17,13 @@
io.ebean
ebean-api
- 16.8.0
+ 16.9.0
io.ebean
ebean-core
- 16.8.0
+ 16.9.0
@@ -42,13 +42,13 @@
io.ebean
ebean-querybean
- 16.8.0
+ 16.9.0
io.ebean
ebean-platform-hana
- 16.8.0
+ 16.9.0
diff --git a/composites/ebean-mariadb/pom.xml b/composites/ebean-mariadb/pom.xml
index 432b4bad3..7c7f2b92d 100644
--- a/composites/ebean-mariadb/pom.xml
+++ b/composites/ebean-mariadb/pom.xml
@@ -4,7 +4,7 @@
ebean-parent
io.ebean
- 16.8.0
+ 16.9.0
../..
@@ -17,13 +17,13 @@
io.ebean
ebean-api
- 16.8.0
+ 16.9.0
io.ebean
ebean-core
- 16.8.0
+ 16.9.0
@@ -42,13 +42,13 @@
io.ebean
ebean-querybean
- 16.8.0
+ 16.9.0
io.ebean
ebean-platform-mariadb
- 16.8.0
+ 16.9.0
diff --git a/composites/ebean-mysql/pom.xml b/composites/ebean-mysql/pom.xml
index 9db47ca03..de040cf16 100644
--- a/composites/ebean-mysql/pom.xml
+++ b/composites/ebean-mysql/pom.xml
@@ -4,7 +4,7 @@
ebean-parent
io.ebean
- 16.8.0
+ 16.9.0
../..
@@ -17,13 +17,13 @@
io.ebean
ebean-api
- 16.8.0
+ 16.9.0
io.ebean
ebean-core
- 16.8.0
+ 16.9.0
@@ -42,13 +42,13 @@
io.ebean
ebean-querybean
- 16.8.0
+ 16.9.0
io.ebean
ebean-platform-mysql
- 16.8.0
+ 16.9.0
diff --git a/composites/ebean-net-postgis/pom.xml b/composites/ebean-net-postgis/pom.xml
index 9e00c1503..230268d34 100644
--- a/composites/ebean-net-postgis/pom.xml
+++ b/composites/ebean-net-postgis/pom.xml
@@ -4,7 +4,7 @@
ebean-parent
io.ebean
- 16.8.0
+ 16.9.0
../..
@@ -22,13 +22,13 @@
io.ebean
ebean-api
- 16.8.0
+ 16.9.0
io.ebean
ebean-core
- 16.8.0
+ 16.9.0
@@ -47,19 +47,19 @@
io.ebean
ebean-querybean
- 16.8.0
+ 16.9.0
io.ebean
ebean-platform-postgres
- 16.8.0
+ 16.9.0
io.ebean
ebean-net-postgis-types
- 16.8.0
+ 16.9.0
diff --git a/composites/ebean-nuodb/pom.xml b/composites/ebean-nuodb/pom.xml
index 3cdad833f..6aae67cd6 100644
--- a/composites/ebean-nuodb/pom.xml
+++ b/composites/ebean-nuodb/pom.xml
@@ -4,7 +4,7 @@
ebean-parent
io.ebean
- 16.8.0
+ 16.9.0
../..
@@ -17,13 +17,13 @@
io.ebean
ebean-api
- 16.8.0
+ 16.9.0
io.ebean
ebean-core
- 16.8.0
+ 16.9.0
@@ -42,13 +42,13 @@
io.ebean
ebean-querybean
- 16.8.0
+ 16.9.0
io.ebean
ebean-platform-nuodb
- 16.8.0
+ 16.9.0
diff --git a/composites/ebean-oracle/pom.xml b/composites/ebean-oracle/pom.xml
index 5fe0d8dd1..7835694ea 100644
--- a/composites/ebean-oracle/pom.xml
+++ b/composites/ebean-oracle/pom.xml
@@ -4,7 +4,7 @@
ebean-parent
io.ebean
- 16.8.0
+ 16.9.0
../..
@@ -17,13 +17,13 @@
io.ebean
ebean-api
- 16.8.0
+ 16.9.0
io.ebean
ebean-core
- 16.8.0
+ 16.9.0
@@ -42,13 +42,13 @@
io.ebean
ebean-querybean
- 16.8.0
+ 16.9.0
io.ebean
ebean-platform-oracle
- 16.8.0
+ 16.9.0
diff --git a/composites/ebean-pgvector/pom.xml b/composites/ebean-pgvector/pom.xml
index 21ffa121f..22d653781 100644
--- a/composites/ebean-pgvector/pom.xml
+++ b/composites/ebean-pgvector/pom.xml
@@ -4,7 +4,7 @@
ebean-parent
io.ebean
- 16.8.0
+ 16.9.0
../..
@@ -22,13 +22,13 @@
io.ebean
ebean-api
- 16.8.0
+ 16.9.0
io.ebean
ebean-core
- 16.8.0
+ 16.9.0
@@ -47,19 +47,19 @@
io.ebean
ebean-querybean
- 16.8.0
+ 16.9.0
io.ebean
ebean-platform-postgres
- 16.8.0
+ 16.9.0
io.ebean
ebean-pgvector-types
- 16.8.0
+ 16.9.0
diff --git a/composites/ebean-postgis/pom.xml b/composites/ebean-postgis/pom.xml
index ae694397f..a320e5b3d 100644
--- a/composites/ebean-postgis/pom.xml
+++ b/composites/ebean-postgis/pom.xml
@@ -4,7 +4,7 @@
ebean-parent
io.ebean
- 16.8.0
+ 16.9.0
../..
@@ -22,13 +22,13 @@
io.ebean
ebean-api
- 16.8.0
+ 16.9.0
io.ebean
ebean-core
- 16.8.0
+ 16.9.0
@@ -47,19 +47,19 @@
io.ebean
ebean-querybean
- 16.8.0
+ 16.9.0
io.ebean
ebean-platform-postgres
- 16.8.0
+ 16.9.0
io.ebean
ebean-postgis-types
- 16.8.0
+ 16.9.0
diff --git a/composites/ebean-postgres/pom.xml b/composites/ebean-postgres/pom.xml
index e3874f5ae..0b58e5195 100644
--- a/composites/ebean-postgres/pom.xml
+++ b/composites/ebean-postgres/pom.xml
@@ -4,7 +4,7 @@
ebean-parent
io.ebean
- 16.8.0
+ 16.9.0
../..
@@ -17,13 +17,13 @@
io.ebean
ebean-api
- 16.8.0
+ 16.9.0
io.ebean
ebean-core
- 16.8.0
+ 16.9.0
@@ -42,13 +42,13 @@
io.ebean
ebean-querybean
- 16.8.0
+ 16.9.0
io.ebean
ebean-platform-postgres
- 16.8.0
+ 16.9.0
diff --git a/composites/ebean-sqlite/pom.xml b/composites/ebean-sqlite/pom.xml
index cbbd2f71f..79e369052 100644
--- a/composites/ebean-sqlite/pom.xml
+++ b/composites/ebean-sqlite/pom.xml
@@ -4,7 +4,7 @@
ebean-parent
io.ebean
- 16.8.0
+ 16.9.0
../..
@@ -17,13 +17,13 @@
io.ebean
ebean-api
- 16.8.0
+ 16.9.0
io.ebean
ebean-core
- 16.8.0
+ 16.9.0
@@ -42,13 +42,13 @@
io.ebean
ebean-querybean
- 16.8.0
+ 16.9.0
io.ebean
ebean-platform-sqlite
- 16.8.0
+ 16.9.0
diff --git a/composites/ebean-sqlserver/pom.xml b/composites/ebean-sqlserver/pom.xml
index 966de043a..79d642e36 100644
--- a/composites/ebean-sqlserver/pom.xml
+++ b/composites/ebean-sqlserver/pom.xml
@@ -4,7 +4,7 @@
ebean-parent
io.ebean
- 16.8.0
+ 16.9.0
../..
@@ -17,13 +17,13 @@
io.ebean
ebean-api
- 16.8.0
+ 16.9.0
io.ebean
ebean-core
- 16.8.0
+ 16.9.0
@@ -42,13 +42,13 @@
io.ebean
ebean-querybean
- 16.8.0
+ 16.9.0
io.ebean
ebean-platform-sqlserver
- 16.8.0
+ 16.9.0
diff --git a/composites/ebean-yugabyte/pom.xml b/composites/ebean-yugabyte/pom.xml
index 73b6d1672..61ca7d5a4 100644
--- a/composites/ebean-yugabyte/pom.xml
+++ b/composites/ebean-yugabyte/pom.xml
@@ -4,7 +4,7 @@
ebean-parent
io.ebean
- 16.8.0
+ 16.9.0
../..
@@ -17,13 +17,13 @@
io.ebean
ebean-api
- 16.8.0
+ 16.9.0
io.ebean
ebean-core
- 16.8.0
+ 16.9.0
@@ -42,13 +42,13 @@
io.ebean
ebean-querybean
- 16.8.0
+ 16.9.0
io.ebean
ebean-platform-postgres
- 16.8.0
+ 16.9.0
diff --git a/composites/ebean/pom.xml b/composites/ebean/pom.xml
index 44ef5c514..7a5155e48 100644
--- a/composites/ebean/pom.xml
+++ b/composites/ebean/pom.xml
@@ -4,7 +4,7 @@
ebean-parent
io.ebean
- 16.8.0
+ 16.9.0
../..
@@ -17,13 +17,13 @@
io.ebean
ebean-api
- 16.8.0
+ 16.9.0
io.ebean
ebean-core
- 16.8.0
+ 16.9.0
@@ -41,7 +41,7 @@
io.ebean
ebean-jackson-mapper
- 16.8.0
+ 16.9.0
@@ -60,13 +60,13 @@
io.ebean
ebean-querybean
- 16.8.0
+ 16.9.0
io.ebean
ebean-platform-all
- 16.8.0
+ 16.9.0
diff --git a/composites/pom.xml b/composites/pom.xml
index 794a9fbb0..a7c8cb817 100644
--- a/composites/pom.xml
+++ b/composites/pom.xml
@@ -4,7 +4,7 @@
ebean-parent
io.ebean
- 16.8.0
+ 16.9.0
composites
diff --git a/docs/guides/AGENTS.md b/docs/guides/AGENTS.md
index d926c678e..0fec50b33 100644
--- a/docs/guides/AGENTS.md
+++ b/docs/guides/AGENTS.md
@@ -14,6 +14,8 @@ Key guides (fetch and follow when performing the relevant task):
- Migrate to `Database.builder()`: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/migrating-to-database-builder.md
- Write queries with query beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/writing-ebean-query-beans.md
- Persisting and transactions: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/persisting-and-transactions-with-ebean.md
+- Query metrics and naming: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/ebean-query-metrics.md
+- Query plan capture: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/ebean-query-plan-capture.md
- Test container setup: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-test-container.md
- DB migration generation: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-db-migration-generation.md
- Lombok with entity beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/lombok-with-ebean-entity-beans.md
diff --git a/docs/guides/README.md b/docs/guides/README.md
index cf860d413..b85a87b7b 100644
--- a/docs/guides/README.md
+++ b/docs/guides/README.md
@@ -29,6 +29,8 @@ existing Maven project. Complete the steps in order.
| Guide | Description |
|-------|-------------|
| [Ebean OpenTelemetry tracing](add-ebean-opentelemetry.md) | Add `ebean-opentelemetry`, register `GlobalOpenTelemetry` once before Ebean databases are built, and troubleshoot missing spans or double-registration errors |
+| [Ebean query metrics and naming](ebean-query-metrics.md) | How Ebean query metric names are derived from `setLabel(..)` and profile locations; secondary (lazy/query) load naming; inline SQL comments; collecting metrics at runtime; mapping to avaje-metrics tags |
+| [Ebean query plan capture](ebean-query-plan-capture.md) | Enable and configure database query plan (`EXPLAIN`) capture for slow queries; bind capture vs plan capture; periodic and on-demand collection; thresholds, load limits, EXPLAIN dialect, and listeners |
## Entity beans
@@ -149,6 +151,8 @@ Key guides (fetch and follow these when performing the relevant task):
- Write queries with query beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/writing-ebean-query-beans.md
- Immutable bean cache for read-only references: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/immutable-bean-cache.md
- Ebean OpenTelemetry tracing: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-opentelemetry.md
+- Query metrics and naming: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/ebean-query-metrics.md
+- Query plan capture: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/ebean-query-plan-capture.md
- Persisting and transactions: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/persisting-and-transactions-with-ebean.md
- Test container setup: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-test-container.md
- DB migration generation: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-db-migration-generation.md
diff --git a/docs/guides/ebean-query-metrics.md b/docs/guides/ebean-query-metrics.md
new file mode 100644
index 000000000..c1fa4710e
--- /dev/null
+++ b/docs/guides/ebean-query-metrics.md
@@ -0,0 +1,258 @@
+# Guide: Ebean query metrics and naming
+
+## Purpose
+
+This guide explains the metrics Ebean captures, how the metric **name** for a query
+is derived, and how you influence that name with `setLabel(..)` and **profile
+locations**. It also covers secondary (lazy / query) load naming, the inline SQL
+comment, collecting metrics at runtime, and how the names map to avaje-metrics tags.
+
+Use this guide when you want to identify a query in metrics/telemetry, when a query
+shows up under an unexpected metric name, or when wiring Ebean metrics into a reporter.
+
+---
+
+## Overview
+
+Ebean records timing and counter metrics for the work it does. Every metric has a
+**name** whose leading segment identifies the kind of work:
+
+| Prefix | What it measures | Example name |
+|---|---|---|
+| `orm.` | Entity (ORM) query | `orm.Customer.findList`, `orm.CustomerFinder.byName` |
+| `dto.` | DTO query | `dto.CustomerDto_byEmail` |
+| `sql.query.` | Raw SQL query | `sql.query.