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.