You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by eo...@apache.org on 2020/04/05 10:58:11 UTC
[maven-studies] 09/11: Start Metrics Module
This is an automated email from the ASF dual-hosted git repository.
eolivelli pushed a commit to branch maven-metrics
in repository https://gitbox.apache.org/repos/asf/maven-studies.git
commit 01748855206e89b0b2d625b42cb038a18ab971cc
Author: Enrico Olivelli <eo...@apache.org>
AuthorDate: Sat Mar 28 14:44:52 2020 +0100
Start Metrics Module
---
maven-metrics/pom.xml | 44 ++++++
.../java/org/apache/maven/metrics/Counter.java | 54 +++++++
.../main/java/org/apache/maven/metrics/Gauge.java | 38 +++++
.../org/apache/maven/metrics/MetricsContext.java | 92 ++++++++++++
.../org/apache/maven/metrics/MetricsProvider.java | 83 +++++++++++
.../metrics/MetricsProviderLifeCycleException.java | 51 +++++++
.../java/org/apache/maven/metrics/Summary.java | 37 +++++
.../java/org/apache/maven/metrics/SummarySet.java | 39 +++++
.../maven/metrics/impl/NullMetricsProvider.java | 160 +++++++++++++++++++++
9 files changed, 598 insertions(+)
diff --git a/maven-metrics/pom.xml b/maven-metrics/pom.xml
new file mode 100644
index 0000000..ab30cb6
--- /dev/null
+++ b/maven-metrics/pom.xml
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+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.
+-->
+
+<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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>org.apache.maven</groupId>
+ <artifactId>maven</artifactId>
+ <version>3.7.0-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>maven-metrics</artifactId>
+
+ <name>Maven Metrics</name>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.commons</groupId>
+ <artifactId>commons-lang3</artifactId>
+ </dependency>
+ </dependencies>
+
+ <build>
+ </build>
+</project>
diff --git a/maven-metrics/src/main/java/org/apache/maven/metrics/Counter.java b/maven-metrics/src/main/java/org/apache/maven/metrics/Counter.java
new file mode 100644
index 0000000..e2eb1d1
--- /dev/null
+++ b/maven-metrics/src/main/java/org/apache/maven/metrics/Counter.java
@@ -0,0 +1,54 @@
+package org.apache.maven.metrics;
+
+/*
+ * 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.
+ */
+
+/**
+ * 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()
+ {
+ add( 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 add( 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();
+
+}
diff --git a/maven-metrics/src/main/java/org/apache/maven/metrics/Gauge.java b/maven-metrics/src/main/java/org/apache/maven/metrics/Gauge.java
new file mode 100644
index 0000000..1c6559c
--- /dev/null
+++ b/maven-metrics/src/main/java/org/apache/maven/metrics/Gauge.java
@@ -0,0 +1,38 @@
+package org.apache.maven.metrics;
+
+/*
+ * 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.
+ */
+
+/**
+ * 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
+ */
+ Number get();
+
+}
diff --git a/maven-metrics/src/main/java/org/apache/maven/metrics/MetricsContext.java b/maven-metrics/src/main/java/org/apache/maven/metrics/MetricsContext.java
new file mode 100644
index 0000000..a42b5bb
--- /dev/null
+++ b/maven-metrics/src/main/java/org/apache/maven/metrics/MetricsContext.java
@@ -0,0 +1,92 @@
+package org.apache.maven.metrics;
+
+/*
+ * 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.
+ */
+
+/**
+ * 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.
+ * If another Gauge was already registered the new one will
+ * take its place.
+ * Registering a null callback is not allowed.
+ *
+ * @param name unique name of the Gauge in this context
+ * @param gauge the implementation of the Gauge
+ *
+ */
+ void registerGauge( String name, Gauge gauge );
+
+ /**
+ * Unregisters the user provided {@link Gauge} bound to the given name.
+ *
+ * @param name unique name of the Gauge in this context
+ *
+ */
+ void unregisterGauge( String name );
+
+ /**
+ * Returns a summary.
+ *
+ * @param name
+ * @return the summary identified by name in this context.
+ */
+ Summary getSummary( String name );
+
+ /**
+ * Returns a set of summaries.
+ *
+ * @param name
+ * @return the summary identified by name in this context.
+ */
+ SummarySet getSummarySet( String name );
+
+}
diff --git a/maven-metrics/src/main/java/org/apache/maven/metrics/MetricsProvider.java b/maven-metrics/src/main/java/org/apache/maven/metrics/MetricsProvider.java
new file mode 100644
index 0000000..66d197c
--- /dev/null
+++ b/maven-metrics/src/main/java/org/apache/maven/metrics/MetricsProvider.java
@@ -0,0 +1,83 @@
+package org.apache.maven.metrics;
+
+/*
+ * 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.
+ */
+
+import java.util.Properties;
+import java.util.function.BiConsumer;
+
+/**
+ * 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.Properties) }
+ * 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();
+
+ /**
+ * Dumps all metrics as a key-value pair.
+ * This method will be used in legacy monitor command.
+ * @param sink the receiver of all of the current values.
+ */
+ void dump( BiConsumer<String, Object> sink );
+
+ /**
+ * Reset all values.
+ * This method is optional and can be noop, depending
+ * on the underlying implementation.
+ */
+ void resetAllValues();
+
+}
diff --git a/maven-metrics/src/main/java/org/apache/maven/metrics/MetricsProviderLifeCycleException.java b/maven-metrics/src/main/java/org/apache/maven/metrics/MetricsProviderLifeCycleException.java
new file mode 100644
index 0000000..ecf7d5b
--- /dev/null
+++ b/maven-metrics/src/main/java/org/apache/maven/metrics/MetricsProviderLifeCycleException.java
@@ -0,0 +1,51 @@
+package org.apache.maven.metrics;
+
+/*
+ * 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.
+ */
+
+/**
+ * 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 );
+ }
+
+}
diff --git a/maven-metrics/src/main/java/org/apache/maven/metrics/Summary.java b/maven-metrics/src/main/java/org/apache/maven/metrics/Summary.java
new file mode 100644
index 0000000..9ad49c1
--- /dev/null
+++ b/maven-metrics/src/main/java/org/apache/maven/metrics/Summary.java
@@ -0,0 +1,37 @@
+package org.apache.maven.metrics;
+
+/*
+ * 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.
+ */
+
+/**
+ * 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 add( long value );
+
+}
diff --git a/maven-metrics/src/main/java/org/apache/maven/metrics/SummarySet.java b/maven-metrics/src/main/java/org/apache/maven/metrics/SummarySet.java
new file mode 100644
index 0000000..e31764a
--- /dev/null
+++ b/maven-metrics/src/main/java/org/apache/maven/metrics/SummarySet.java
@@ -0,0 +1,39 @@
+package org.apache.maven.metrics;
+
+/*
+ * 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.
+ */
+
+/**
+ * Summaries track the size and number of events.
+ * They are able to publish minumum, maximum, average values, depending on the capabilities of the MetricsProvider.
+ * A SummarySet is a set of {@link Summary}.
+ */
+public interface SummarySet
+{
+
+ /**
+ * Register a value.
+ * <p>This method is thread safe, The MetricsProvider will take care of synchronization.</p>
+ *
+ * @param key the key to access the Summary for the given key
+ * @param value current value
+ */
+ void add( String key, long value );
+
+}
diff --git a/maven-metrics/src/main/java/org/apache/maven/metrics/impl/NullMetricsProvider.java b/maven-metrics/src/main/java/org/apache/maven/metrics/impl/NullMetricsProvider.java
new file mode 100644
index 0000000..f7ed453
--- /dev/null
+++ b/maven-metrics/src/main/java/org/apache/maven/metrics/impl/NullMetricsProvider.java
@@ -0,0 +1,160 @@
+package org.apache.maven.metrics.impl;
+
+/*
+ * 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.
+ */
+
+import java.util.Properties;
+import java.util.function.BiConsumer;
+import org.apache.maven.metrics.Counter;
+import org.apache.maven.metrics.Gauge;
+import org.apache.maven.metrics.MetricsContext;
+import org.apache.maven.metrics.MetricsProvider;
+import org.apache.maven.metrics.MetricsProviderLifeCycleException;
+import org.apache.maven.metrics.Summary;
+import org.apache.maven.metrics.SummarySet;
+
+/**
+ * This is a dummy MetricsProvider which does nothing.
+ */
+public class NullMetricsProvider implements MetricsProvider
+{
+
+ /**
+ * Instance of NullMetricsProvider useful for tests.
+ */
+ public static final MetricsProvider INSTANCE = new NullMetricsProvider();
+
+ @Override
+ public void configure( Properties configuration ) throws MetricsProviderLifeCycleException
+ {
+ }
+
+ @Override
+ public void start() throws MetricsProviderLifeCycleException
+ {
+ }
+
+ @Override
+ public MetricsContext getRootContext()
+ {
+ return NullMetricsContext.INSTANCE;
+ }
+
+ @Override
+ public void dump( BiConsumer<String, Object> sink )
+ {
+ }
+
+ @Override
+ public void resetAllValues()
+ {
+ }
+
+ @Override
+ public void stop()
+ {
+ }
+
+ /**
+ * Default no-op implementation.
+ */
+ public static final class NullMetricsContext implements MetricsContext
+ {
+
+ public static final NullMetricsContext INSTANCE = new NullMetricsContext();
+
+ @Override
+ public MetricsContext getContext( String name )
+ {
+ return INSTANCE;
+ }
+
+ @Override
+ public Counter getCounter( String name )
+ {
+ return NullCounter.INSTANCE;
+ }
+
+ @Override
+ public void registerGauge( String name, Gauge gauge )
+ {
+ }
+
+ @Override
+ public void unregisterGauge( String name )
+ {
+ }
+
+ @Override
+ public Summary getSummary( String name )
+ {
+ return NullSummary.INSTANCE;
+ }
+
+ @Override
+ public SummarySet getSummarySet( String name )
+ {
+ return NullSummarySet.INSTANCE;
+ }
+
+ }
+
+ private static final class NullCounter implements Counter
+ {
+
+ private static final NullCounter INSTANCE = new NullCounter();
+
+ @Override
+ public void add( long delta )
+ {
+ }
+
+ @Override
+ public long get()
+ {
+ return 0;
+ }
+
+ }
+
+ private static final class NullSummary implements Summary
+ {
+
+ private static final NullSummary INSTANCE = new NullSummary();
+
+ @Override
+ public void add( long value )
+ {
+ }
+
+ }
+
+ private static final class NullSummarySet implements SummarySet
+ {
+
+ private static final NullSummarySet INSTANCE = new NullSummarySet();
+
+ @Override
+ public void add( String key, long value )
+ {
+ }
+
+ }
+
+}