Add AOP-based spring method timing metrics, servlet filter for path-based metrics. (prometheus#168)

Add servlet filter for timing requests and Spring AOP method timings

Author: andrewstuart

README.md

@@ -400,6 +400,83 @@ or `EntityManagerFactory`, you can use this code to access the underlying `Sessi
 SessionFactory sessionFactory = entityManagerFactory.unwrap(SessionFactory.class);
 ```
 
+#### Servlet Filter
+
+There is a servlet filter available for measuring the duration taken by servlet
+requests. The `metric-name` init parameter is required, and is the name of the
+metric prometheus will expose for the timing metrics. Help text via the `help`
+init parameter is not required, although it is highly recommended.  The number
+of buckets is overridable, and can be configured by passing a comma-separated
+string of doubles as the `buckets` init parameter. The granularity of path
+measuring is also configurable, via the `path-components` init parameter. By
+default, the servlet filter will record each path differently, but by setting an
+integer here, you can tell the filter to only record up to the Nth slashes. That
+is, all reqeusts with greater than N "/" characters in the servlet URI path will
+be measured in the same bucket and you will lose that granularity.
+
+The code below is an example of the XML configuration for the filter. You will
+need to place this (replace your own values) code in your
+`webapp/WEB-INF/web.xml` file.
+
+```xml
+<filter>
+  <filter-name>prometheusFilter</filter-name>
+  <filter-class>net.cccnext.ssp.portal.spring.filter.PrometheusMetricsFilter</filter-class>
+  <init-param>
+    <param-name>metric-name</param-name>
+    <param-value>webapp_metrics_filter</param-value>
+  </init-param>
+  <init-param>
+    <param-name>help</param-name>
+    <param-value>This is the help for your metrics filter</param-value>
+  </init-param>
+  <init-param>
+    <param-name>buckets</param-name>
+    <param-value>0.005,0.01,0.025,0.05,0.075,0.1,0.25,0.5,0.75,1,2.5,5,7.5,10</param-value>
+  </init-param>
+  <!-- Optionally override path components; anything less than 1 (1 is the default)
+       means full granularity -->
+  <init-param>
+    <param-name>path-components</param-name>
+    <param-value>1</param-value>
+  </init-param>
+</filter>
+
+<!-- You will most likely want this to be the first filter in the chain
+(therefore the first <filter-mapping> in the web.xml file), so that you can get
+the most accurate measurement of latency. -->
+<filter-mapping>
+  <filter-name>prometheusFilter</filter-name>
+  <url-pattern>/*</url-pattern>
+</filter-mapping>
+```
+
+Additionally, you can instantiate your servlet filter directly in Java code. To
+do this, you just need to call the non-empty constructor. The first parameter,
+the metric name, is required. The second, help, is optional but highly
+recommended. The last two (path-components, and buckets) are optional and will
+default sensibly if omitted.
+
+#### Spring AOP
+
+There is a Spring AOP collector that allows you to annotate methods that you
+would like to instrument with a [Summary](#Summary), but without going through
+the process of manually instaniating and registering your metrics classes. To
+use the metrics annotations, simply add `simpleclient_spring_web` as a
+dependency, annotate a configuration class with `@EnablePrometheusTiming`, then
+annotate your Spring components as such:
+
+```java
+@Controller
+public class MyController {
+  @RequestMapping("/")
+  @PrometheusTimeMethod(name = "my_controller_path_duration_seconds", help = "Some helpful info here")
+  public Object handleMain() {
+    // Do something
+  }
+}
+```
+
 ## Exporting
 
 There are several options for exporting metrics.

pom.xml

@@ -56,6 +56,7 @@
         <module>simpleclient_logback</module>
         <module>simpleclient_pushgateway</module>
         <module>simpleclient_servlet</module>
+        <module>simpleclient_spring_web</module>
         <module>simpleclient_spring_boot</module>
         <module>simpleclient_jetty</module>
         <module>simpleclient_vertx</module>

simpleclient_servlet/pom.xml

@@ -73,5 +73,11 @@
             <version>1.9.5</version>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <version>1.9.5</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 </project>

simpleclient_servlet/src/main/java/io/prometheus/client/filter/MetricsFilter.java

@@ -0,0 +1,181 @@
+package io.prometheus.client.filter;
+
+import io.prometheus.client.Histogram;
+
+import javax.servlet.Filter;
+import javax.servlet.FilterChain;
+import javax.servlet.FilterConfig;
+import javax.servlet.ServletException;
+import javax.servlet.ServletRequest;
+import javax.servlet.ServletResponse;
+import javax.servlet.http.HttpServletRequest;
+import java.io.IOException;
+
+/**
+ * The MetricsFilter class exists to provide a high-level filter that enables tunable collection of metrics for Servlet
+ * performance.
+ *
+ * The Histogram name itself is required, and configured with a {@code metric-name} init parameter.
+ *
+ * The help parameter, configured with the {@code help} init parameter, is not required but strongly recommended.
+ *
+ * By default, this filter will provide metrics that distinguish only 1 level deep for the request path
+ * (including servlet context path), but can be configured with the {@code path-components} init parameter. Any number
+ * provided that is less than 1 will provide the full path granularity (warning, this may affect performance).
+ *
+ * The Histogram buckets can be configured with a {@code buckets} init parameter whose value is a comma-separated list
+ * of valid {@code double} values.
+ *
+ * {@code
+ * <filter>
+ *   <filter-name>prometheusFilter</filter-name>
+ *   <filter-class>net.cccnext.ssp.portal.spring.filter.PrometheusMetricsFilter</filter-class>
+ *   <init-param>
+ *      <param-name>metric-name</param-name>
+ *      <param-value>webapp_metrics_filter</param-value>
+ *   </init-param>
+ *    <init-param>
+ *      <param-name>help</param-name>
+ *      <param-value>The time taken fulfilling servlet requests</param-value>
+ *   </init-param>
+ *   <init-param>
+ *      <param-name>buckets</param-name>
+ *      <param-value>0.005,0.01,0.025,0.05,0.075,0.1,0.25,0.5,0.75,1,2.5,5,7.5,10</param-value>
+ *   </init-param>
+ *   <init-param>
+ *      <param-name>path-components</param-name>
+ *      <param-value>0</param-value>
+ *   </init-param>
+ * </filter>
+ * }
+ *
+ * @author Andrew Stuart &lt;andrew.stuart2@gmail.com&gt;
+ */
+public class MetricsFilter implements Filter {
+    static final String PATH_COMPONENT_PARAM = "path-components";
+    static final String HELP_PARAM = "help";
+    static final String METRIC_NAME_PARAM = "metric-name";
+    static final String BUCKET_CONFIG_PARAM = "buckets";
+
+    private Histogram histogram = null;
+
+    // Package-level for testing purposes.
+    int pathComponents = 1;
+    private String metricName = null;
+    private String help = "The time taken fulfilling servlet requests";
+    private double[] buckets = null;
+
+    public MetricsFilter() {}
+
+    public MetricsFilter(
+            String metricName,
+            String help,
+            Integer pathComponents,
+            double[] buckets
+    ) throws ServletException {
+        this.metricName = metricName;
+        this.buckets = buckets;
+        if (help != null) {
+            this.help = help;
+        }
+        if (pathComponents != null) {
+            this.pathComponents = pathComponents;
+        }
+        this.init(null);
+    }
+
+    private boolean isEmpty(String s) {
+        return s == null || s.length() == 0;
+    }
+
+    private String getComponents(String str) {
+        if (str == null || pathComponents < 1) {
+            return str;
+        }
+        int count = 0;
+        int i =  -1;
+        do {
+            i = str.indexOf("/", i + 1);
+            if (i < 0) {
+                // Path is longer than specified pathComponents.
+                return str;
+            }
+            count++;
+        } while (count <= pathComponents);
+
+        return str.substring(0, i);
+    }
+
+    @Override
+    public void init(FilterConfig filterConfig) throws ServletException {
+        Histogram.Builder builder = Histogram.build()
+                .labelNames("path", "method");
+
+        if (filterConfig == null && isEmpty(metricName)) {
+            throw new ServletException("No configuration object provided, and no metricName passed via constructor");
+        }
+
+        if (filterConfig != null) {
+            if (isEmpty(metricName)) {
+                metricName = filterConfig.getInitParameter(METRIC_NAME_PARAM);
+                if (isEmpty(metricName)) {
+                    throw new ServletException("Init parameter \"" + METRIC_NAME_PARAM + "\" is required; please supply a value");
+                }
+            }
+
+            if (!isEmpty(filterConfig.getInitParameter(HELP_PARAM))) {
+                help = filterConfig.getInitParameter(HELP_PARAM);
+            }
+
+            // Allow overriding of the path "depth" to track
+            if (!isEmpty(filterConfig.getInitParameter(PATH_COMPONENT_PARAM))) {
+                pathComponents = Integer.valueOf(filterConfig.getInitParameter(PATH_COMPONENT_PARAM));
+            }
+
+            // Allow users to override the default bucket configuration
+            if (!isEmpty(filterConfig.getInitParameter(BUCKET_CONFIG_PARAM))) {
+                String[] bucketParams = filterConfig.getInitParameter(BUCKET_CONFIG_PARAM).split(",");
+                buckets = new double[bucketParams.length];
+
+                for (int i = 0; i < bucketParams.length; i++) {
+                    buckets[i] = Double.parseDouble(bucketParams[i]);
+                }
+            }
+        }
+
+        if (buckets != null) {
+            builder = builder.buckets(buckets);
+        }
+
+        histogram = builder
+                .help(help)
+                .name(metricName)
+                .register();
+    }
+
+    @Override
+    public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) throws IOException, ServletException {
+        if (!(servletRequest instanceof HttpServletRequest)) {
+            filterChain.doFilter(servletRequest, servletResponse);
+            return;
+        }
+
+        HttpServletRequest request = (HttpServletRequest) servletRequest;
+
+        String path = request.getRequestURI();
+
+        Histogram.Timer timer = histogram
+            .labels(getComponents(path), request.getMethod())
+            .startTimer();
+
+        try {
+            filterChain.doFilter(servletRequest, servletResponse);
+        } finally {
+            timer.observeDuration();
+        }
+    }
+
+    @Override
+    public void destroy() {
+    }
+}