Database reference documentation (#4574)

* Database reference documentation

* Added jdbc observations section

docs/modules/ROOT/nav.adoc

@@ -37,6 +37,7 @@
 * xref:reference.adoc[Reference Instrumentations]
 ** xref:reference/cache.adoc[Cache]
 ** xref:reference/commons-pool.adoc[Apache Commons Pool]
+** xref:reference/db.adoc[Database]
 ** xref:reference/grpc.adoc[gRPC]
 ** xref:reference/httpcomponents.adoc[Apache HttpComponents Client]
 ** xref:reference/jetty.adoc[Jetty and Jersey]

docs/modules/ROOT/pages/reference/db.adoc

@@ -0,0 +1,53 @@
+[[overview]]
+= Database Instrumentation
+
+Micrometer can instrument various libraries that interact with databases
+
+* <<db-datasource-observation, DataSource Observation Instrumentation>>
+* <<db-datasource, DataSource Metrics Instrumentation>>
+* <<db-jooq, jOOQ Instrumentation>>
+* <<db-postgres, PostgreSQL Instrumentation>>
+
+[[db-datasource-observation]]
+== DataSource Observation Instrumentation
+
+Through the https://github.com/jdbc-observations/datasource-micrometer[Datasource Micrometer] project you can instrument your `Datasource` to start producing https://docs.micrometer.io/micrometer/reference/observation.html[Observations] while interacting with the database. That means that depending on your Observation Handler setup you can plug in producing of metrics or distributed tracing.
+
+You can read more about Datasource Micrometer https://jdbc-observations.github.io/datasource-micrometer/docs/current/docs/html/[reference documentation] here.
+
+[[db-datasource]]
+== DataSource Metrics Instrumentation
+
+[source,java,subs=+attributes]
+-----
+// Binding instrumentation through static method
+include::{include-core-test-java}/io/micrometer/core/instrument/binder/db/DatabaseTableMetricsTest.java[tags=monitor, indent=0]
+
+// Usage example
+include::{include-core-test-java}/io/micrometer/core/instrument/binder/db/DatabaseTableMetricsTest.java[tags=statement, indent=0]
+include::{include-core-test-java}/io/micrometer/core/instrument/binder/db/DatabaseTableMetricsTest.java[tags=result, indent=0]
+-----
+
+[[db-jooq]]
+== jOOQ Instrumentation
+
+[source,java,subs=+attributes]
+-----
+// Setting up instrumentation
+include::{include-core-test-java}/io/micrometer/core/instrument/binder/db/MetricsDSLContextTest.java[tags=setup, indent=0]
+
+// Usage example
+include::{include-core-test-java}/io/micrometer/core/instrument/binder/db/MetricsDSLContextTest.java[tags=result, indent=0]
+-----
+
+[[db-postgres]]
+== PostgresSQL Instrumentation
+
+[source,java,subs=+attributes]
+-----
+// Setting up instrumentation
+include::{include-core-test-java}/io/micrometer/core/instrument/binder/db/PostgreSQLDatabaseMetricsIntegrationTest.java[tags=setup, indent=0]
+
+// Usage example
+include::{include-core-test-java}/io/micrometer/core/instrument/binder/db/PostgreSQLDatabaseMetricsIntegrationTest.java[tags=result, indent=0]
+-----

micrometer-core/src/test/java/io/micrometer/core/instrument/binder/db/DatabaseTableMetricsTest.java

@@ -43,10 +43,12 @@ void setup() throws SQLException {
         ds = new JDBCDataSource();
         ds.setURL("jdbc:hsqldb:mem:test");
 
+        // tag::statement[]
         try (Connection conn = ds.getConnection()) {
             conn.prepareStatement("CREATE TABLE foo (id int)").execute();
             conn.prepareStatement("INSERT INTO foo VALUES (1)").executeUpdate();
         }
+        // end::statement[]
     }
 
     @AfterEach
@@ -58,8 +60,13 @@ void shutdown() throws SQLException {
 
     @Test
     void rowCountGauge() {
+        // tag::monitor[]
         DatabaseTableMetrics.monitor(registry, "foo", "mydb", ds);
+        // end::monitor[]
+
+        // tag::result[]
         assertThat(registry.get("db.table.size").tag("table", "foo").tag("db", "mydb").gauge().value()).isEqualTo(1.0);
+        // end::result[]
     }
 
     @Test

micrometer-core/src/test/java/io/micrometer/core/instrument/binder/db/MetricsDSLContextTest.java

@@ -105,9 +105,11 @@ void timeExecute() throws SQLException {
         try (Connection conn = DriverManager.getConnection("jdbc:h2:mem:fluentSelect")) {
             MetricsDSLContext jooq = createDatabase(conn);
 
+            // tag::result[]
             jooq.tag("name", "selectAllAuthors").execute("SELECT * FROM author");
 
             assertThat(meterRegistry.get("jooq.query").tag("name", "selectAllAuthors").timer().count()).isEqualTo(1);
+            // end::result[]
         }
     }
 
@@ -192,9 +194,11 @@ void userExecuteListenerShouldBePreserved() {
 
     @NonNull
     private MetricsDSLContext createDatabase(Connection conn) {
+        // tag::setup[]
         Configuration configuration = new DefaultConfiguration().set(conn).set(SQLDialect.H2);
 
-        MetricsDSLContext jooq = withMetrics(DSL.using(configuration), meterRegistry, Tags.empty());
+        MetricsDSLContext jooq = MetricsDSLContext.withMetrics(DSL.using(configuration), meterRegistry, Tags.empty());
+        // end::setup[]
 
         jooq.execute("CREATE TABLE author (" + "  id int NOT NULL," + "  first_name varchar(255) DEFAULT NULL,"
                 + "  last_name varchar(255) DEFAULT NULL," + "  PRIMARY KEY (id)" + ")");

micrometer-core/src/test/java/io/micrometer/core/instrument/binder/db/PostgreSQLDatabaseMetricsIntegrationTest.java

@@ -63,12 +63,15 @@ void setup() {
         dataSource = createDataSource();
         tags = Tags.of("database", postgres.getDatabaseName());
 
+        // tag::setup[]
         new PostgreSQLDatabaseMetrics(dataSource, postgres.getDatabaseName()).bindTo(registry);
+        // end::setup[]
     }
 
     @Test
     void gaugesAreNotZero() throws Exception {
         /* create noise to increment gauges */
+        // tag::result[]
         executeSql("CREATE TABLE gauge_test_table (val varchar(255))",
                 "INSERT INTO gauge_test_table (val) VALUES ('foo')", "UPDATE gauge_test_table SET val = 'bar'",
                 "SELECT * FROM gauge_test_table", "DELETE FROM gauge_test_table");
@@ -79,6 +82,7 @@ void gaugesAreNotZero() throws Exception {
         for (String name : GAUGES) {
             assertThat(get(name).gauge().value()).withFailMessage("Gauge " + name + " is zero.").isGreaterThan(0);
         }
+        // end::result[]
     }
 
     @Test