isabella232 / java-cassandra-driver

OpenTracing instrumentation for Cassandra Driver

OpenTracing Cassandra Driver Instrumentation

OpenTracing instrumentation for Cassandra Driver.

Installation

Cassandra 3

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

Cassandra 4

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

Usage

// Instantiate tracer
Tracer tracer = ...

Cassandra 3

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

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

Cassandra 4

// Instantiate CqlSession:
CqlSession session = CqlSession.builder().build()

// Decorate CqlSession with TracingCqlSession:
CqlSession tracingSession = new TracingCqlSession(session, tracer);

// execute query with TracingCqlSession:
tracingSession.execute("...");

Span Names for Cassandra 3

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"

License

Apache 2.0 License.