Observability

Since version 2.4.15 mod_auth_openidc allows for collection and retrieval of a number of metrics that are designed to be used in systems monitoring and alerting tools such as Prometheus.

Measurements

The OIDCMetricsData primitive configures the top level classes of metrics that will be collected. Supported metric classes are:

• authtype
  the authentication handler type split out per AuthType: openid-connect, oauth20 and auth-openidc
• authn
  authentication request generation and response processing
• authz
  authorization errors per OIDCUnAuthzAction (per Require statement, not overall)
• require.claim
  matches/errors count of Require claim directives (per Require statement, not overall)
• requests
  requests to the provider endpoints (metadata retrieval, token request, refresh requests and userinfo requests)
• session
  existing session handling
• cache
  cache read/write/errors
• redirect_uri
  requests to the Redirect URI
• content
  requests to the content handler, split out per types of request (info, metrics, jwks, etc.)

[The detailed list of all metrics with their description will be included here when ready for final release in 2.4.15]

Types

Two types of metrics exists, counters, recorded as a simple number and timings, recorded as a histogram.

Process

The measurements are recorded per virtual host in a local in-memory hash table for performance reasons. The local data is flushed to shared memory in a dedicated thread that runs every 5 seconds per virtual host. Notice that any data consumed on OIDCMetricsPublish is therefore max 5 seconds behind. The shared memory is shared between all of the virtual hosts configured on the same Apache instance. Retrieval of the data on OIDCMetricsPublish returns and resets the counters/timings for all virtual hosts.

Retrieval

The OIDCMetricsPublish primitive configures where the data is published. This URL may contain sensitive data and can be protected by any available Apache mechanism (including e.g. AuthType oauth20). This can be done as part of the virtual host that runs mod_auth_openidc but one may also define a separate virtual host in the same Apache server to publish the data, e.g.:

<VirtualHost _default_:8443>
  SSLEngine on	
  OIDCMetricsPublish  /_mod_auth_openidc/metrics
  Require ip 192.168
</VirtualHost>

Data can be retrieved in a number of formats (see below), using the format query parameter. The format-specific default setting whether or not counters/timings are reset on retrieval can be overruled using the parameter reset with values true|false.

Formats

The URL configured in OIDCMetricsData returns the collected metrics data in a specified format, passed in the format=<value> query parameter. The folowing formats are supported, listed with their reset setting default:

• format=prometheus&reset=true (default)
  the Prometheus text-based exposition format
• format=json&reset=true
  JSON a custom extended JSON format with descriptions and labels
• format=status&reset=false
  Status a short text response containing a single OK line, meant to be using in monitoring/uptime tools such as Nagios, optionally extended to "OK: <value" by retrieving a specific counter in the provided server=<vhost>&counter=<name> parameters.
• format=internal&reset=false
  Internal a terse internal JSON-based representation of the data that is stored in shared memory, without textual labels or descriptions, only used for debugging

Advanced

Use RequireAny with Require claim <sub> for user specific access count.