Monitoring

The Connect2id server provides a monitoring endpoint with over 100 metrics and a number of backend database health checks. These are implemented with help of the Dropwizard Metrics library.

The metrics can also be reported via JMX or Graphite to a remote metrics collection and visualisation server.

The monitor endpoint has its configuration in the following file:

WEB-INF/monitor.properties

Any property in the configuration file can be overridden with a Java system property, e.g. by setting the optional -D argument at JVM startup:

-Dmonitor.apiAccessTokenSHA256=cca68b8b82bcf0b96cb826199429e50cd95a042f8e8891d1ac56ab135d096633

The external configuration guide has tips for setting system properties from environment variables, local files and other locations.

1. Web API

monitor.apiAccessTokenSHA256

The access token for the monitor endpoint, represented by its SHA-256 hash (in hexadecimal format). The hashed storage is intended to prevent accidental leakage of the token through configuration files, logs, etc. The token is of type Bearer, non-expiring and must contain at least 32 random alphanumeric characters to make brute force guessing impractical. If not specified the web API will be disabled.

The hash for a token with value ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6:

monitor.apiAccessTokenSHA256=cca68b8b82bcf0b96cb826199429e50cd95a042f8e8891d1ac56ab135d096633

monitor.secondaryAPIAccessTokenSHA256

Optional secondary access token for the monitor endpoint. Has the same format as monitor.apiAccessTokenSHA256. Must not be set if not needed.

The secondary token can be used by a load balancer to monitor the health check of the Connect2id server.

monitor.secondaryAPIAccessTokenSHA256=304b07b6d8eb155a957b965831be9ce39fb098554a2d5f2047ee0a0491022dea

2. JMX reporting

Controls metrics reporting via JMX.

monitor.enableJMX

Enables / disables monitoring via JMX.

monitor.enableJMX=false

3. Graphite reporting

Controls metrics reporting via Graphite to a remote metrics collection and visualisation server.

monitor.graphite.enable

Enables / disables metrics reporting to a Carbon server (component of the Graphite system).

monitor.graphite.enable=true

monitor.graphite.host

The Carbon server host name / IP address where the metrics will be streamed.

monitor.graphite.host=graphite.example.com

monitor.graphite.port

The Carbon server port number.

monitor.graphite.port=2003

monitor.graphite.reportInterval

The reporting interval, in seconds.

monitor.graphite.reportInterval=60

monitor.graphite.batchSize

Set to a positive integer to enable metrics batching using the Graphite pickle protocol. If set to zero batching is disabled, implying use of the Graphite plaintext protocol. Note that the pickle and plaintext protocols typically require a different port number.

monitor.graphite.batchSize=0

monitor.graphite.prefix

Optional prefix for the metrics. May be used to prepend an API key and / or to specify a name for the Connect2id server node in a cluster.

To specify an API key for each streamed metrics packet:

monitor.graphite.prefix=999d98bd-d745-4255-9f02-a3eec57c3fe5

To specify an API key and a base name for Connect2id server node:

monitor.graphite.prefix=999d98bd-d745-4255-9f02-a3eec57c3fe5.c2id_node1

monitor.graphite.ratesTimeUnit

The time unit for reporting rates. Specified as Java TimeUnit enum constants.

monitor.graphite.ratesTimeUnit=SECONDS

monitor.graphite.durationsTimeUnit

The time unit for reporting durations. Specified as Java TimeUnit enum constants.

monitor.graphite.durationsTimeUnit=MILLISECONDS

monitor.graphite.filter

White list of metric names to report to the Carbon server, with optional wild cards. To report all metrics set the filter value to an asterisk *. More than one filter card may be specified.

To send all available metrics:

monitor.graphite.filter=*

To send only those metrics that relate to the token and user endpoint of the Connect2id server:

monitor.graphite.filter.1=tokenEndpoint.*
monitor.graphite.filter.2=userInfoEndpoint.*

You can also specify absolute metric names (no wild card):

monitor.graphite.filter.1=op.idTokenIssues
monitor.graphite.filter.2=tokenEndpoint.*
monitor.graphite.filter.3=userInfoEndpoint.*