OpenTracing JDBC Instrumentation

OpenTracing instrumentation for JDBC.

Installation

pom.xml

<dependency>
    <groupId>io.opentracing.contrib</groupId>
    <artifactId>opentracing-jdbc</artifactId>
    <version>VERSION</version>
</dependency>

Usage

Non-interceptor

Tracing for JDBC connections of URLs starting with "jdbc:tracing:".

1. Activate tracing for JDBC connections by adding tracing to the JDBC url:

   jdbc:tracing:h2:mem:test

   To trace calls with active Spans only, set property traceWithActiveSpanOnly=true.

   jdbc:tracing:h2:mem:test?traceWithActiveSpanOnly=true

   To ignore specific queries (such as health checks), use the property ignoreForTracing="SELECT 1". Double quotes can be escaped with \.

   SELECT * FROM \"TEST\"
   ^{The property can be repeated for multiple statements.}

2. Set driver class to io.opentracing.contrib.jdbc.TracingDriver.

   Class.forName("io.opentracing.contrib.jdbc.TracingDriver");

   or

   io.opentracing.contrib.jdbc.TracingDriver.load();

3. Instantiate tracer and register it with GlobalTracer.

   // Instantiate tracer
   Tracer tracer = ...
   
   // Register tracer with GlobalTracer
   GlobalTracer.register(tracer);

Interceptor

Tracing for all JDBC connections without modifying the URL.

In "interceptor mode", the TracingDriver will intercept calls to DriverManager.getConnection(url,...) for all URLs. The TracingDriver provides connections to the DriverManager that are instrumented. Turn on "interceptor mode" via:

io.opentracing.contrib.jdbc.TracingDriver.setInterceptorMode(true);

The withActiveSpanOnly and ignoreStatements properties for "interceptor mode" can be configured with the TracingDriver via:

// Set withActiveSpanOnly=true
TracingDriver.setInterceptorProperty(true);

and

// Set ignoreStatements={"CREATE TABLE ignored (id INTEGER, TEST VARCHAR)"}
TracingDriver.setInterceptorProperty(Collections.singleton("CREATE TABLE ignored (id INTEGER, TEST VARCHAR)"));

Hibernate

<hibernate-configuration>
    <session-factory>
        <property name="hibernate.connection.driver_class">io.opentracing.contrib.jdbc.TracingDriver</property>
        <property name="hibernate.connection.url">jdbc:tracing:mysql://localhost:3306/test</property>
        ...
    </session-factory>
    ...
</hibernate-configuration>

JPA

<persistence-unit name="jpa">
    <properties>
        <property name="javax.persistence.jdbc.driver" value="io.opentracing.contrib.jdbc.TracingDriver"/>
        <property name="javax.persistence.jdbc.url" value="jdbc:tracing:mysql://localhost:3306/test"/>
        ...
    </properties>
</persistence-unit>

Spring

For dbcp2:

<bean id="dataSource" destroy-method="close" class="org.apache.commons.dbcp2.BasicDataSource">
    <property name="driverClassName" value="io.opentracing.contrib.jdbc.TracingDriver"/>
    <property name="url" value="jdbc:tracing:mysql://localhost:3306/test"/>
    ...
</bean>

Troubleshooting

In case of Unable to find a driver error the database driver should be registered before configuring the datasource. E.g. Class.forName("com.mysql.jdbc.Driver");

License

Apache 2.0 License.