The Shibboleth IdP V4 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only. See the IDP5 wiki space for current documentation on the supported version.
MetricsConfiguration
Current File(s): conf/admin/metrics.xml, conf/admin/general-admin.xml (V4.0), conf/admin/admin.properties (V4.1+), conf/logback.xml
Format: Native Spring, Logback, Properties (V4.1+)
Overview
The IdP includes a framework for instrumentation, diagnostics, and performance management that complements the logging support and integrates with it to allow tuning of instrumentation overhead. The framework is based on the Metrics library and includes a number of related features:
some built-in metrics providing low-level system information, software versions, etc.
a small number of built-in metrics exposed by the IdP itself, including a customizeable set of configuration properties
a facillity for installing timers and counters to measure request handling
an API for accessing metrics (all or a subset) in JSON format
the ability to schedule reports of metrics in JSON format out to an http(s) collection point
Most of these features are configured whole or in part via conf/admin/metrics.xml and are discussed below.
General Configuration
The core bean in the metric system is a MetricRegistry that stores all of the active metrics in the system for use by various other reporting objects. Certain kinds of metrics are subject to your control and can be selectively installed or skipped based on what gets registered, at startup. By default various sets of metrics are installed for you via a bean in metrics.xml that inherits from shibboleth.metrics.RegisterMetricSets, which is a way of using Spring to call the registration method. The pre-installed metrics largely overlap with the information available from the now-deprecated status page.
Also provided by default, but commented out, are references to a number of lower level metric sets related to the JVM.
The way to think about these particular metrics is that they're "external" to the IdP for the most part, in the sense that they're objects that access public interfaces of IdP, OpenSAML, and Java components, and use them to report information. Because they're external, they can be selectively installed (or not) just by registering them (or not).
A lot of the other interesting metrics in the system are "internal", in the sense that they're implemented either wholly, or in conjunction with, internal classes themselves, and typically are not something you specifically need to register yourself. Instead, you have the ability to enable or disable all metrics using a MetricFilter.
Logger-Driven Filtering
The registry of metrics is extended by Shibboleth with the ability to "filter" metrics by reusing the logging configuration's ability to adjust the logging level of particular categories hierarchically. By naming metrics in a similar way, it's possible to effectively enable and disable metrics at runtime, which can have very small (or in rare cases, less small) impacts on performance. You may want to leave a metric configured all the time, but toggle it on only at particular times. Using the logging layer is easy, flexible, reloadable, and ignorable if you don't care about the overhead.
Every metric has a name in dotted-separator notation (i.e., the same as a logging category) and you can control the on/off status of a particular metric or set of metrics by manipulating the level of a corresponding logging category with the prefix "metrics." That is, a metric named "net.shibboleth.idp.version" is controlled by a logging category named "metrics.net.shibboleth.idp.version".
By default, all metrics are enabled at the "INFO" level.
Reporting
There are two built-in mechanisms provided for reporting out metrics, along with a variety of options available within the Metrics library itself that deployers may choose to wire in with Spring. For example, it's possible to expose metrics via JMX, through logging, via the console, to databases, etc.
The two generic approaches that come "ready to deploy" are both centered around use of JSON as a reporting format, and both pull (via a REST API) and push (via an HTTP reporter) are provided.