OpenTelemetry JDBC instrumentation library

docs/standalone-library-instrumentation.md

@@ -10,6 +10,7 @@ that can be used if you prefer that over using the Java agent:
 * [AWS SDK 2.2+](../instrumentation/aws-sdk/aws-sdk-2.2/library)
 * [gRPC](../instrumentation/grpc-1.6/library)
 * [Guava](../instrumentation/guava-10.0/library)
+* [JDBC](../instrumentation/jdbc/library)
 * [Lettuce](../instrumentation/lettuce/lettuce-5.1/library)
 * [Log4j](../instrumentation/log4j/log4j-2.13.2/library)
 * [Logback](../instrumentation/logback-1.0/library)

instrumentation/jdbc/javaagent/build.gradle.kts

@@ -9,6 +9,7 @@ muzzle {
 }
 
 dependencies {
+  implementation(project(":instrumentation:jdbc:library"))
 
   compileOnly("com.google.auto.value:auto-value-annotations")
   annotationProcessor("com.google.auto.value:auto-value")
@@ -26,6 +27,8 @@ dependencies {
   testLibrary("com.mchange:c3p0:0.9.5")
 
   latestDepTestLibrary("org.apache.derby:derby:10.14.+")
+
+  testImplementation(project(":instrumentation:jdbc:testing"))
 }
 
 tasks.withType<Test>().configureEach {

instrumentation/jdbc/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jdbc/ConnectionInstrumentation.java

@@ -12,6 +12,7 @@
 import static net.bytebuddy.matcher.ElementMatchers.returns;
 import static net.bytebuddy.matcher.ElementMatchers.takesArgument;
 
+import io.opentelemetry.instrumentation.jdbc.internal.JdbcMaps;
 import io.opentelemetry.javaagent.extension.instrumentation.TypeInstrumentation;
 import io.opentelemetry.javaagent.extension.instrumentation.TypeTransformer;
 import java.sql.PreparedStatement;

instrumentation/jdbc/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jdbc/DriverInstrumentation.java

@@ -12,6 +12,9 @@
 import static net.bytebuddy.matcher.ElementMatchers.returns;
 import static net.bytebuddy.matcher.ElementMatchers.takesArgument;
 
+import io.opentelemetry.instrumentation.jdbc.internal.DbInfo;
+import io.opentelemetry.instrumentation.jdbc.internal.JdbcConnectionUrlParser;
+import io.opentelemetry.instrumentation.jdbc.internal.JdbcMaps;
 import io.opentelemetry.javaagent.extension.instrumentation.TypeInstrumentation;
 import io.opentelemetry.javaagent.extension.instrumentation.TypeTransformer;
 import java.sql.Connection;

instrumentation/jdbc/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jdbc/JdbcSingletons.java

@@ -11,6 +11,9 @@
 import io.opentelemetry.instrumentation.api.instrumenter.SpanNameExtractor;
 import io.opentelemetry.instrumentation.api.instrumenter.db.DbAttributesExtractor;
 import io.opentelemetry.instrumentation.api.instrumenter.db.DbSpanNameExtractor;
+import io.opentelemetry.instrumentation.jdbc.internal.DbRequest;
+import io.opentelemetry.instrumentation.jdbc.internal.JdbcAttributesExtractor;
+import io.opentelemetry.instrumentation.jdbc.internal.JdbcNetAttributesExtractor;
 import io.opentelemetry.javaagent.instrumentation.api.instrumenter.PeerServiceAttributesExtractor;
 
 public final class JdbcSingletons {

instrumentation/jdbc/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jdbc/PreparedStatementInstrumentation.java

@@ -16,6 +16,7 @@
 
 import io.opentelemetry.context.Context;
 import io.opentelemetry.context.Scope;
+import io.opentelemetry.instrumentation.jdbc.internal.DbRequest;
 import io.opentelemetry.javaagent.extension.instrumentation.TypeInstrumentation;
 import io.opentelemetry.javaagent.extension.instrumentation.TypeTransformer;
 import io.opentelemetry.javaagent.instrumentation.api.CallDepthThreadLocalMap;

instrumentation/jdbc/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jdbc/StatementInstrumentation.java

@@ -16,6 +16,7 @@
 
 import io.opentelemetry.context.Context;
 import io.opentelemetry.context.Scope;
+import io.opentelemetry.instrumentation.jdbc.internal.DbRequest;
 import io.opentelemetry.javaagent.extension.instrumentation.TypeInstrumentation;
 import io.opentelemetry.javaagent.extension.instrumentation.TypeTransformer;
 import io.opentelemetry.javaagent.instrumentation.api.CallDepthThreadLocalMap;

instrumentation/jdbc/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jdbc/datasource/DataSourceInstrumentation.java

@@ -5,8 +5,8 @@
 
 package io.opentelemetry.javaagent.instrumentation.jdbc.datasource;
 
+import static io.opentelemetry.instrumentation.jdbc.internal.DataSourceSingletons.instrumenter;
 import static io.opentelemetry.javaagent.extension.matcher.AgentElementMatchers.implementsInterface;
-import static io.opentelemetry.javaagent.instrumentation.jdbc.datasource.DataSourceSingletons.instrumenter;
 import static net.bytebuddy.matcher.ElementMatchers.named;
 
 import io.opentelemetry.context.Context;

instrumentation/jdbc/javaagent/src/test/groovy/JdbcInstrumentationTest.groovy

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import io.opentelemetry.instrumentation.jdbc.TestConnection
+import io.opentelemetry.instrumentation.jdbc.TestDriver
+
 import static io.opentelemetry.api.trace.SpanKind.CLIENT
 import static io.opentelemetry.api.trace.SpanKind.INTERNAL
 import static io.opentelemetry.instrumentation.test.utils.TraceUtils.basicSpan
@@ -28,8 +31,6 @@ import org.h2.jdbcx.JdbcDataSource
 import org.hsqldb.jdbc.JDBCDriver
 import spock.lang.Shared
 import spock.lang.Unroll
-import test.TestConnection
-import test.TestDriver
 
 @Unroll
 class JdbcInstrumentationTest extends AgentInstrumentationSpecification {
@@ -466,6 +467,7 @@ class JdbcInstrumentationTest extends AgentInstrumentationSpecification {
     when:
     try {
       connection = new TestConnection(true)
+      connection.url = "jdbc:testdb://localhost"
     } catch (Exception ignored) {
       connection = driver.connect(jdbcUrl, null)
     }
@@ -580,6 +582,7 @@ class JdbcInstrumentationTest extends AgentInstrumentationSpecification {
   def "test getClientInfo exception"() {
     setup:
     Connection connection = new TestConnection(false)
+    connection.url = "jdbc:testdb://localhost"
 
     when:
     Statement statement = null
@@ -720,6 +723,7 @@ class JdbcInstrumentationTest extends AgentInstrumentationSpecification {
   def "should handle recursive Statements inside Connection.getMetaData(): #desc"() {
     given:
     def connection = new DbCallingConnection(usePreparedStatementInConnection)
+    connection.url = "jdbc:testdb://localhost"
 
     when:
     runUnderTrace("parent") {

instrumentation/jdbc/library/NOTICE.txt

@@ -0,0 +1,19 @@
+This product contains a modified part of OpenTracing JDBC Instrumentation:
+
+  * License:
+
+ Copyright 2017-2021 The OpenTracing 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
+
+      https://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.
+
+  * Homepage: https://github.com/opentracing-contrib/java-jdbc

instrumentation/jdbc/library/README.md

@@ -0,0 +1,78 @@
+# Manual Instrumentation for JDBC
+
+Provides OpenTelemetry instrumentation for
+[Java JDBC API](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/).
+
+## Quickstart
+
+### Add these dependencies to your project.
+
+Replace `OPENTELEMETRY_VERSION` with the latest stable
+[release](https://mvnrepository.com/artifact/io.opentelemetry). `Minimum version: 1.4.0`
+
+For Maven add to your `pom.xml`:
+
+```xml
+<dependencies>
+  <dependency>
+    <groupId>io.opentelemetry.instrumentation</groupId>
+    <artifactId>opentelemetry-jdbc</artifactId>
+    <version>OPENTELEMETRY_VERSION</version>
+  </dependency>
+</dependencies>
+```
+
+For Gradle add to your dependencies:
+
+```groovy
+implementation("io.opentelemetry.instrumentation:opentelemetry-jdbc:OPENTELEMETRY_VERSION")
+```
+
+##### Usage
+
+There are three possible ways to activate the OpenTelemetry JDBC instrumentation. The first way is more preferable for
+DI frameworks which uses connection pools, as it wraps a `DataSource` with a special OpenTelemetry wrapper. The second
+one requires to change the connection URL and switch to use a special OpenTelemetry driver.
+
+### Datasource way
+
+If your application uses a DataSource, simply wrap your current DataSource object with `OpenTelemetryDataSource`.
+`OpenTelemetryDataSource` has a constructor method that accepts the `DataSource` to wrap. This is by far the simplest
+method especially if you use a dependency injection (DI) frameworks such as
+[Spring Framework](https://spring.io/projects/spring-framework), [Micronaut](https://micronaut.io),
+[Quarkus](https://quarkus.io), or [Guice](https://github.com/google/guice).
+
+```java
+import org.apache.commons.dbcp2.BasicDataSource;
+import org.springframework.context.annotation.Configuration;
+import io.opentelemetry.instrumentation.jdbc.datasource.OpenTelemetryDataSource;
+
+@Configuration
+public class DataSourceConfig {
+
+  @Bean
+  public DataSource dataSource() {
+    BasicDataSource dataSource = new BasicDataSource();
+    dataSource.setDriverClassName("org.postgresql.Driver");
+    dataSource.setUrl("jdbc:postgresql://127.0.0.1:5432/example");
+    dataSource.setUsername("postgres");
+    dataSource.setPassword("root");
+    return new OpenTelemetryDataSource(dataSource);
+  }
+
+}
+```
+
+### Driver way
+
+1. Activate tracing for JDBC connections by setting `jdbc:otel:` prefix to the JDBC URL:
+
+```
+jdbc:otel:h2:mem:test
+```
+
+2. Set the driver class to `io.opentelemetry.instrumentation.jdbc.OpenTelemetryDriver` and initialize the driver with:
+
+```java
+Class.forName("io.opentelemetry.instrumentation.jdbc.OpenTelemetryDriver");
+```

instrumentation/jdbc/library/build.gradle.kts

@@ -0,0 +1,19 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+plugins {
+  id("otel.library-instrumentation")
+}
+
+dependencies {
+  implementation(project(":instrumentation-api"))
+
+  compileOnly("com.google.auto.value:auto-value-annotations")
+  annotationProcessor("com.google.auto.value:auto-value")
+
+  implementation("org.slf4j:slf4j-api")
+
+  testImplementation(project(":instrumentation:jdbc:testing"))
+}