diff options
author | Bogdan Drutu <bdrutu@google.com> | 2018-08-10 14:45:23 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2018-08-10 14:45:23 -0700 |
commit | a804907c77858ff319ba059af968f6cfd8eb3925 (patch) | |
tree | ca5cb145056682cf950a9e8442d4b7f05242cddc | |
parent | 52f38e48e2ac6cb65e28dcd97b4f7e9650357bba (diff) | |
download | opencensus-java-a804907c77858ff319ba059af968f6cfd8eb3925.tar.gz |
Add support for recording Gauges. (#1344)
* Add support for Gauges in OpenCensus.
* Minor comment fix.
-rw-r--r-- | api/src/main/java/io/opencensus/common/ToDoubleFunction.java | 39 | ||||
-rw-r--r-- | api/src/main/java/io/opencensus/common/ToLongFunction.java | 38 | ||||
-rw-r--r-- | metrics/src/main/java/io/opencensus/metrics/MetricProducer.java (renamed from metrics/src/main/java/io/opencensus/metrics/export/MetricProducer.java) | 10 | ||||
-rw-r--r-- | metrics/src/main/java/io/opencensus/metrics/MetricRegistry.java | 117 | ||||
-rw-r--r-- | metrics/src/main/java/io/opencensus/metrics/Metrics.java | 13 | ||||
-rw-r--r-- | metrics/src/main/java/io/opencensus/metrics/MetricsComponent.java | 14 | ||||
-rw-r--r-- | metrics/src/main/java/io/opencensus/metrics/export/MetricProducerManager.java | 1 | ||||
-rw-r--r-- | metrics/src/test/java/io/opencensus/metrics/MetricRegistryTest.java | 181 | ||||
-rw-r--r-- | metrics/src/test/java/io/opencensus/metrics/MetricsComponentTest.java | 6 | ||||
-rw-r--r-- | metrics/src/test/java/io/opencensus/metrics/export/MetricProducerManagerTest.java | 1 |
10 files changed, 415 insertions, 5 deletions
diff --git a/api/src/main/java/io/opencensus/common/ToDoubleFunction.java b/api/src/main/java/io/opencensus/common/ToDoubleFunction.java new file mode 100644 index 00000000..479270f1 --- /dev/null +++ b/api/src/main/java/io/opencensus/common/ToDoubleFunction.java @@ -0,0 +1,39 @@ +/* + * 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.common; + +// TODO(bdrutu): Change @code to @link when metrics is moved in the API. + +/** + * Represents a function that produces a double-valued result. See {@code + * io.opencensus.metrics.MetricRegistry} for an example of its use. + * + * <p>Note: This class is based on the java.util.ToDoubleFunction class added in Java 1.8. We cannot + * use the Function from Java 1.8 because this library is Java 1.6 compatible. + * + * @since 0.16 + */ +public interface ToDoubleFunction<T> { + + /** + * Applies this function to the given argument. + * + * @param value the function argument. + * @return the function result. + */ + double applyAsDouble(T value); +} diff --git a/api/src/main/java/io/opencensus/common/ToLongFunction.java b/api/src/main/java/io/opencensus/common/ToLongFunction.java new file mode 100644 index 00000000..9a6e9b19 --- /dev/null +++ b/api/src/main/java/io/opencensus/common/ToLongFunction.java @@ -0,0 +1,38 @@ +/* + * 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.common; + +// TODO(bdrutu): Change @code to @link when metrics is moved in the API. + +/** + * Represents a function that produces a long-valued result. See {@code + * io.opencensus.metrics.MetricRegistry} for an example of its use. + * + * <p>Note: This class is based on the java.util.ToLongFunction class added in Java 1.8. We cannot + * use the Function from Java 1.8 because this library is Java 1.6 compatible. + * + * @since 0.16 + */ +public interface ToLongFunction<T> { + /** + * Applies this function to the given argument. + * + * @param value the function argument. + * @return the function result. + */ + long applyAsLong(T value); +} diff --git a/metrics/src/main/java/io/opencensus/metrics/export/MetricProducer.java b/metrics/src/main/java/io/opencensus/metrics/MetricProducer.java index a6658ac1..38b5d571 100644 --- a/metrics/src/main/java/io/opencensus/metrics/export/MetricProducer.java +++ b/metrics/src/main/java/io/opencensus/metrics/MetricProducer.java @@ -14,14 +14,14 @@ * limitations under the License. */ -package io.opencensus.metrics.export; +package io.opencensus.metrics; import io.opencensus.common.ExperimentalApi; -import io.opencensus.metrics.Metric; +import io.opencensus.metrics.export.MetricProducerManager; import java.util.Collection; /** - * A {@link Metric} producer that can be registered for exporting using {@link + * A {@link io.opencensus.metrics.Metric} producer that can be registered for exporting using {@link * MetricProducerManager}. * * <p>All implementation MUST be thread-safe. @@ -30,9 +30,9 @@ import java.util.Collection; public abstract class MetricProducer { /** - * Returns a collection of produced {@link Metric}s to be exported. + * Returns a collection of produced {@link io.opencensus.metrics.Metric}s to be exported. * - * @return a collection of produced {@link Metric}s to be exported. + * @return a collection of produced {@link io.opencensus.metrics.Metric}s to be exported. */ public abstract Collection<Metric> getMetrics(); } diff --git a/metrics/src/main/java/io/opencensus/metrics/MetricRegistry.java b/metrics/src/main/java/io/opencensus/metrics/MetricRegistry.java new file mode 100644 index 00000000..ae4d90b0 --- /dev/null +++ b/metrics/src/main/java/io/opencensus/metrics/MetricRegistry.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.metrics; + +import io.opencensus.common.ExperimentalApi; +import io.opencensus.common.ToDoubleFunction; +import io.opencensus.common.ToLongFunction; +import io.opencensus.internal.Utils; +import java.util.Collection; +import java.util.Collections; +import java.util.LinkedHashMap; + +/** + * Creates and manages your application's set of metrics. Exporters use the metric registry to + * iterate over the set of metrics instrumenting your application, and then further export each + * metric to the backend of choice. + * + * @since 0.16 + */ +@ExperimentalApi +public abstract class MetricRegistry extends MetricProducer { + /** + * Build a new long gauge to be added to the registry. + * + * <p>Must be called only once. + * + * @param name the name of the metric. + * @param description the description of the metric. + * @param unit the unit of the metric. + * @param obj the function argument. + * @param function the function to be called. + * @since 0.16 @ExperimentalApi + */ + public abstract <T> void addLongGauge( + String name, + String description, + String unit, + LinkedHashMap<LabelKey, LabelValue> labels, + T obj, + ToLongFunction<T> function); + + /** + * Build a new double gauge to be added to the registry. + * + * <p>Must be called only once. + * + * @param name the name of the metric. + * @param description the description of the metric. + * @param unit the unit of the metric. + * @param obj the function argument. + * @param function the function to be called. + * @since 0.16 @ExperimentalApi + */ + public abstract <T> void addDoubleGauge( + String name, + String description, + String unit, + LinkedHashMap<LabelKey, LabelValue> labels, + T obj, + ToDoubleFunction<T> function); + + static MetricRegistry newNoopMetricRegistry() { + return new NoopMetricRegistry(); + } + + private static final class NoopMetricRegistry extends MetricRegistry { + + @Override + public <T> void addLongGauge( + String name, + String description, + String unit, + LinkedHashMap<LabelKey, LabelValue> labels, + T obj, + ToLongFunction<T> function) { + Utils.checkNotNull(name, "name"); + Utils.checkNotNull(description, "description"); + Utils.checkNotNull(unit, "unit"); + Utils.checkNotNull(labels, "labels"); + Utils.checkNotNull(function, "function"); + } + + @Override + public <T> void addDoubleGauge( + String name, + String description, + String unit, + LinkedHashMap<LabelKey, LabelValue> labels, + T obj, + ToDoubleFunction<T> function) { + Utils.checkNotNull(name, "name"); + Utils.checkNotNull(description, "description"); + Utils.checkNotNull(unit, "unit"); + Utils.checkNotNull(labels, "labels"); + Utils.checkNotNull(function, "function"); + } + + @Override + public Collection<Metric> getMetrics() { + return Collections.emptyList(); + } + } +} diff --git a/metrics/src/main/java/io/opencensus/metrics/Metrics.java b/metrics/src/main/java/io/opencensus/metrics/Metrics.java index e36bc4e1..ed7d6716 100644 --- a/metrics/src/main/java/io/opencensus/metrics/Metrics.java +++ b/metrics/src/main/java/io/opencensus/metrics/Metrics.java @@ -40,6 +40,19 @@ public final class Metrics { return metricsComponent.getExportComponent(); } + /** + * Returns the global {@link MetricRegistry}. + * + * <p>This {@code MetricRegistry} is already added to the global {@link + * io.opencensus.metrics.export.MetricProducerManager}. + * + * @return the global {@code MetricRegistry}. + * @since 0.16 + */ + public static MetricRegistry getMetricRegistry() { + return metricsComponent.getMetricRegistry(); + } + // Any provider that may be used for MetricsComponent can be added here. @DefaultVisibilityForTesting static MetricsComponent loadMetricsComponent(@Nullable ClassLoader classLoader) { diff --git a/metrics/src/main/java/io/opencensus/metrics/MetricsComponent.java b/metrics/src/main/java/io/opencensus/metrics/MetricsComponent.java index df6d4aec..08d954ef 100644 --- a/metrics/src/main/java/io/opencensus/metrics/MetricsComponent.java +++ b/metrics/src/main/java/io/opencensus/metrics/MetricsComponent.java @@ -37,6 +37,14 @@ public abstract class MetricsComponent { public abstract ExportComponent getExportComponent(); /** + * Returns the {@link MetricRegistry} with the provided implementation. + * + * @return the {@link MetricRegistry} implementation. + * @since 0.16 + */ + public abstract MetricRegistry getMetricRegistry(); + + /** * Returns an instance that contains no-op implementations for all the instances. * * @return an instance that contains no-op implementations for all the instances. @@ -48,10 +56,16 @@ public abstract class MetricsComponent { private static final class NoopMetricsComponent extends MetricsComponent { private static final ExportComponent EXPORT_COMPONENT = ExportComponent.newNoopExportComponent(); + private static final MetricRegistry METRIC_REGISTRY = MetricRegistry.newNoopMetricRegistry(); @Override public ExportComponent getExportComponent() { return EXPORT_COMPONENT; } + + @Override + public MetricRegistry getMetricRegistry() { + return METRIC_REGISTRY; + } } } diff --git a/metrics/src/main/java/io/opencensus/metrics/export/MetricProducerManager.java b/metrics/src/main/java/io/opencensus/metrics/export/MetricProducerManager.java index ae744635..9600a023 100644 --- a/metrics/src/main/java/io/opencensus/metrics/export/MetricProducerManager.java +++ b/metrics/src/main/java/io/opencensus/metrics/export/MetricProducerManager.java @@ -18,6 +18,7 @@ package io.opencensus.metrics.export; import io.opencensus.common.ExperimentalApi; import io.opencensus.internal.Utils; +import io.opencensus.metrics.MetricProducer; import java.util.Collections; import java.util.LinkedHashSet; import java.util.Set; diff --git a/metrics/src/test/java/io/opencensus/metrics/MetricRegistryTest.java b/metrics/src/test/java/io/opencensus/metrics/MetricRegistryTest.java new file mode 100644 index 00000000..0e467dc8 --- /dev/null +++ b/metrics/src/test/java/io/opencensus/metrics/MetricRegistryTest.java @@ -0,0 +1,181 @@ +/* + * 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.metrics; + +import io.opencensus.common.ToDoubleFunction; +import io.opencensus.common.ToLongFunction; +import java.util.LinkedHashMap; +import org.junit.Rule; +import org.junit.Test; +import org.junit.rules.ExpectedException; + +public class MetricRegistryTest { + @Rule public ExpectedException thrown = ExpectedException.none(); + + private final MetricRegistry metricRegistry = + MetricsComponent.newNoopMetricsComponent().getMetricRegistry(); + + @Test + public void addDoubleGauge_NullName() { + thrown.expect(NullPointerException.class); + metricRegistry.addDoubleGauge( + null, + "description", + "1", + new LinkedHashMap<LabelKey, LabelValue>(), + null, + new ToDoubleFunction<Object>() { + @Override + public double applyAsDouble(Object value) { + return 5.0; + } + }); + } + + @Test + public void addDoubleGauge_NullDescription() { + thrown.expect(NullPointerException.class); + metricRegistry.addDoubleGauge( + "name", + null, + "1", + new LinkedHashMap<LabelKey, LabelValue>(), + null, + new ToDoubleFunction<Object>() { + @Override + public double applyAsDouble(Object value) { + return 5.0; + } + }); + } + + @Test + public void addDoubleGauge_NullUnit() { + thrown.expect(NullPointerException.class); + metricRegistry.addDoubleGauge( + "name", + "description", + null, + new LinkedHashMap<LabelKey, LabelValue>(), + null, + new ToDoubleFunction<Object>() { + @Override + public double applyAsDouble(Object value) { + return 5.0; + } + }); + } + + @Test + public void addDoubleGauge_NullLabels() { + thrown.expect(NullPointerException.class); + metricRegistry.addDoubleGauge( + "name", + "description", + "1", + null, + null, + new ToDoubleFunction<Object>() { + @Override + public double applyAsDouble(Object value) { + return 5.0; + } + }); + } + + @Test + public void addDoubleGauge_NullFunction() { + thrown.expect(NullPointerException.class); + metricRegistry.addDoubleGauge( + "name", "description", "1", new LinkedHashMap<LabelKey, LabelValue>(), null, null); + } + + @Test + public void addLongGauge_NullName() { + thrown.expect(NullPointerException.class); + metricRegistry.addLongGauge( + null, + "description", + "1", + new LinkedHashMap<LabelKey, LabelValue>(), + null, + new ToLongFunction<Object>() { + @Override + public long applyAsLong(Object value) { + return 5; + } + }); + } + + @Test + public void addLongGauge_NullDescription() { + thrown.expect(NullPointerException.class); + metricRegistry.addLongGauge( + "name", + null, + "1", + new LinkedHashMap<LabelKey, LabelValue>(), + null, + new ToLongFunction<Object>() { + @Override + public long applyAsLong(Object value) { + return 5; + } + }); + } + + @Test + public void addLongGauge_NullUnit() { + thrown.expect(NullPointerException.class); + metricRegistry.addLongGauge( + "name", + "description", + null, + new LinkedHashMap<LabelKey, LabelValue>(), + null, + new ToLongFunction<Object>() { + @Override + public long applyAsLong(Object value) { + return 5; + } + }); + } + + @Test + public void addLongGauge_NullLabels() { + thrown.expect(NullPointerException.class); + metricRegistry.addLongGauge( + "name", + "description", + "1", + null, + null, + new ToLongFunction<Object>() { + @Override + public long applyAsLong(Object value) { + return 5; + } + }); + } + + @Test + public void addLongGauge_NullFunction() { + thrown.expect(NullPointerException.class); + metricRegistry.addLongGauge( + "name", "description", "1", new LinkedHashMap<LabelKey, LabelValue>(), null, null); + } +} diff --git a/metrics/src/test/java/io/opencensus/metrics/MetricsComponentTest.java b/metrics/src/test/java/io/opencensus/metrics/MetricsComponentTest.java index 0a3ceb14..1c4e70f7 100644 --- a/metrics/src/test/java/io/opencensus/metrics/MetricsComponentTest.java +++ b/metrics/src/test/java/io/opencensus/metrics/MetricsComponentTest.java @@ -31,4 +31,10 @@ public class MetricsComponentTest { assertThat(MetricsComponent.newNoopMetricsComponent().getExportComponent()) .isInstanceOf(ExportComponent.newNoopExportComponent().getClass()); } + + @Test + public void defaultMetricRegistry() { + assertThat(MetricsComponent.newNoopMetricsComponent().getMetricRegistry()) + .isInstanceOf(MetricRegistry.newNoopMetricRegistry().getClass()); + } } diff --git a/metrics/src/test/java/io/opencensus/metrics/export/MetricProducerManagerTest.java b/metrics/src/test/java/io/opencensus/metrics/export/MetricProducerManagerTest.java index 2d4e7c9c..b79de213 100644 --- a/metrics/src/test/java/io/opencensus/metrics/export/MetricProducerManagerTest.java +++ b/metrics/src/test/java/io/opencensus/metrics/export/MetricProducerManagerTest.java @@ -18,6 +18,7 @@ package io.opencensus.metrics.export; import static com.google.common.truth.Truth.assertThat; +import io.opencensus.metrics.MetricProducer; import java.util.Set; import org.junit.Before; import org.junit.Rule; |