OpenTracing Cassandra Driver Instrumentation

OpenTracing instrumentation for Cassandra Driver.

Installation

pom.xml

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

Usage

// Instantiate tracer
Tracer tracer = ...

// Instantiate Cluster Builder
 Cluster.Builder builder = Cluster.builder().addContactPoints("127.0.0.1").withPort(9142);

// Instantiate Tracing Cluster
Cluster cluster = new TracingCluster(builder, tracer);

Span Names

By default, spans for executed queries will be created with the name execute. To use a different name for the query spans, you can create a custom name provider by implementing the QuerySpanNameProvider interface.

QuerySpanNameProvider interface

public interface QuerySpanNameProvider {
  public interface Builder {
    QuerySpanNameProvider build();
  }

  /**
   * Given a Cassandra query, return a name for the span
   * @param query Cassandra query
   * @return Name for query's span
   */
  String querySpanName(String query);

}

CustomStringSpanName

Returns a predefined string for every span. Defaults to execute on null or "" argument to build()

import io.opentracing.contrib.cassandra.QuerySpanNameProvider.CustomStringSpanName;
import io.opentracing.contrib.cassandra.QuerySpanNameProvider.QuerySpanNameProvider;
...

// Initialize with custom string
QuerySpanNameProvider querySpanNameProvider = CustomStringSpanName.newBuilder().build("CUSTOM_NAME");


// Instantiate Tracing Cluster with QuerySpanNameProvider as an argument
Tracer tracer = ...
Cluster.Builder builder = ...
Cluster cluster = new TracingCluster(builder, tracer, querySpanNameProvider);

Session session = cluster.newSession();

// Execute query
session.execute("SELECT * FROM example.table WHERE field = ?", "test");
// Span is created with span name 
// "CUSTOM_NAME"

FullQuerySpanName

Returns the full query as the span name.

import io.opentracing.contrib.cassandra.QuerySpanNameProvider.FullQuerySpanName;
import io.opentracing.contrib.cassandra.QuerySpanNameProvider.QuerySpanNameProvider;
...

// Initialize
QuerySpanNameProvider querySpanNameProvider = FullQuerySpanName.newBuilder().build();


// Instantiate Tracing Cluster with QuerySpanNameProvider as an argument
Tracer tracer = ...
Cluster.Builder builder = ...
Cluster cluster = new TracingCluster(builder, tracer, querySpanNameProvider);

Session session = cluster.newSession();

// Execute query
session.execute("SELECT * FROM example.table WHERE field = ?", "test");

// Span is created with the full query as the span name,
// "SELECT * FROM example.table WHERE field = ?;"

// Span name will be parameterized if the original given query is parameterized.

PrefixedFullQuerySpanName

Returns the full query as the span name, with a custom string prefix. Defaults to Cassandra on null or "" argument to build().

import io.opentracing.contrib.cassandra.QuerySpanNameProvider.PrefixedFullQuerySpanName;
import io.opentracing.contrib.cassandra.QuerySpanNameProvider.QuerySpanNameProvider;
...

// Initialize with custom prefix string
QuerySpanNameProvider querySpanNameProvider = PrefixedFullQuerySpanName.newBuilder().build("CUSTOM_PREFIX");


// Instantiate Tracing Cluster with QuerySpanNameProvider as an argument
Tracer tracer = ...
Cluster.Builder builder = ...
Cluster cluster = new TracingCluster(builder, tracer, querySpanNameProvider);


Session session = cluster.newSession();

// Execute query
session.execute("SELECT * FROM example.table WHERE field = ?", "test");

// Span is created with the full query as the span name, prefixed with the custom prefix, 
// "CUSTOM_PREFIX: SELECT * FROM example.table WHERE field = ?;"

// Span name will be parameterized if the original given query is parameterized.

QueryMethodTableSpanName

Returns formatted string Cassandra.[METHOD] - [TARGET_ENTITY] where [METHOD] is the Cassandra Method and [TARGET_ENTITY] is the entity that the method is acting on (view, keyspace, table, index).

For methods that require no target entity, returns Cassandra.[METHOD].

If a method does require a target entity, but none is found, returns Cassandra.[METHOD] - N/A.

The supported Cassandra methods are:

SELECT
INSERT
UPDATE
DELETE
BATCH
USE
CREATE MATERIALIZED VIEW
ALTER MATERIALIZED VIEW
DROP MATERIALIZED VIEW
CREATE KEYSPACE
ALTER KEYSPACE
DROP KEYSPACE
CREATE TABLE
ALTER TABLE
DROP TABLE
TRUNCATE
CREATE INDEX
DROP INDEX

import io.opentracing.contrib.cassandra.QuerySpanNameProvider.QueryMethodTableSpanName;
import io.opentracing.contrib.cassandra.QuerySpanNameProvider.QuerySpanNameProvider;
...

// Initialize
QuerySpanNameProvider querySpanNameProvider = QueryMethodTableSpanName.newBuilder().build();


// Instantiate Tracing Cluster with QuerySpanNameProvider as an argument
Tracer tracer = ...
Cluster.Builder builder = ...
Cluster cluster = new TracingCluster(builder, tracer, querySpanNameProvider);

Session session = cluster.newSession();

// Execute query
session.execute("SELECT * FROM example.table WHERE field = ?", "test");

// Span is created with the method and target entity in the name,
// "Cassandra.SELECT - example.table"

// Provider has support for additional qualifiers IF EXISTS and IF NOT EXISTS
session.execute("CREATE TABLE example.table;");
session.execute("CREATE TABLE IF NOT EXISTS example.table;")

// Two spans are created with the same name,
// "Cassandra.CREATE_TABLE - example.table"

garret-smith/java-cassandra-driver