Add a new artifact for gRPC utility classes for instrumentation. (#577)

* Add a new artifact for gRPC utility classes for instrumentation.

* Add code conversion and fix readme.

* Enable exporting to maven for grpc_util.

* Use Code for gRPC not CanonicalCode.

7 files changed, 311 insertions, 4 deletions

diff --git a/all/build.gradle b/all/build.gradle
index 22c02565..5b3a2eb1 100644
--- a/all/build.gradle
+++ b/all/build.gradle
@@ -22,6 +22,7 @@ def subprojects = [
         project(':opencensus-impl-lite'),
         project(':opencensus-testing'),
         project(':opencensus-contrib-agent'),
+        project(':opencensus-contrib-grpc-util'),
         project(':opencensus-contrib-zpages'),
         project(':opencensus-exporter-trace-logging'),
         project(':opencensus-exporter-trace-stackdriver'),
@@ -31,7 +32,7 @@ def subprojects = [
 def subprojects_javadoc = [
         project(':opencensus-api'),
         project(':opencensus-testing'),
-        project(':opencensus-contrib-agent'),
+        project(':opencensus-contrib-grpc-util'),
         project(':opencensus-contrib-zpages'),
         project(':opencensus-exporter-trace-logging'),
         project(':opencensus-exporter-trace-stackdriver'),
diff --git a/build.gradle b/build.gradle
index ff98f129..47aca7f1 100644
--- a/build.gradle
+++ b/build.gradle
@@ -104,7 +104,7 @@ subprojects {
     ext {
         autoValueVersion = '1.4'
         findBugsVersion = '3.0.1'
-        grpcContextVersion = '1.6.0'
+        grpcVersion = '1.6.1'
         guavaVersion = '19.0'
 
         libraries = [
@@ -114,9 +114,10 @@ subprojects {
                 disruptor: 'com.lmax:disruptor:3.3.6',
                 errorprone: 'com.google.errorprone:error_prone_annotations:2.0.19',
                 findbugs_annotations: "com.google.code.findbugs:annotations:${findBugsVersion}",
-                google_auth       : 'com.google.auth:google-auth-library-credentials:0.7.0',
+                google_auth: 'com.google.auth:google-auth-library-credentials:0.7.0',
                 google_cloud_trace: 'com.google.cloud:google-cloud-trace:0.22.0-alpha',
-                grpc_context: "io.grpc:grpc-context:${grpcContextVersion}",
+                grpc_context: "io.grpc:grpc-context:${grpcVersion}",
+                grpc_core: "io.grpc:grpc-core:${grpcVersion}",
                 guava: "com.google.guava:guava:${guavaVersion}",
                 jsr305: "com.google.code.findbugs:jsr305:${findBugsVersion}",
 
@@ -248,6 +249,7 @@ subprojects {
     uploadArchives.onlyIf {
         name in ['opencensus-api',
                  'opencensus-contrib-agent',
+                 'opencensus-contrib-grpc-util',
                  'opencensus-contrib-zpages',
                  'opencensus-exporter-trace-logging',
                  'opencensus-exporter-trace-stackdriver',
diff --git a/contrib/grpc_util/README.md b/contrib/grpc_util/README.md
new file mode 100644
index 00000000..8880ef28
--- /dev/null
+++ b/contrib/grpc_util/README.md
@@ -0,0 +1,33 @@
+# OpenCensus gRPC Util
+[![Build Status][travis-image]][travis-url] [![Build status][appveyor-image]][appveyor-url] [![Maven Central][maven-image]][maven-url]
+
+The *OpenCensus gRPC Util for Java* is a collection of utilities for trace instrumentation when 
+working with [gRPC][grpc-url].
+
+## Quickstart
+
+### Add the dependencies to your project
+
+For Maven add to your `pom.xml`:
+```xml
+<dependencies>
+  <dependency>
+    <groupId>io.opencensus</groupId>
+    <artifactId>opencensus-contrib-grpc-util</artifactId>
+    <version>0.6.0</version>
+  </dependency>
+</dependencies>
+```
+
+For Gradle add to your dependencies:
+```gradle
+compile 'io.opencensus:opencensus-contrib-grpc-util:0.6.0'
+```
+
+[travis-image]: https://travis-ci.org/census-instrumentation/opencensus-java.svg?branch=master
+[travis-url]: https://travis-ci.org/census-instrumentation/opencensus-java
+[appveyor-image]: https://ci.appveyor.com/api/projects/status/hxthmpkxar4jq4be/branch/master?svg=true
+[appveyor-url]: https://ci.appveyor.com/project/instrumentationjavateam/opencensus-java/branch/master
+[maven-image]: https://maven-badges.herokuapp.com/maven-central/io.opencensus/opencensus-contrib-grpc-util/badge.svg
+[maven-url]: https://maven-badges.herokuapp.com/maven-central/io.opencensus/opencensus-contrib-grpc-util
+[grpc-url]: https://github.com/grpc/grpc-java
diff --git a/contrib/grpc_util/build.gradle b/contrib/grpc_util/build.gradle
new file mode 100644
index 00000000..6241d750
--- /dev/null
+++ b/contrib/grpc_util/build.gradle
@@ -0,0 +1,15 @@
+description = 'OpenCensus gRPC Util'
+
+apply plugin: 'java'
+
+[compileJava, compileTestJava].each() {
+    it.sourceCompatibility = 1.6
+    it.targetCompatibility = 1.6
+}
+
+dependencies {
+    compile project(':opencensus-api'),
+            libraries.grpc_core
+
+    signature "org.codehaus.mojo.signature:java16:+@signature"
+}
diff --git a/contrib/grpc_util/src/main/java/io/opencensus/contrib/grpc/util/StatusConverter.java b/contrib/grpc_util/src/main/java/io/opencensus/contrib/grpc/util/StatusConverter.java
new file mode 100644
index 00000000..3bf91e3f
--- /dev/null
+++ b/contrib/grpc_util/src/main/java/io/opencensus/contrib/grpc/util/StatusConverter.java
@@ -0,0 +1,159 @@
+/*
+ * Copyright 2017, OpenCensus 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.
+ */
+
+package io.opencensus.contrib.grpc.util;
+
+/**
+ * Utility class to convert between {@link io.opencensus.trace.Status} and {@link io.grpc.Status}
+ */
+public final class StatusConverter {
+
+  /**
+   * Returns a {@link io.opencensus.trace.Status.CanonicalCode} from a {@link io.grpc.Status.Code}.
+   *
+   * @param grpcCode the given {@code io.grpc.Status.Code}.
+   * @return a {@code io.opencensus.trace.Status.CanonicalCode} from a {@code io.grpc.Status.Code}.
+   */
+  public static io.opencensus.trace.Status.CanonicalCode fromGrpcCode(
+      io.grpc.Status.Code grpcCode) {
+    return opencensusStatusFromGrpcCode(grpcCode).getCanonicalCode();
+  }
+
+  /**
+   * Returns a {@link io.opencensus.trace.Status} from a {@link io.grpc.Status}.
+   *
+   * @param grpcStatus the given {@code io.grpc.Status}.
+   * @return a {@code io.opencensus.trace.Status} from a {@code io.grpc.Status}.
+   */
+  public static io.opencensus.trace.Status fromGrpcStatus(io.grpc.Status grpcStatus) {
+    io.opencensus.trace.Status status = opencensusStatusFromGrpcCode(grpcStatus.getCode());
+    if (grpcStatus.getDescription() != null) {
+      status = status.withDescription(grpcStatus.getDescription());
+    }
+    return status;
+  }
+
+  /**
+   * Returns a {@link io.grpc.Status.Code} from a {@link io.opencensus.trace.Status.CanonicalCode}.
+   *
+   * @param opencensusCanonicalCode the given {@code io.opencensus.trace.Status.CanonicalCode}.
+   * @return a {@code io.grpc.Status.Code} from a {@code io.opencensus.trace.Status.CanonicalCode}.
+   */
+  public static io.grpc.Status.Code toGrpcCode(io.opencensus.trace.Status.CanonicalCode
+      opencensusCanonicalCode) {
+    return grpcStatusFromOpencensusCanonicalCode(opencensusCanonicalCode).getCode();
+  }
+
+  /**
+   * Returns a {@link io.grpc.Status} from a {@link io.opencensus.trace.Status}.
+   *
+   * @param opencensusStatus the given {@code io.opencensus.trace.Status}.
+   * @return a {@code io.grpc.Status} from a {@code io.opencensus.trace.Status}.
+   */
+  public static io.grpc.Status toGrpcStatus(io.opencensus.trace.Status opencensusStatus) {
+    io.grpc.Status status = grpcStatusFromOpencensusCanonicalCode(opencensusStatus
+        .getCanonicalCode());
+    if (opencensusStatus.getDescription() != null) {
+      status = status.withDescription(opencensusStatus.getDescription());
+    }
+    return status;
+  }
+
+  private static io.opencensus.trace.Status opencensusStatusFromGrpcCode(io.grpc.Status.Code
+      grpcCanonicaleCode) {
+    switch (grpcCanonicaleCode) {
+      case OK:
+        return io.opencensus.trace.Status.OK;
+      case CANCELLED:
+        return io.opencensus.trace.Status.CANCELLED;
+      case UNKNOWN:
+        return io.opencensus.trace.Status.UNKNOWN;
+      case INVALID_ARGUMENT:
+        return io.opencensus.trace.Status.INVALID_ARGUMENT;
+      case DEADLINE_EXCEEDED:
+        return io.opencensus.trace.Status.DEADLINE_EXCEEDED;
+      case NOT_FOUND:
+        return io.opencensus.trace.Status.NOT_FOUND;
+      case ALREADY_EXISTS:
+        return io.opencensus.trace.Status.ALREADY_EXISTS;
+      case PERMISSION_DENIED:
+        return io.opencensus.trace.Status.PERMISSION_DENIED;
+      case RESOURCE_EXHAUSTED:
+        return io.opencensus.trace.Status.RESOURCE_EXHAUSTED;
+      case FAILED_PRECONDITION:
+        return io.opencensus.trace.Status.FAILED_PRECONDITION;
+      case ABORTED:
+        return io.opencensus.trace.Status.ABORTED;
+      case OUT_OF_RANGE:
+        return io.opencensus.trace.Status.OUT_OF_RANGE;
+      case UNIMPLEMENTED:
+        return io.opencensus.trace.Status.UNIMPLEMENTED;
+      case INTERNAL:
+        return io.opencensus.trace.Status.INTERNAL;
+      case UNAVAILABLE:
+        return io.opencensus.trace.Status.UNAVAILABLE;
+      case DATA_LOSS:
+        return io.opencensus.trace.Status.DATA_LOSS;
+      case UNAUTHENTICATED:
+        return io.opencensus.trace.Status.UNAUTHENTICATED;
+    }
+    throw new AssertionError("Unhandled status code " + grpcCanonicaleCode);
+  }
+
+  private static io.grpc.Status grpcStatusFromOpencensusCanonicalCode(io.opencensus.trace.Status
+      .CanonicalCode opencensusCanonicalCode) {
+    switch (opencensusCanonicalCode) {
+      case OK:
+        return io.grpc.Status.OK;
+      case CANCELLED:
+        return io.grpc.Status.CANCELLED;
+      case UNKNOWN:
+        return io.grpc.Status.UNKNOWN;
+      case INVALID_ARGUMENT:
+        return io.grpc.Status.INVALID_ARGUMENT;
+      case DEADLINE_EXCEEDED:
+        return io.grpc.Status.DEADLINE_EXCEEDED;
+      case NOT_FOUND:
+        return io.grpc.Status.NOT_FOUND;
+      case ALREADY_EXISTS:
+        return io.grpc.Status.ALREADY_EXISTS;
+      case PERMISSION_DENIED:
+        return io.grpc.Status.PERMISSION_DENIED;
+      case RESOURCE_EXHAUSTED:
+        return io.grpc.Status.RESOURCE_EXHAUSTED;
+      case FAILED_PRECONDITION:
+        return io.grpc.Status.FAILED_PRECONDITION;
+      case ABORTED:
+        return io.grpc.Status.ABORTED;
+      case OUT_OF_RANGE:
+        return io.grpc.Status.OUT_OF_RANGE;
+      case UNIMPLEMENTED:
+        return io.grpc.Status.UNIMPLEMENTED;
+      case INTERNAL:
+        return io.grpc.Status.INTERNAL;
+      case UNAVAILABLE:
+        return io.grpc.Status.UNAVAILABLE;
+      case DATA_LOSS:
+        return io.grpc.Status.DATA_LOSS;
+      case UNAUTHENTICATED:
+        return io.grpc.Status.UNAUTHENTICATED;
+    }
+    throw new AssertionError("Unhandled status code " + opencensusCanonicalCode);
+  }
+
+  private StatusConverter() {
+  }
+}
diff --git a/contrib/grpc_util/src/test/java/io/opencensus/contrib/grpc/util/StatusConverterTest.java b/contrib/grpc_util/src/test/java/io/opencensus/contrib/grpc/util/StatusConverterTest.java
new file mode 100644
index 00000000..c62c5fa7
--- /dev/null
+++ b/contrib/grpc_util/src/test/java/io/opencensus/contrib/grpc/util/StatusConverterTest.java
@@ -0,0 +1,95 @@
+/*
+ * Copyright 2017, OpenCensus 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.
+ */
+
+package io.opencensus.contrib.grpc.util;
+
+import static com.google.common.truth.Truth.assertThat;
+
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/**
+ * Unit tests for {@link StatusConverter}.
+ */
+@RunWith(JUnit4.class)
+public class StatusConverterTest {
+
+  @Test
+  public void convertFromGrpcCode() {
+    for (io.grpc.Status.Code grpcCanonicalCode : io.grpc.Status.Code.values()) {
+      io.opencensus.trace.Status.CanonicalCode opencensusCanonicalCode = StatusConverter
+          .fromGrpcCode(grpcCanonicalCode);
+      assertThat(opencensusCanonicalCode.toString()).isEqualTo(grpcCanonicalCode.toString());
+    }
+  }
+
+  @Test
+  public void convertFromGrpcStatus() {
+    // Without description
+    for (io.grpc.Status.Code grpcCanonicalCode : io.grpc.Status.Code.values()) {
+      io.grpc.Status grpcStatus = io.grpc.Status.fromCode(grpcCanonicalCode);
+      io.opencensus.trace.Status opencensusStatus = StatusConverter.fromGrpcStatus(grpcStatus);
+      assertThat(opencensusStatus.getCanonicalCode().toString())
+          .isEqualTo(grpcStatus.getCode().toString());
+      assertThat(opencensusStatus.getDescription()).isNull();
+    }
+
+    // With description
+    for (io.grpc.Status.Code grpcCanonicalCode : io.grpc.Status.Code.values()) {
+      io.grpc.Status grpcStatus =
+          io.grpc.Status.fromCode(grpcCanonicalCode).withDescription("This is my description");
+      io.opencensus.trace.Status opencensusStatus = StatusConverter.fromGrpcStatus(grpcStatus);
+      assertThat(opencensusStatus.getCanonicalCode().toString())
+          .isEqualTo(grpcStatus.getCode().toString());
+      assertThat(opencensusStatus.getDescription()).isEqualTo(grpcStatus.getDescription());
+    }
+  }
+
+  @Test
+  public void convertToGrpcCode() {
+    for (io.opencensus.trace.Status.CanonicalCode opencensusCanonicalCode :
+        io.opencensus.trace.Status.CanonicalCode.values()) {
+      io.grpc.Status.Code grpcCanonicalCode = StatusConverter
+          .toGrpcCode(opencensusCanonicalCode);
+      assertThat(grpcCanonicalCode.toString()).isEqualTo(opencensusCanonicalCode.toString());
+    }
+  }
+
+  @Test
+  public void convertToGrpcStatus() {
+    // Without description
+    for (io.opencensus.trace.Status.CanonicalCode opencensusCanonicalCode :
+        io.opencensus.trace.Status.CanonicalCode.values()) {
+      io.opencensus.trace.Status opencensusStatus = opencensusCanonicalCode.toStatus();
+      io.grpc.Status grpcStatus = StatusConverter.toGrpcStatus(opencensusStatus);
+      assertThat(grpcStatus.getCode().toString())
+          .isEqualTo(opencensusStatus.getCanonicalCode().toString());
+      assertThat(grpcStatus.getDescription()).isNull();
+    }
+
+    // With description
+    for (io.opencensus.trace.Status.CanonicalCode opencensusCanonicalCode :
+        io.opencensus.trace.Status.CanonicalCode.values()) {
+      io.opencensus.trace.Status opencensusStatus =
+          opencensusCanonicalCode.toStatus().withDescription("This is my description");
+      io.grpc.Status grpcStatus = StatusConverter.toGrpcStatus(opencensusStatus);
+      assertThat(grpcStatus.getCode().toString())
+          .isEqualTo(opencensusStatus.getCanonicalCode().toString());
+      assertThat(grpcStatus.getDescription()).isEqualTo(opencensusStatus.getDescription());
+    }
+  }
+}
diff --git a/settings.gradle b/settings.gradle
index 72524f78..c3f164e3 100644
--- a/settings.gradle
+++ b/settings.gradle
@@ -12,6 +12,7 @@ include ":core_impl"
 include ":core_impl_java"
 include ":core_impl_android"
 include ":opencensus-contrib-agent"
+include ":opencensus-contrib-grpc-util"
 
 project(':opencensus-api').projectDir = "$rootDir/api" as File
 project(':opencensus-impl-core').projectDir = "$rootDir/impl_core" as File
@@ -19,6 +20,7 @@ project(':opencensus-impl-lite').projectDir = "$rootDir/impl_lite" as File
 project(':opencensus-impl').projectDir = "$rootDir/impl" as File
 project(':opencensus-testing').projectDir = "$rootDir/testing" as File
 project(':opencensus-contrib-agent').projectDir = "$rootDir/contrib/agent" as File
+project(':opencensus-contrib-grpc-util').projectDir = "$rootDir/contrib/grpc_util" as File
 project(':opencensus-exporter-trace-logging').projectDir = "$rootDir/exporters/trace_logging" as File
 project(':opencensus-exporter-trace-stackdriver').projectDir = "$rootDir/exporters/trace_stackdriver" as File