diff options
14 files changed, 505 insertions, 1 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md index 4e4d3af9..b3fa3020 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,13 +1,14 @@ ## Unreleased - Add `AttributeValueDouble` to `AttributeValue`. - Add `createWithSender` to `JaegerTraceExporter` to allow use of `HttpSender` - with extra configurations + with extra configurations. - Add an API `Functions.returnToString()`. - Add `opencensus-contrib-opencensus-proto-util` that has helper utilities to convert between Java data models and protos. - Migrate to new Stackdriver Kubernetes monitored resource. This could be a breaking change if you are using `gke_container` resources. For more info, https://cloud.google.com/monitoring/kubernetes-engine/migration#incompatible +- Add OpenCensus Java OC-Agent Trace Exporter. ## 0.16.1 - 2018-09-18 - Fix ClassCastException in Log4j log correlation diff --git a/RELEASING.md b/RELEASING.md index 669fc8fa..2b4aa512 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -220,6 +220,7 @@ $ README_FILES=( exporters/trace/instana/README.md exporters/trace/logging/README.md exporters/trace/jaeger/README.md + exporters/trace/ocagent/README.md exporters/trace/stackdriver/README.md exporters/trace/zipkin/README.md ) diff --git a/all/build.gradle b/all/build.gradle index 072459d1..66e6a893 100644 --- a/all/build.gradle +++ b/all/build.gradle @@ -20,6 +20,7 @@ def subprojects = [ project(':opencensus-contrib-spring-sleuth-v1x'), project(':opencensus-contrib-zpages'), project(':opencensus-exporter-trace-logging'), + project(':opencensus-exporter-trace-ocagent'), project(':opencensus-exporter-trace-stackdriver'), project(':opencensus-exporter-trace-zipkin'), project(':opencensus-exporter-trace-jaeger'), @@ -46,6 +47,7 @@ def subprojects_javadoc = [ project(':opencensus-contrib-spring-sleuth-v1x'), project(':opencensus-contrib-zpages'), project(':opencensus-exporter-trace-logging'), + project(':opencensus-exporter-trace-ocagent'), project(':opencensus-exporter-trace-stackdriver'), project(':opencensus-exporter-trace-zipkin'), project(':opencensus-exporter-trace-jaeger'), diff --git a/build.gradle b/build.gradle index 7754eba1..e3bcb688 100644 --- a/build.gradle +++ b/build.gradle @@ -432,6 +432,7 @@ subprojects { 'opencensus-exporter-stats-stackdriver', 'opencensus-exporter-trace-instana', 'opencensus-exporter-trace-logging', + 'opencensus-exporter-trace-ocagent', 'opencensus-exporter-trace-stackdriver', 'opencensus-exporter-trace-zipkin', 'opencensus-exporter-trace-jaeger', diff --git a/buildscripts/import-control.xml b/buildscripts/import-control.xml index 69a3de8e..2467e35c 100644 --- a/buildscripts/import-control.xml +++ b/buildscripts/import-control.xml @@ -174,6 +174,10 @@ General guidelines on imports: <allow pkg="io.opencensus.exporter.trace.jaeger"/> <allow pkg="org.apache.thrift"/> </subpackage> + <subpackage name="ocagent"> + <allow pkg="io.opencensus.exporter.trace.ocagent"/> + <allow pkg="io.opencensus.proto"/> + </subpackage> <subpackage name="stackdriver"> <allow pkg="com.google"/> <allow pkg="io.opencensus.exporter.trace.stackdriver"/> diff --git a/exporters/trace/ocagent/README.md b/exporters/trace/ocagent/README.md new file mode 100644 index 00000000..4f25bd6e --- /dev/null +++ b/exporters/trace/ocagent/README.md @@ -0,0 +1,48 @@ +# OpenCensus Java OC-Agent Trace Exporter + +The *OpenCensus Java OC-Agent Trace Exporter* is the Java implementation of the OpenCensus Agent +(OC-Agent) Trace Exporter. + +## Quickstart + +### Add the dependencies to your project + +For Maven add to your `pom.xml`: +```xml +<dependencies> + <dependency> + <groupId>io.opencensus</groupId> + <artifactId>opencensus-api</artifactId> + <version>0.17.0</version> + </dependency> + <dependency> + <groupId>io.opencensus</groupId> + <artifactId>opencensus-exporter-trace-ocagent</artifactId> + <version>0.17.0</version> + </dependency> + <dependency> + <groupId>io.opencensus</groupId> + <artifactId>opencensus-impl</artifactId> + <version>0.17.0</version> + <scope>runtime</scope> + </dependency> +</dependencies> +``` + +For Gradle add to your dependencies: +```gradle +compile 'io.opencensus:opencensus-api:0.17.0' +compile 'io.opencensus:opencensus-exporter-trace-ocagent:0.17.0' +runtime 'io.opencensus:opencensus-impl:0.17.0' +``` + +### Register the exporter + +```java +public class MyMainClass { + public static void main(String[] args) throws Exception { + OcAgentTraceExporter.createAndRegister(); + // ... + } +} +``` diff --git a/exporters/trace/ocagent/build.gradle b/exporters/trace/ocagent/build.gradle new file mode 100644 index 00000000..7214eb58 --- /dev/null +++ b/exporters/trace/ocagent/build.gradle @@ -0,0 +1,19 @@ +description = 'OpenCensus Java OC-Agent Trace Exporter' + +[compileJava, compileTestJava].each() { + it.sourceCompatibility = 1.7 + it.targetCompatibility = 1.7 +} + +dependencies { + compileOnly libraries.auto_value + + compile project(':opencensus-api'), + project(':opencensus-contrib-monitored-resource-util'), + libraries.opencensus_proto + + testCompile project(':opencensus-api') + + signature "org.codehaus.mojo.signature:java17:1.0@signature" + signature "net.sf.androidscents.signature:android-api-level-14:4.0_r4@signature" +} diff --git a/exporters/trace/ocagent/src/main/java/io/opencensus/exporter/trace/ocagent/OcAgentTraceExporter.java b/exporters/trace/ocagent/src/main/java/io/opencensus/exporter/trace/ocagent/OcAgentTraceExporter.java new file mode 100644 index 00000000..c704314a --- /dev/null +++ b/exporters/trace/ocagent/src/main/java/io/opencensus/exporter/trace/ocagent/OcAgentTraceExporter.java @@ -0,0 +1,124 @@ +/* + * Copyright 2018, 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.exporter.trace.ocagent; + +import static com.google.common.base.Preconditions.checkState; + +import com.google.common.annotations.VisibleForTesting; +import io.opencensus.trace.Tracing; +import io.opencensus.trace.export.SpanExporter; +import io.opencensus.trace.export.SpanExporter.Handler; +import javax.annotation.Nullable; +import javax.annotation.concurrent.GuardedBy; +import javax.annotation.concurrent.ThreadSafe; + +/** + * The implementation of the OpenCensus Agent (OC-Agent) Trace Exporter. + * + * <p>Example of usage: + * + * <pre>{@code + * public static void main(String[] args) { + * OcAgentTraceExporter.createAndRegister(); + * ... // Do work. + * } + * }</pre> + * + * @since 0.17 + */ +@ThreadSafe +public final class OcAgentTraceExporter { + + private static final Object monitor = new Object(); + private static final String REGISTER_NAME = OcAgentTraceExporter.class.getName(); + + @GuardedBy("monitor") + @Nullable + private static Handler handler = null; + + private OcAgentTraceExporter() {} + + /** + * Creates a {@code OcAgentTraceExporterHandler} with default configurations and registers it to + * the OpenCensus library. + * + * @since 0.17 + */ + public static void createAndRegister() { + synchronized (monitor) { + checkState(handler == null, "OC-Agent exporter is already registered."); + OcAgentTraceExporterHandler newHandler = new OcAgentTraceExporterHandler(); + registerInternal(newHandler); + } + } + + /** + * Creates a {@code OcAgentTraceExporterHandler} with the given configurations and registers it to + * the OpenCensus library. + * + * @param configuration the {@code OcAgentTraceExporterConfiguration}. + * @since 0.17 + */ + public static void createAndRegister(OcAgentTraceExporterConfiguration configuration) { + synchronized (monitor) { + checkState(handler == null, "OC-Agent exporter is already registered."); + OcAgentTraceExporterHandler newHandler = + new OcAgentTraceExporterHandler( + configuration.getEndPoint(), + configuration.getServiceName(), + configuration.getUseInsecure()); + registerInternal(newHandler); + } + } + + /** + * Registers the {@code OcAgentTraceExporterHandler}. + * + * @param spanExporter the instance of the {@code SpanExporter} where this service is registered. + */ + @VisibleForTesting + static void register(SpanExporter spanExporter, Handler handler) { + spanExporter.registerHandler(REGISTER_NAME, handler); + } + + private static void registerInternal(Handler newHandler) { + synchronized (monitor) { + handler = newHandler; + register(Tracing.getExportComponent().getSpanExporter(), newHandler); + } + } + + /** + * Unregisters the OC-Agent exporter from the OpenCensus library. + * + * @since 0.17 + */ + public static void unregister() { + unregister(Tracing.getExportComponent().getSpanExporter()); + } + + /** + * Unregisters the {@code OcAgentTraceExporterHandler}. + * + * @param spanExporter the instance of the {@code SpanExporter} from where this service is + * unregistered. + */ + @VisibleForTesting + static void unregister(SpanExporter spanExporter) { + spanExporter.unregisterHandler(REGISTER_NAME); + } +} diff --git a/exporters/trace/ocagent/src/main/java/io/opencensus/exporter/trace/ocagent/OcAgentTraceExporterConfiguration.java b/exporters/trace/ocagent/src/main/java/io/opencensus/exporter/trace/ocagent/OcAgentTraceExporterConfiguration.java new file mode 100644 index 00000000..0800eff6 --- /dev/null +++ b/exporters/trace/ocagent/src/main/java/io/opencensus/exporter/trace/ocagent/OcAgentTraceExporterConfiguration.java @@ -0,0 +1,117 @@ +/* + * Copyright 2018, 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.exporter.trace.ocagent; + +import com.google.auto.value.AutoValue; +import javax.annotation.Nullable; +import javax.annotation.concurrent.Immutable; + +/** + * Configurations for {@link OcAgentTraceExporter}. + * + * @since 0.17 + */ +@AutoValue +@Immutable +public abstract class OcAgentTraceExporterConfiguration { + + OcAgentTraceExporterConfiguration() {} + + /** + * Returns the end point of OC-Agent. The end point can be dns, ip:port, etc. + * + * @return the end point of OC-Agent. + * @since 0.17 + */ + @Nullable + public abstract String getEndPoint(); + + /** + * Returns whether to disable client transport security for the exporter's gRPC connection or not. + * + * @return whether to disable client transport security for the exporter's gRPC connection or not. + * @since 0.17 + */ + @Nullable + public abstract Boolean getUseInsecure(); + + /** + * Returns the service name to be used for this {@link OcAgentTraceExporter}. + * + * @return the service name. + * @since 0.17 + */ + @Nullable + public abstract String getServiceName(); + + /** + * Returns a new {@link Builder}. + * + * @return a {@code Builder}. + * @since 0.17 + */ + public static Builder builder() { + return new AutoValue_OcAgentTraceExporterConfiguration.Builder(); + } + + /** + * Builder for {@link OcAgentTraceExporterConfiguration}. + * + * @since 0.17 + */ + @AutoValue.Builder + public abstract static class Builder { + + Builder() {} + + /** + * Sets the end point of OC-Agent server. + * + * @param endPoint the end point of OC-Agent. + * @return this. + * @since 0.17 + */ + public abstract Builder setEndPoint(String endPoint); + + /** + * Sets whether to disable client transport security for the exporter's gRPC connection or not. + * + * @param useInsecure whether disable client transport security for the exporter's gRPC + * connection. + * @return this. + * @since 0.17 + */ + public abstract Builder setUseInsecure(Boolean useInsecure); + + /** + * Sets the service name to be used for this {@link OcAgentTraceExporter}. + * + * @param serviceName the service name. + * @return this. + * @since 0.17 + */ + public abstract Builder setServiceName(String serviceName); + + /** + * Builds a {@link OcAgentTraceExporterConfiguration}. + * + * @return a {@code OcAgentTraceExporterConfiguration}. + * @since 0.17 + */ + public abstract OcAgentTraceExporterConfiguration build(); + } +} diff --git a/exporters/trace/ocagent/src/main/java/io/opencensus/exporter/trace/ocagent/OcAgentTraceExporterHandler.java b/exporters/trace/ocagent/src/main/java/io/opencensus/exporter/trace/ocagent/OcAgentTraceExporterHandler.java new file mode 100644 index 00000000..27e56c66 --- /dev/null +++ b/exporters/trace/ocagent/src/main/java/io/opencensus/exporter/trace/ocagent/OcAgentTraceExporterHandler.java @@ -0,0 +1,51 @@ +/* + * Copyright 2018, 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.exporter.trace.ocagent; + +import io.opencensus.trace.export.SpanData; +import io.opencensus.trace.export.SpanExporter.Handler; +import java.util.Collection; +import javax.annotation.Nullable; + +/** Exporting handler for OC-Agent Tracing. */ +final class OcAgentTraceExporterHandler extends Handler { + + private static final String DEFAULT_END_POINT = "localhost:55678"; + private static final String DEFAULT_SERVICE_NAME = "OpenCensus"; + + // private final String endPoint; + // private final String serviceName; + // private final boolean useInsecure; + + OcAgentTraceExporterHandler() { + this(null, null, null); + } + + OcAgentTraceExporterHandler( + @Nullable String endPoint, @Nullable String serviceName, @Nullable Boolean useInsecure) { + // this.endPoint = endPoint == null ? DEFAULT_END_POINT : endPoint; + // this.serviceName = serviceName == null ? DEFAULT_SERVICE_NAME : serviceName; + // this.useInsecure = useInsecure == null ? false : useInsecure; + } + + @Override + public void export(Collection<SpanData> spanDataList) { + // TODO(songya): implement this. + // for (SpanData spanData : spanDataList) { + // } + } +} diff --git a/exporters/trace/ocagent/src/main/java/io/opencensus/exporter/trace/ocagent/package-info.java b/exporters/trace/ocagent/src/main/java/io/opencensus/exporter/trace/ocagent/package-info.java new file mode 100644 index 00000000..d01dd7eb --- /dev/null +++ b/exporters/trace/ocagent/src/main/java/io/opencensus/exporter/trace/ocagent/package-info.java @@ -0,0 +1,29 @@ +/* + * Copyright 2018, 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. + */ + +/** + * This package contains the Java implementation of the OpenCensus Agent (OC-Agent) Trace Exporter. + * + * <p>WARNING: Currently all the public classes under this package are marked as {@link + * io.opencensus.common.ExperimentalApi}. The classes and APIs under {@link + * io.opencensus.exporter.trace.ocagent} are likely to get backwards-incompatible updates in the + * future. DO NOT USE except for experimental purposes. + * + * <p>See more details on + * https://github.com/census-instrumentation/opencensus-proto/tree/master/src/opencensus/proto/agent. + */ +@io.opencensus.common.ExperimentalApi +package io.opencensus.exporter.trace.ocagent; diff --git a/exporters/trace/ocagent/src/test/java/io/opencensus/exporter/trace/ocagent/OcAgentTraceExporterConfigurationTest.java b/exporters/trace/ocagent/src/test/java/io/opencensus/exporter/trace/ocagent/OcAgentTraceExporterConfigurationTest.java new file mode 100644 index 00000000..4349dfd7 --- /dev/null +++ b/exporters/trace/ocagent/src/test/java/io/opencensus/exporter/trace/ocagent/OcAgentTraceExporterConfigurationTest.java @@ -0,0 +1,50 @@ +/* + * Copyright 2018, 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.exporter.trace.ocagent; + +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 OcAgentTraceExporterConfiguration}. */ +@RunWith(JUnit4.class) +public class OcAgentTraceExporterConfigurationTest { + + @Test + public void defaultConfiguration() { + OcAgentTraceExporterConfiguration configuration = + OcAgentTraceExporterConfiguration.builder().build(); + assertThat(configuration.getEndPoint()).isNull(); + assertThat(configuration.getServiceName()).isNull(); + assertThat(configuration.getUseInsecure()).isNull(); + } + + @Test + public void setAndGet() { + OcAgentTraceExporterConfiguration configuration = + OcAgentTraceExporterConfiguration.builder() + .setEndPoint("192.168.0.1:50051") + .setServiceName("service") + .setUseInsecure(true) + .build(); + assertThat(configuration.getEndPoint()).isEqualTo("192.168.0.1:50051"); + assertThat(configuration.getServiceName()).isEqualTo("service"); + assertThat(configuration.getUseInsecure()).isTrue(); + } +} diff --git a/exporters/trace/ocagent/src/test/java/io/opencensus/exporter/trace/ocagent/OcAgentTraceExporterTest.java b/exporters/trace/ocagent/src/test/java/io/opencensus/exporter/trace/ocagent/OcAgentTraceExporterTest.java new file mode 100644 index 00000000..c58acdb1 --- /dev/null +++ b/exporters/trace/ocagent/src/test/java/io/opencensus/exporter/trace/ocagent/OcAgentTraceExporterTest.java @@ -0,0 +1,54 @@ +/* + * Copyright 2018, 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.exporter.trace.ocagent; + +import static org.mockito.Matchers.any; +import static org.mockito.Matchers.eq; +import static org.mockito.Mockito.verify; + +import io.opencensus.trace.export.SpanExporter; +import io.opencensus.trace.export.SpanExporter.Handler; +import org.junit.Before; +import org.junit.Test; +import org.junit.runner.RunWith; +import org.junit.runners.JUnit4; +import org.mockito.Mock; +import org.mockito.MockitoAnnotations; + +/** Unit tests for {@link OcAgentTraceExporter}. */ +@RunWith(JUnit4.class) +public class OcAgentTraceExporterTest { + @Mock private SpanExporter spanExporter; + @Mock private Handler handler; + + @Before + public void setUp() { + MockitoAnnotations.initMocks(this); + } + + @Test + public void registerUnregisterOcAgentTraceExporter() { + OcAgentTraceExporter.register(spanExporter, handler); + verify(spanExporter) + .registerHandler( + eq("io.opencensus.exporter.trace.ocagent.OcAgentTraceExporter"), + any(OcAgentTraceExporterHandler.class)); + OcAgentTraceExporter.unregister(spanExporter); + verify(spanExporter) + .unregisterHandler(eq("io.opencensus.exporter.trace.ocagent.OcAgentTraceExporter")); + } +} diff --git a/settings.gradle b/settings.gradle index dda7557f..409d3147 100644 --- a/settings.gradle +++ b/settings.gradle @@ -7,6 +7,7 @@ include ":opencensus-impl" include ":opencensus-testing" include ":opencensus-exporter-trace-instana" include ":opencensus-exporter-trace-logging" +include ":opencensus-exporter-trace-ocagent" include ":opencensus-exporter-trace-stackdriver" include ":opencensus-exporter-trace-zipkin" include ":opencensus-exporter-trace-jaeger" @@ -59,6 +60,8 @@ project(':opencensus-exporter-trace-instana').projectDir = "$rootDir/exporters/trace/instana" as File project(':opencensus-exporter-trace-logging').projectDir = "$rootDir/exporters/trace/logging" as File +project(':opencensus-exporter-trace-ocagent').projectDir = + "$rootDir/exporters/trace/ocagent" as File project(':opencensus-exporter-trace-stackdriver').projectDir = "$rootDir/exporters/trace/stackdriver" as File project(':opencensus-exporter-trace-zipkin').projectDir = "$rootDir/exporters/trace/zipkin" as File |