Adds Cassandra client and server integration

This contains tracing instrumentation for [Cassandra](https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/tracing/Tracing.java) and the [DataStax Java Driver](https://github.com/datastax/java-driver).

`brave.cassandra.Tracing` extracts trace state from the custom payload
of incoming requests. How long each request takes, each suboperation,
and relevant tags like the session ID are reported to Zipkin.

`brave.cassandra.driver.TracingSession` tracks the client-side of cassandra and
adds trace context to the custom payload of outgoing requests. If
server integration is in place, cassandra will contribute data to these
RPC spans.

Closes openzipkin/brave#414

.gitignore

@@ -1,22 +1,22 @@
-# Compiled class file
 *.class
 
-# Log file
-*.log
-
-# BlueJ files
-*.ctxt
-
 # Mobile Tools for Java (J2ME)
 .mtj.tmp/
 
 # Package Files #
 *.jar
 *.war
 *.ear
-*.zip
-*.tar.gz
-*.rar
 
 # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
 hs_err_pid*
+
+# Maven
+target/
+
+# IntelliJ
+.idea/
+*.iml
+
+# macOS
+.DS_Store

.mvn/wrapper/maven-wrapper.properties

@@ -0,0 +1 @@
+distributionUrl=https://repo1.maven.org/maven2/org/apache/maven/apache-maven/3.5.0/apache-maven-3.5.0-bin.zip

CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing to Zipkin
+
+If you would like to contribute code you can do so through GitHub by forking the repository and sending a pull request (on a branch other than `master` or `gh-pages`).
+
+When submitting code, please apply [Square Code Style](https://github.com/square/java-code-styles).
+* If the settings import correctly, CodeStyle/Java will be named Square and use 2 space tab and indent, with 4 space continuation indent.
+
+## License
+
+By contributing your code, you agree to license your contribution under the terms of the APLv2: https://github.com/openzipkin/zipkin/blob/master/LICENSE
+
+All files are released with the Apache 2.0 license.
+
+If you are adding a new file it should have a header like below. This can be automatically added by running `./mvnw com.mycila:license-maven-plugin:format`.
+
+```
+/**
+ * Copyright 2017 The OpenZipkin 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
+ *
+ * http://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.
+ */
+ ```

README.md

@@ -1,2 +1,15 @@
+[![Gitter chat](http://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg)](https://gitter.im/openzipkin/zipkin)
+[![Build Status](https://circleci.com/gh/openzipkin/brave-cassandra.svg?style=svg)](https://circleci.com/gh/openzipkin/brave-cassandra)
+[![Download](https://api.bintray.com/packages/openzipkin/maven/brave-cassandra/images/download.svg)](https://bintray.com/openzipkin/maven/brave-cassandra/_latestVersion)
+
 # brave-cassandra
-Tracing instrumentation for Cassandra and the DataStax Java Driver
+This contains tracing instrumentation for [Cassandra](https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/tracing/Tracing.java) and the [DataStax Java Driver](https://github.com/datastax/java-driver).
+
+`brave.cassandra.Tracing` extracts trace state from the custom payload
+of incoming requests. How long each request takes, each suboperation,
+and relevant tags like the session ID are reported to Zipkin.
+
+`brave.cassandra.driver.TracingSession` tracks the client-side of cassandra and
+adds trace context to the custom payload of outgoing requests. If
+server integration is in place, cassandra will contribute data to these
+RPC spans.

RELEASE.md

@@ -0,0 +1,41 @@
+# Brave Cassandra Release Process
+
+This repo uses semantic versions. Please keep this in mind when choosing version numbers.
+
+1. **Alert others you are releasing**
+
+   There should be no commits made to master while the release is in progress (about 10 minutes). Before you start
+   a release, alert others on [gitter](https://gitter.im/openzipkin/zipkin) so that they don't accidentally merge
+   anything. If they do, and the build fails because of that, you'll have to recreate the release tag described below.
+
+1. **Push a git tag**
+
+   The tag should be of the format `release-N.M.L`, for example `release-3.7.1`.
+
+1. **Wait for CircleCI**
+
+   This part is controlled by [`build-support/publish-stable.sh`](build-support/publish-stable.sh). It creates a bunch of new commits, bumps
+   the version, publishes artifacts, and syncs to Maven Central. https://circleci.com/gh/openzipkin/brave-cassandra
+
+## Credentials
+
+Credentials of various kind are needed for the release process to work. If you notice something
+failing due to unauthorized, re-save them as [environment variables](https://circleci.com/gh/openzipkin/brave-cassandra/edit#env-vars).
+
+## First release of the year
+
+The license plugin verifies license headers of files include a copyright notice indicating the years a file was affected.
+This information is taken from git history. There's a once-a-year problem with files that include version numbers (pom.xml).
+When a release tag is made, it increments version numbers, then commits them to git. On the first release of the year,
+further commands will fail due to the version increments invalidating the copyright statement. The way to sort this out is
+the following:
+
+Before you do the first release of the year, move the SNAPSHOT version back and forth from whatever the current is.
+In-between, re-apply the licenses.
+```bash
+$ ./mvnw versions:set -DnewVersion=1.3.3-SNAPSHOT -DgenerateBackupPoms=false
+$ ./mvnw com.mycila:license-maven-plugin:format
+$ ./mvnw versions:set -DnewVersion=1.3.2-SNAPSHOT -DgenerateBackupPoms=false
+$ git commit -am"Adjusts copyright headers for this year"
+```
+

build-support/go-offline.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+#
+# Copyright 2017 The OpenZipkin 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
+#
+# http://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.
+#
+
+# Due to https://issues.apache.org/jira/browse/MDEP-323 and cross-module dependencies,
+# we can't easily run mvn dependency:go-offline. This is a workaround for that.
+# It removes all dependencies on io.zipkin.java and ${project.groupId} using XSLT,
+# then runs go-offline on the resulting POMs.
+
+set -xeuo pipefail
+
+rm -rf go-offline-builddir
+mkdir -p go-offline-builddir
+trap "rm -rf $(pwd)/go-offline-builddir" EXIT
+
+for f in $(find . -name 'pom.xml'); do
+    echo $f
+    mkdir -p $(dirname go-offline-builddir/$f)
+    xsltproc ./build-support/pom-no-crossmodule-dependencies.xsl $f > go-offline-builddir/$f
+done
+
+cd go-offline-builddir
+../mvnw dependency:go-offline

build-support/pom-no-crossmodule-dependencies.xsl

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright 2017 The OpenZipkin 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
+
+    http://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.
+
+-->
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:pom="http://maven.apache.org/POM/4.0.0">
+  <xsl:template match="@*|node()">
+    <xsl:copy>
+      <xsl:apply-templates select="@*|node()"/>
+    </xsl:copy>
+  </xsl:template>
+
+  <xsl:template match="pom:dependency[pom:groupId = 'io.zipkin.aws']" />
+  <xsl:template match="pom:dependency[pom:groupId = '${project.groupId}']" />
+</xsl:stylesheet>

build-support/publish-snapshot.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+#
+# Copyright 2017 The OpenZipkin 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
+#
+# http://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.
+#
+
+set -euo pipefail
+set -x
+
+if ./mvnw help:evaluate -N -Dexpression=project.version | grep -v '\['  | grep -q SNAPSHOT; then
+    ./mvnw --batch-mode -s ./.settings.xml -Prelease -nsu -DskipTests deploy
+else
+    echo "Not building release versions, those are built by the tag builder using the publish-stable.sh script"
+fi

build-support/publish-stable.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+#
+# Copyright 2017 The OpenZipkin 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
+#
+# http://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.
+#
+
+set -euo pipefail
+set -x
+
+./mvnw -DskipTests install -nsu
+./mvnw --batch-mode -s ./.settings.xml -Prelease -nsu -DskipTests deploy
+./mvnw --batch-mode -s ./.settings.xml -nsu -N io.zipkin.centralsync-maven-plugin:centralsync-maven-plugin:sync

build-support/trigger-publish.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+#
+# Copyright 2017 The OpenZipkin 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
+#
+# http://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.
+#
+
+set -euo pipefail
+set -x
+
+release_version() {
+    echo "${CIRCLE_TAG}" | sed 's/^release-//'
+}
+
+safe_checkout_master() {
+  # We need to be on a branch for release:perform to be able to create commits, and we want that branch to be master.
+  # But we also want to make sure that we build and release exactly the tagged version, so we verify that the remote
+  # master is where our tag is.
+  git checkout -B master
+  git fetch origin master:origin/master
+  commit_local_master="$(git show --pretty='format:%H' master)"
+  commit_remote_master="$(git show --pretty='format:%H' origin/master)"
+  if [ "$commit_local_master" != "$commit_remote_master" ]; then
+    echo "Master on remote 'origin' has commits since the version under release, aborting"
+    exit 1
+  fi
+}
+
+safe_checkout_master
+./mvnw --batch-mode -s ./.settings.xml -Prelease -nsu -DreleaseVersion="$(release_version)" -Darguments="-DskipTests" release:prepare

cassandra-driver/README.md

@@ -0,0 +1,61 @@
+# brave-instrumentation-cassandra-driver
+This contains tracing instrumentation for the [DataStax Java Driver](https://github.com/datastax/java-driver).
+
+`brave.cassandra.driver.TracingSession` tracks the client-side of cassandra
+and adds trace context to the custom payload of outgoing requests. If
+[server integration](../cassandra) is in place, cassandra will contribute
+data to these RPC spans.
+
+To set this up, wrap your session like below
+```java
+session = TracingSession.create(tracing, realSession);
+```
+
+
+## Tagging policy
+By default, the following are added to cassandra client spans:
+* Span.name as the simple type-name of the statement: ex "bound-statement"
+* Tags/binary annotations:
+  * "cassandra.keyspace"
+  * "cassandra.query" CQL of prepared statements
+  * "error" when there is an error of any kind
+* Remote IP and port information
+
+To change the span and tag naming policy, you can do something like this:
+
+```java
+cassandraClientTracing = cassandraClientTracing.toBuilder()
+    .parser(new CassandraClientParser() {
+        @Override public String spanName(Statement statement) {
+          return "query";
+        }
+
+        @Override public void requestTags(Statement statement, SpanCustomizer customizer) {
+          super.requestTags(statement, tagger);
+          customizer.tag("cassandra.fetch_size", Integer.toString(statement.getFetchSize()));
+        }
+    })
+    .build();
+
+tracesSession = TracingSession.create(cassandraClientTracing.clientOf("remote-cluster"), session);
+```
+
+## Sampling Policy
+The default sampling policy is to use the default (trace ID) sampler.
+
+For example, if there's no trace already in progress, the sampler
+indicated by `Tracing.Builder.sampler` decides whether or not to start a
+new trace for the cassandra client request.
+
+You can change the sampling policy by specifying it in the `CassandraClientTracing`
+component. Here's an example which only starts new traces for bound statements.
+
+```java
+cassandraClientTracing = cassandraClientTracing.toBuilder()
+    .sampler(new CassandraClientSampler() {
+       @Override public Boolean trySample(Statement statement) {
+         return statement instanceof BoundStatement;
+       }
+     })
+    .build();
+```

cassandra-driver/pom.xml

@@ -0,0 +1,47 @@
+<?xml version="1.0"?>
+<!--
+
+    Copyright 2017 The OpenZipkin 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
+
+    http://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.
+
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <parent>
+    <groupId>io.zipkin.brave.cassandra</groupId>
+    <artifactId>brave-cassandra-parent</artifactId>
+    <version>0.0.1-SNAPSHOT</version>
+  </parent>
+  <modelVersion>4.0.0</modelVersion>
+
+  <artifactId>brave-instrumentation-cassandra-driver</artifactId>
+  <name>Brave Instrumentation: DataStax Java Driver for Apache Cassandra</name>
+
+  <properties>
+    <main.basedir>${project.basedir}/..</main.basedir>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>com.datastax.cassandra</groupId>
+      <artifactId>cassandra-driver-core</artifactId>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>${project.groupId}</groupId>
+      <artifactId>brave-instrumentation-cassandra-tests</artifactId>
+      <version>${project.version}</version>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+</project>