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

@@ -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,10 +11,13 @@
 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 {
-  private static final String INSTRUMENTATION_NAME = "io.opentelemetry.javaagent.jdbc";
+  private static final String INSTRUMENTATION_NAME = "io.opentelemetry.jdbc";
 
   private static final Instrumenter<DbRequest, Void> INSTRUMENTER;
 

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,120 @@
+# 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 one requires
+to change the connection URL and switch to use a special OpenTelemetry driver. The second method
+only requires minimal changes in your application without needing to change the connection URL, but
+it's necessary to remove the explicit driver selection. And the third way is more preferable for DI frameworks
+which uses connection pools, as it wraps a `DataSource` with a special OpenTelemetry wrapper.
+
+### Driver: non-interceptor mode.
+
+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");
+```
+
+### Driver: interceptor mode.
+
+This mode can be useful for activating tracing for all JDBC connections without modifying the URL.
+
+In the "interceptor mode", the `OpenTelemetryDriver` will intercept calls to
+`DriverManager.getConnection(url,...)` for all URLs. The `OpenTelemetryDriver` will return instrumented
+connections that will delegate calls to the actual DB driver. Please note that the `OpenTelemetryDriver` must be
+registered before the underlying driver - it's recommended to turn on the "interceptor mode" as early as possible.
+
+For most applications:
+
+```java
+public static void main(String[] args) {
+  io.opentelemetry.instrumentation.jdbc.OpenTelemetryDriver.setInterceptorMode(true);
+
+  // ...
+}
+
+```
+
+For web applications based on Servlet API:
+
+```java
+public void contextInitialized(ServletContextEvent event) {
+  io.opentelemetry.instrumentation.jdbc.OpenTelemetryDriver.setInterceptorMode(true);
+
+  // ...
+}
+```
+
+Sometimes it's also required to register the OpenTelemetry driver as a first driver in the
+DriverManager list, otherwise another driver can be selected at the time of initialization.
+
+Calling `OpenTelemetryDriver.ensureRegisteredAsTheFirstDriver()` method along with
+`setInterceptorMode(true)` will fix that problem.
+
+Please note drivers like Oracle JDBC may fail since they're destroyed forever after deregistration.
+
+### 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);
+  }
+
+}
+```

instrumentation/jdbc/library/build.gradle

@@ -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')
+}