Repository: zookeeper Updated Branches: refs/heads/master df2b3f4fd -> 82776922a
ZOOKEEPER-3103: Pluggable metrics system for ZooKeeper - MetricsProvider API definition Define the API which must be implemented by a Metrics Provider. a MetricsProvider is a pluggable component which is able to gather metrics about the system and publish them to an external application for analysis. Author: Enrico Olivelli - Diennea <[email protected]> Author: Enrico Olivelli <[email protected]> Reviewers: [email protected], [email protected] Closes #582 from eolivelli/fix/metrics and squashes the following commits: 16412653 [Enrico Olivelli] better javadocs c3fc95e9 [Enrico Olivelli - Diennea] Address review comments, clean up API and docs, add 'boolean' return value to registerGauge f57e2f33 [Enrico Olivelli - Diennea] Address review comments, clean up API and docs, add 'boolean' return value to registerGauge 08ca334f [Enrico Olivelli - Diennea] Address review comments, clean up API and docs, add 'boolean' return value to registerGauge 0640293b [Enrico Olivelli - Diennea] ZOOKEEPER-3103 Pluggable metrics system for ZooKeeper - MetricsProvider API definition Project: http://git-wip-us.apache.org/repos/asf/zookeeper/repo Commit: http://git-wip-us.apache.org/repos/asf/zookeeper/commit/82776922 Tree: http://git-wip-us.apache.org/repos/asf/zookeeper/tree/82776922 Diff: http://git-wip-us.apache.org/repos/asf/zookeeper/diff/82776922 Branch: refs/heads/master Commit: 82776922af9a0931e8053c0b93b82311e0f0b4b3 Parents: df2b3f4 Author: Enrico Olivelli - Diennea <[email protected]> Authored: Tue Aug 14 14:33:45 2018 +0200 Committer: Andor Molnar <[email protected]> Committed: Tue Aug 14 14:33:45 2018 +0200 ---------------------------------------------------------------------- .../org/apache/zookeeper/metrics/Counter.java | 50 ++++++++++++++ .../org/apache/zookeeper/metrics/Gauge.java | 35 ++++++++++ .../zookeeper/metrics/MetricsContext.java | 71 ++++++++++++++++++++ .../zookeeper/metrics/MetricsProvider.java | 64 ++++++++++++++++++ .../MetricsProviderLifeCycleException.java | 45 +++++++++++++ .../org/apache/zookeeper/metrics/Summary.java | 35 ++++++++++ 6 files changed, 300 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/zookeeper/blob/82776922/src/java/main/org/apache/zookeeper/metrics/Counter.java ---------------------------------------------------------------------- diff --git a/src/java/main/org/apache/zookeeper/metrics/Counter.java b/src/java/main/org/apache/zookeeper/metrics/Counter.java new file mode 100644 index 0000000..f11717a --- /dev/null +++ b/src/java/main/org/apache/zookeeper/metrics/Counter.java @@ -0,0 +1,50 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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 org.apache.zookeeper.metrics; + +/** + * A counter refers to a value which can only increase. + * Usually the value is reset when the process starts. + */ +public interface Counter { + + /** + * Increment the value by one. + * <p>This method is thread safe, The MetricsProvider will take care of synchronization.</p> + */ + default void inc() { + inc(1); + } + + /** + * Increment the value by a given amount. + * <p>This method is thread safe, The MetricsProvider will take care of synchronization.</p> + * + * @param delta amount to increment, this cannot be a negative number. + */ + void inc(long delta); + + /** + * Get the current value held by the counter. + * <p>This method is thread safe, The MetricsProvider will take care of synchronization.</p> + * + * @return the current value + */ + long get(); +} http://git-wip-us.apache.org/repos/asf/zookeeper/blob/82776922/src/java/main/org/apache/zookeeper/metrics/Gauge.java ---------------------------------------------------------------------- diff --git a/src/java/main/org/apache/zookeeper/metrics/Gauge.java b/src/java/main/org/apache/zookeeper/metrics/Gauge.java new file mode 100644 index 0000000..fb8fd67 --- /dev/null +++ b/src/java/main/org/apache/zookeeper/metrics/Gauge.java @@ -0,0 +1,35 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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 org.apache.zookeeper.metrics; + +/** + * A Gauge is an application provided object which will be called by the framework in order to sample the value + * of an integer value. + */ +public interface Gauge { + + /** + * Returns the current value associated with this gauge. + * The MetricsProvider will call this callback without taking care of synchronization, it is up to the application + * to handle thread safety. + * + * @return the current value for the gauge + */ + long get(); +} http://git-wip-us.apache.org/repos/asf/zookeeper/blob/82776922/src/java/main/org/apache/zookeeper/metrics/MetricsContext.java ---------------------------------------------------------------------- diff --git a/src/java/main/org/apache/zookeeper/metrics/MetricsContext.java b/src/java/main/org/apache/zookeeper/metrics/MetricsContext.java new file mode 100644 index 0000000..f095e91 --- /dev/null +++ b/src/java/main/org/apache/zookeeper/metrics/MetricsContext.java @@ -0,0 +1,71 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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 org.apache.zookeeper.metrics; + +/** + * A MetricsContext is like a namespace for metrics. + * Each component/submodule will have its own MetricsContext. + * <p>In some cases it is possible to have a separate MetricsContext + * for each instance of a component, for instance on the server side + * a possible usecase it to gather metrics for every other peer. + * </p> + * <p> + * Contexts are organized in a hierarchy. + * </p> + * + */ +public interface MetricsContext { + + /** + * Returns a sub context. + * + * @param name the name of the subcontext + * + * @return a new metrics context. + */ + MetricsContext getContext(String name); + + /** + * Returns a counter. + * + * @param name + * @return the counter identified by name in this context. + */ + Counter getCounter(String name); + + /** + * Registers an user provided {@link Gauge} which will be called by the MetricsProvider in order to sample + * an integer value. + * + * @param name unique name of the Gauge in this context + * @param gauge the implementation of the Gauge + * + * @return true if the Gauge was successfully registered, false if the Gauge was already registered. + */ + boolean registerGauge(String name, Gauge gauge); + + /** + * Returns a summary. + * + * @param name + * @return the summary identified by name in this context. + */ + Summary getSummary(String name); + +} http://git-wip-us.apache.org/repos/asf/zookeeper/blob/82776922/src/java/main/org/apache/zookeeper/metrics/MetricsProvider.java ---------------------------------------------------------------------- diff --git a/src/java/main/org/apache/zookeeper/metrics/MetricsProvider.java b/src/java/main/org/apache/zookeeper/metrics/MetricsProvider.java new file mode 100644 index 0000000..16e9e0d --- /dev/null +++ b/src/java/main/org/apache/zookeeper/metrics/MetricsProvider.java @@ -0,0 +1,64 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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 org.apache.zookeeper.metrics; + +import java.util.Properties; + +/** + * A MetricsProvider is a system which collects Metrics and publishes current values to external facilities. + * + * The system will create an instance of the configured class using the default constructor, which must be public.<br> + * After the instantiation of the provider, the system will call {@link #configure(java.util.Map) } in order to provide configuration, + * and then when the system is ready to work it will call {@link #start() }. + * <br> + * Providers can be used both on ZooKeeper servers and on ZooKeeper clients. + */ +public interface MetricsProvider { + + /** + * Configure the provider. + * + * @param configuration the configuration. + * + * @throws MetricsProviderLifeCycleException in case of invalid configuration. + */ + void configure(Properties configuration) throws MetricsProviderLifeCycleException; + + /** + * Start the provider. + * For instance such method will start a network endpoint. + * + * @throws MetricsProviderLifeCycleException in case of failure + */ + void start() throws MetricsProviderLifeCycleException; + + /** + * Provides access to the root context. + * + * @return the root context + */ + MetricsContext getRootContext(); + + /** + * Releases resources held by the provider.<br> + * This method must not throw exceptions.<br> + * This method can be called more than once. + */ + void stop(); +} http://git-wip-us.apache.org/repos/asf/zookeeper/blob/82776922/src/java/main/org/apache/zookeeper/metrics/MetricsProviderLifeCycleException.java ---------------------------------------------------------------------- diff --git a/src/java/main/org/apache/zookeeper/metrics/MetricsProviderLifeCycleException.java b/src/java/main/org/apache/zookeeper/metrics/MetricsProviderLifeCycleException.java new file mode 100644 index 0000000..809ead3 --- /dev/null +++ b/src/java/main/org/apache/zookeeper/metrics/MetricsProviderLifeCycleException.java @@ -0,0 +1,45 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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 org.apache.zookeeper.metrics; + +/** + * A generic exception thrown during the licecycle of a MetricsProvider. + * <p>These exception will prevent the system from booting.</p> + * <p>Normally these exception will be ignored during shutdown.</p> + */ +public class MetricsProviderLifeCycleException extends Exception { + + private static final long serialVersionUID = 1L; + + public MetricsProviderLifeCycleException() { + } + + public MetricsProviderLifeCycleException(String message) { + super(message); + } + + public MetricsProviderLifeCycleException(String message, Throwable cause) { + super(message, cause); + } + + public MetricsProviderLifeCycleException(Throwable cause) { + super(cause); + } + +} http://git-wip-us.apache.org/repos/asf/zookeeper/blob/82776922/src/java/main/org/apache/zookeeper/metrics/Summary.java ---------------------------------------------------------------------- diff --git a/src/java/main/org/apache/zookeeper/metrics/Summary.java b/src/java/main/org/apache/zookeeper/metrics/Summary.java new file mode 100644 index 0000000..8b882ac --- /dev/null +++ b/src/java/main/org/apache/zookeeper/metrics/Summary.java @@ -0,0 +1,35 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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 org.apache.zookeeper.metrics; + +/** + * Summaries track the size and number of events. + * They are able to publish minumum, maximum, average values, depending on the capabilities of the MetricsProvider. + */ +public interface Summary { + + /** + * Register a value. + * <p>This method is thread safe, The MetricsProvider will take care of synchronization.</p> + * + * @param value current value + */ + void registerValue(long value); + +}
