Filter probes
Filter probes are just normal filters in defined in the Magnolia filter chain (see Request processing and filters for more). Filters are executed in the order they are defined in the filter chain. Filter probes are able to collect their metrics from the point they are defined in the filter chain.
There are two types of filter probes:
-
filter probes that measure execution time of requests
-
filter probes that count requests
Available filter probes
-
SimpleCounterFilterProbe: maintains a count of requests being processed
-
SimplePassthroughFilterProbe: measures the processing time to handle a request
-
SimpleSummaryPassthroughFilterProbe: maintains a histogram of the processing times for requests
-
SimpleFilterSequenceProbe: measures the processing time between two points in the filter chain
-
CounterFilterProbe: maintains a count of requests being processed with the request details as labels
-
PassthroughFilterProbe: measures the processing time to handle a request with the request details as labels
-
SummaryPassthroughFilterProbe: maintains a histogram of the processing times for request with the request details as labels
-
FilterSequenceProbe: measures the processing time between two points in the filter chain
-
ServletContextProbe: captures information about the servlet context
Using Filter Probes
The filter chain is the heart of Magnolia’s request processing. While filter probes don’t use a lot of system resources in making their measurements, adding many filter probes to the filter chain may affect Magnolia’s ability to process requests.
Prometheus and Grafana can also post-process measurements collected by filter probes. You can make queries to pull larges amounts of request measurements into dashboards that can affect Prometheus and Grafana performance.
Here are some recommendations to keep in mind when using filter probes.
If you are not interested in the request details such as URI, URL or request method, use the "simple" versions of the filter probes - SimpleCounterFilterProbe, SimplePassthroughFilterProbe, SimpleSummaryPassthroughFilterProbe or SimpleFilterSequenceProbe - since these probes do not collect the request details.
If you do want the request details when using CounterFilterProbe, PassthroughFilterProbe, SummaryPassthroughFilterProbe or FilterSequenceProbe, try to limit the labels collected to just what is needed.
If you want to monitor requests to specific URLs, use voters to limit the requests monitored by filter probes.
Limiting Filter Probes
All filter probes can use voters to limit the requests that are measured. Voters can check the attributes of a request to see if it should be measured by a filter probe, including:
-
The request URI
-
The user agent
-
Request headers
-
Request parameters
You can also use logical operations to combine the results of several voters. |
You can configure voters in a filter probe like this:
SimpleCounterFilterProbe
SimpleCounterFilterProbe counts the total number of requests received or the current number of active requests.
SimpleCounterFilterProbe does not add any labels to its measurements; use CounterFilterProbe if you want to add labels based on request attributes to measurements.
Configuration properties
Property | Description | Required | ||
---|---|---|---|---|
|
|
|||
|
The name of the filter.
|
|||
|
Enable or disable the collection of filter metrics for this probe. Default = |
|||
|
The metric name, must be unique among all active probes. |
|||
|
||||
|
A list of request voters. Requests matching the voters will be measured by the filter probe. Those requests that do not will be ignored.
|
|||
|
Maintain a total of all requests seen or a running tally of active requests.
Default = |
SimplePassthroughFilterProbe
SimplePassthroughFilterProbe measures the time taken for all filters after the filter probe to execute.
SimplePassthroughFilterProbe does not add any labels to its measurements; use PassthroughFilterProbe if you want to add labels based on request attributes to measurements.
Configuration properties
Property | Description | Required | ||
---|---|---|---|---|
|
|
|||
|
The name of the filter.
|
|||
|
Enable or disable the collection of filter metrics for this probe. Default = |
|||
|
The metric name, must be unique among all active probes. |
|||
|
||||
|
A list of request voters. Requests matching the voters will be measured by the filter probe. Those requests that do not will be ignored.
|
|||
|
Maintain a total of all requests seen or a running tally of active requests.
Default = |
SimpleSummaryPassthroughFilterProbe
SimpleSummaryPassthroughFilterProbe collects a distribution of the times taken for all filters after the filter probe to execute. While Prometheus queries and functions can compute histograms of measurements, SimpleSummaryPassthroughFilterProbe may be faster in generating a histogram.
SimpleSummaryPassthroughFilterProbe does not add any labels to its measurements; use SummaryPassthroughFilterProbe if you want to add labels based on request attributes to measurements.
Configuration properties
Property | Description | Required | ||
---|---|---|---|---|
|
|
|||
|
The name of the filter.
|
|||
|
Enable or disable the collection of filter metrics for this probe. Default = |
|||
|
The metric name, must be unique among all active probes. |
|||
|
||||
|
A list of request voters. Requests matching the voters will be measured by the filter probe. Those requests that do not will be ignored.
|
|||
|
Maintain a total of all requests seen or a running tally of active requests.
Default = |
SimpleFilterSequenceProbe
SimpleFilterSequenceProbe measures the processing time taken by one or more following filters, though not necessarily the entire remaining filter chain.
SimpleFilterSequenceProbe uses a filter timer trigger to record the processing time.
Suppose you have the following sequence of filters configured:
-
(other filters…)
-
SimpleFilterSequenceProbe
-
FilterA
-
FilterB
-
FilterTimerTrigger
-
(more filters…)
When executed, SimpleFilterSequenceProbe starts a timer, FilterA and FilterB are executed. When FilterTimeTrigger is reached, the timer is stopped and the measurement is recorded.
If you don’t configure a FilterTimerTrigger, SimpleFilterSequenceProbe will stop the timer after the request has been processed by all remaining, but this is the same as, and less efficient as, using SimplePassthroughFilterProbe.
SimpleFilterSequenceProbe does not add any labels to its measurements; use FilterSequenceProbe if you want to add labels based on request attributes to measurements.
See Filter timer triggers below for more on setting up FilterTimerTriggers. |
Configuration properties
Property | Description | Required | ||
---|---|---|---|---|
|
|
|||
|
The name of the filter.
|
|||
|
Enable or disable the collection of filter metrics for this probe. Default = |
|||
|
The metric name, must be unique among all active probes. |
|||
|
||||
|
The attribute name of the timer added to the request. The attributeName should be unique. The attribute name is used to store the timer in the request. It should be used in the configuration of the corresponding FilterTimerTrigger. |
|||
|
A list of request voters. Requests matching the voters will be measured by the filter probe. Those requests that do not will be ignored.
|
Measurements with request labels
The simple filter probes - SimpleCounterFilterProbe, SimplePassthroughFilterProbe, SimpleSummaryFilterProbe and SimpleFilterSequenceProbe - do not add any additional information to their measurements as labels. There are versions of these probes - namely: CounterFilterProbe, PassthroughFilterProbe, SummaryFilterProbe and FilterSequenceProbe - that make the same measurements but also allow you to add request attributes as labels. The labels can be used to distinguish or aggregate measurements based on the request URI, request method or HTTP status, among others.
You can specify the name used for the label by configuring the label property.
The following request attributes can be added as labels to a measurement:
- RequestMethodLabelValue - the HTTP request method
-
class:
info.magnolia.services.instrumentation.probes.labels.RequestMethodLabelValue
Adds the HTTP request method, either GET, PUT or POST.
The label value is determined by javax.servlet.http.HttpServletRequest.getMethod()
.
- RequestURILabelValue - the HTTP request URI
-
class:
info.magnolia.services.instrumentation.probes.labels.RequestURILabelValue
Adds the HTTP request URI.
The label value is determined by javax.servlet.http.HttpServletRequest.HttpServletRequest.getRequestURI()
.
- RequestURLLabelValue - the HTTP request URL
-
class:
info.magnolia.services.instrumentation.probes.labels.RequestURLLabelValue
Adds the HTTP request URL.
The label value is determined by javax.servlet.http.HttpServletRequest.HttpServletRequest.getRequestURL().toString()
.
- StatusLabelValue - the HTTP request status
-
class:
info.magnolia.services.instrumentation.probes.labels.StatusLabelValue
Adds the HTTP request URL.
The label value is determined by javax.servlet.http.HttpServletResponse.getStatus()
.
You can configure one or more request labels to CounterFilterProbe , PassthroughFilterProbe , SummaryFilterProbe and FilterSequenceProbe by configuring the labels property:
|
CounterFilterProbe
Counts the total number of requests received or the current number of active requests.
CounterFilterProbe adds labels to its measurements based on its labels configuration; use SimpleCounterFilterProbe if you don’t want to add labels based on request attributes to measurements.
Configuration properties
Property | Description | Required | ||
---|---|---|---|---|
|
|
|||
|
The name of the filter.
|
|||
|
Enable or disable the collection of filter metrics for this probe. Default = |
|||
|
The metric name, must be unique among all active probes. |
|||
|
A description of the metric. |
|||
|
A list of request voters. Requests matching the voters will be measured by the filter probe. Those requests that do not will be ignored.
|
|||
|
The measurement labels as described above. |
|||
|
Maintain a total of all requests seen or a running tally of active requests.
Default = |
PassthroughFilterProbe
PassthroughFilterProbe measures the time taken for all filters after the filter probe to execute.
PassthroughFilterProbe adds labels to its measurements as configured; use SimplePassthroughFilterProbe if you don’t need to add labels based on request attributes to measurements.
Configuration properties
Property | Description | Required | ||
---|---|---|---|---|
|
|
|||
|
The name of the filter.
|
|||
|
Enable or disable the collection of filter metrics for this probe. Default = |
|||
|
The metric name, must be unique among all active probes. |
|||
|
A description of the metric. |
|||
|
A list of request voters. Requests matching the voters will be measured by the filter probe. Those requests that do not will be ignored.
|
SummaryPassthroughFilterProbe
SummaryPassthroughFilterProbe collects a distribution of the times taken for all filters after the filter probe to execute. While Prometheus queries and functions can compute histograms of measurements, SummaryPassthroughFilterProbe may be faster in generating a histogram.
SummaryPassthroughFilterProbe does not add any labels to its measurements; use SimpleSummaryPassthroughFilterProbe if you don’t need to add labels based on request attributes to measurements.
Configuration properties
Property | Description | Required | ||
---|---|---|---|---|
|
|
|||
|
The name of the filter.
|
|||
|
Enable or disable the collection of filter metrics for this probe. Default = |
|||
|
The metric name, must be unique among all active probes. |
|||
|
A description of the metric. |
|||
|
A list of request voters. Requests matching the voters will be measured by the filter probe. Those requests that do not will be ignored.
|
FilterSequenceProbe
FilterSequenceProbe measures the processing time taken by one or more following filters, though not necessarily the entire remaining filter chain.
FilterSequenceProbe uses a filter timer trigger to record the processing time.
Suppose you have the following sequence of filters configured:
-
(other filters…)
-
FilterSequenceProbe
-
FilterA
-
FilterB
-
FilterTimerTrigger
-
(more filters…)
When executed, FilterSequenceProbe starts a timer, FilterA and FilterB are executed. When FilterTimeTrigger is reached, the timer is stopped and the measurement is recorded.
If you don’t configure a FilterTimerTrigger, FilterSequenceProbe will stop the timer after the request has been processed by all remaining filters, but this is the same as, and less efficient as, using SimplePassthroughFilterProbe.
See Filter timer triggers below for more on setting up FilterTimerTriggers. |
FilterSequenceProbe adds labels to its measurements as configured; use SimpleFilterSequenceProbe if you don’t need to add labels based on request attributes to measurements.
Configuration properties
Property | Description | Required | ||
---|---|---|---|---|
|
|
|||
|
The name of the filter.
|
|||
|
Enable or disable the collection of filter metrics for this probe. Default = |
|||
|
The metric name, must be unique among all active probes. |
|||
|
||||
|
The attribute name of the timer added to the request. The attributeName should be unique. The attribute name is used to store the timer in the request. It should be used in the configuration of the corresponding FilterTimerTrigger. |
|||
|
A list of request voters. Requests matching the voters will be measured by the filter probe. Those requests that do not will be ignored.
|
Filter timer triggers
The filter sequence probes SimpleFilterSequenceProbe and FilterSequenceProbe use a FilterTimerTrigger to measure the processing time across one or more filters.
A FilterTimerTrigger isn’t a probe, it simply stops a timer started by SimpleFilterSequenceProbe or FilterSequenceProbe.
Each filter sequence probe you set up in the filter chain should have a corresponding FilterTimerTrigger defined immediately after the filters you want to measure.
Here’s how to configure a FilterTimerTrigger.
Configuration properties
Property | Description | Required | ||
---|---|---|---|---|
|
|
|||
|
The name of the filter.
|
|||
|
Enable or disable the filter trigger. Default = |
|||
|
The name of the timer added to the request by SimpleFilterSequenceProbe or FilterSequenceProbe. The timerAttribute must be formatted as follows: <filter sequence probe class name>.<filter sequence probe attribute name> Filter sequence probe class name is the fully qualified class name of the probe that starts the timer, either
|
ServletContextProbe
ServletContextProbe collects information about the servlet context Magnolia is running in, including:
-
the context path
-
the major version number of the Servlet specification supported by the context
-
the minor version number of the Servlet specification supported by the context
-
the server info
-
the servlet context name
The servlet context information above is recorded as labels. The value of the metric is always 1
.
Since the servlet context information does not change while Magnolia is running, the servlet context information is collected once, from the first request arriving at the ServletContextProbe. Subsequent requests to ServletContextProbe will not capture the servlet context information and the request will just be passed along the filter chain.
ServletContextProbe should be positioned early in the filter chain. ServletContextProbe also supports use of voters to restrict requests received by the probe, however, since the servlet context information collected does not change between requests, using voters may delay the collection of the servlet context information.
Configuration properties
Property | Description | Required | ||
---|---|---|---|---|
|
|
|||
|
The name of the filter.
|
|||
|
Enable or disable the collection of filter metrics for this probe. Default = |
|||
|
The metric name, must be unique among all active probes. |
|||
|
A description of the metric. |
|||
|
A list of request voters. Requests matching the voters will be measured by the filter probe. Those requests that do not will be ignored.
|
Labels
Label | Metric | Description |
---|---|---|
|
<metric-name> |
The context path returned by |
|
<metric-name> |
The major version number of the Java Servlet specification supported by the servlet container. The value is returned by |
|
<metric-name> |
The minor version number of the Java Servlet specification supported by the servlet container. The value is returned by |
|
<metric-name> |
The name and version of the servlet container on which Magnolia is running. The form of the returned string is servername/versionnumber. For example, the JavaServer Web Development Kit may return the string JavaServer Web Dev Kit/1.0. The servlet container may return other optional information after the primary string in parentheses, for example, JavaServer Web Dev Kit/1.0 (JDK 1.1.6; Windows NT 4.0 x86). The value is returned by |
|
<metric-name> |
The name of the Magnolia web application corresponding to this ServletContext as specified in the deployment descriptor for this web application by the display-name element. The value is returned by |