JarCasting
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:".
-
Activate tracing for JDBC connections by adding
tracingto the JDBC url:jdbc:tracing:h2:mem:test
To trace calls with active
Spans only, set propertytraceWithActiveSpanOnly=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. -
Set driver class to
io.opentracing.contrib.jdbc.TracingDriver.Class.forName("io.opentracing.contrib.jdbc.TracingDriver");
or
io.opentracing.contrib.jdbc.TracingDriver.load();
-
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. Please note that the TracingDriver must be registered before the underlying driver, It's recommended to turn on "interceptor mode" in the first place.
For standalone applications:
public static void main(String[] args) {
io.opentracing.contrib.jdbc.TracingDriver.setInterceptorMode(true);
// some jdbc operation here
}
For web applications:
public void contextInitialized(ServletContextEvent event) {
io.opentracing.contrib.jdbc.TracingDriver.setInterceptorMode(true);
}
Or call TracingDriver.ensureRegisteredAsTheFirstDriver() along with TracingDriver.setInterceptorMode(true) at any place, Please note driver like Oracle JDBC may fail since it's destroyed forever after deregistration.
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>
Spring Boot 2
For Hikari (Postgresl):
### Spring JPA Datasource Connection
spring.datasource.username=postgres
spring.datasource.password=XXXXX
spring.datasource.hikari.driverClassName=io.opentracing.contrib.jdbc.TracingDriver
spring.datasource.hikari.jdbcUrl=jdbc:tracing:postgresql://localhost:5432/my_app_db
Configuration Bean:
@Component
public class OpenTracingConfig {
@Bean
public io.opentracing.Tracer jaegerTracer() {
io.opentracing.contrib.jdbc.TracingDriver.load();
return new Configuration("my_app").getTracer();
}
}
Slow Query
Span is marked by tag slow=true if duration exceed slowQueryThresholdMs. slowQueryThresholdMs defaults to 0 which means disabled, can be enabled in two ways:
- Passing system property, E.g.
-Dio.opentracing.contrib.jdbc.slowQueryThresholdMs=100 - Modify value by code, E.g.
io.opentracing.contrib.jdbc.JdbcTracing.setSlowQueryThresholdMs(100)
Fast Query
Spans that complete faster than the optional excludeFastQueryThresholdMs flag will be not be reported. excludeFastQueryThresholdMs defaults to 0 which means disabled, can be enabled in two ways:
- Passing system property, E.g.
-Dio.opentracing.contrib.jdbc.excludeFastQueryThresholdMs=100 - Modify value by code, E.g.
io.opentracing.contrib.jdbc.JdbcTracing.setExcludeFastQueryThresholdMs(100)
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");
