Skip to content

Observability

Jump to bottom Edit New page
Hans Zandbelt edited this page Jan 30, 2024 · 23 revisions

Since version 2.4.15.1 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.

Metrics

The OIDCMetricsData primitive configures the top level classes of metrics that will be collected.

Classes

authtype        Request counter, overall and per AuthType: openid-connect, oauth20 and auth-openidc.
authn           Authentication request creation and response processing.
authz           Authorization errors per OIDCUnAuthzAction (per Require statement, not overall).
require.claim   Match/failure count of Require claim directives (per Require statement, not overall).
provider        Requests to the provider [token, userinfo, metadata] endpoints.
session         Existing session processing.
cache           Cache read/write timings and errors.
redirect_uri    Requests to the Redirect URI, per type.
content         Requests to the content handler, per type of request: info, metrics, jwks, etc.

Metrics are recorded and published per defined virtual host in Apache. Two types of metrics exists:

  • timers: recorded as a histogram: count, sum and (10) buckets [5000ms-0.1ms]
  • counters: recorded as a cumulative total

Timers

authtype.handler     Histogram of the overall authz+authz processing time.
authn.request        Histogram of authentication requests.
authn.response       Histogram of authentication responses.
session.valid        Histogram of successfully validated existing sessions.
provider.metadata    Histogram of provider discovery document requests.
provider.token       Histogram of provider token requests.
provider.refresh     Histogram of provider refresh token requests.
provider.userinfo    Histogram of provider userinfo requests.
cache.read           Histogram of cache read requests.
cache.write          Histogram of cache write requests.

Counters

authtype.mod_auth_openidc              Nr of requests handled by mod_auth_openidc.
authtype.openid-connect                Nr of requests handled by AuthType openid-connect.
authtype.oauth20                       Nr of requests handled by AuthType oauth20.
authtype.auth-openidc                  Nr of requests handled by AuthType auth-openidc.
authtype.declined                      Nr of requests not handled by mod_auth_openidc.
authn.request.error.url                Nr of errors matching the incoming request URL against the configuration.
authn.response.error.state-mismatch    Nr of state mismatch errors in authentication responses.
authn.response.error.state-expired     Nr of state expired errors in authentication responses.
authn.response.error.provider          Nr of errors returned by the provider in authentication responses.
authn.response.error.protocol          Nr of protocol errors handling authentication responses.
authn.response.error.remote-user       Nr of errors identifying the remote user based on provided claims.
authz.action.auth                      Nr of step-up authentication requests.
authz.action.401                       Nr of 401 authorization errors.
authz.action.403                       Nr of 403 authorization errors.
authz.action.302                       Nr of 302 authorization errors.
authz.error.oauth20                    Nr of AuthType oauth20 (401) authorization errors.
require.claim.match.<claim-value>      Nr of (per-) Require claim authorization matches.
require.claim.error.<claim-value>      Nr of (per-) Require claim authorization errors.
provider.metadata.error                Nr of errors retrieving a provider discovery document.
provider.token.error                   Nr of errors making a token request to a provider.
provider.refresh.error                 Nr of errors refreshing the access token at the token endpoint.
provider.userinfo.error                Nr of errors calling a provider userinfo endpoint.
provider.http.connect.error.<string>   Nr of (libcurl) provider/network connectivity errors.
provider.http.response.code.<code>     Nr of HTTP response code calling a provider endpoint.
session.error.cookie-domain            Nr of cookie domain validation errors for existing sessions.
session.error.expired                  Nr of sessions that exceeded the maximum duration.
session.error.refresh-access-token     Nr of errors refreshing the access token before expiry in existing sessions.
session.error.refresh-user-info        Nr of errors refreshing claims from the userinfo endpoint in existing sessions.
session.error.general                  Nr of existing sessions that failed validation.
cache.cache.error                      Nr of cache read/write errors.
redirect_uri.authn.response.redirect   Nr of authentication responses received in a redirect.
redirect_uri.authn.response.post       Nr of authentication responses received in a HTTP POST.
redirect_uri.authn.response.implicit   Nr of (presumed) implicit authentication responses to the redirect URI.
redirect_uri.discovery.response        Nr of discovery responses to the redirect URI.
redirect_uri.request.logout            Nr of logout requests to the redirect URI.
redirect_uri.request.jwks              Nr of JWKs retrieval requests to the redirect URI.
redirect_uri.request.session           Nr of session management requests to the redirect URI.
redirect_uri.request.refresh           Nr of refresh access token requests to the redirect URI.
redirect_uri.request.request_uri       Nr of Request URI calls to the redirect URI.
redirect_uri.request.remove_at_cache   Nr of access token cache removal requests to the redirect URI.
redirect_uri.request.session           Nr of revoke session requests to the redirect URI.
redirect_uri.request.info              Nr of info hook requests to the redirect URI.
redirect_uri.error.provider            Nr of provider authentication response errors received at the redirect URI.
redirect_uri.error.invalid             Nr of invalid requests to the redirect URI.
content.request.declined               Nr of requests declined by the content handler.
content.request.info                   Nr of info hook requests to the content handler.
content.request.jwks                   Nr of JWKs requests to the content handler.
content.request.discovery              Nr of discovery requests to the content handler.
content.request.post-preserve          Nr of HTTP POST preservation requests to the content handler.
content.request.unknown                Nr of unknown requests to the content handler.

Collection

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 192.168.0.200:8080>
  OIDCMetricsPublish  /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: <counter-value> by retrieving a specific counter in the provided server_name=<vhost>&counter=<name>[&spec=<value>] 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 on / with Require claim sub:<value> for user specific access count in oidc_require_claim_match[value="sub:<value>"]

Add a custom footer
Add a custom sidebar
Clone this wiki locally