Monitoring configuration

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:


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


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


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.


Enables / disables monitoring via JMX.

monitor.enableJMX = false

3. Graphite reporting

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


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

monitor.graphite.enable = true

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


The Carbon server port number.

monitor.graphite.port = 2003


The reporting interval, in seconds.

monitor.graphite.reportInterval = 60


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


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


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

monitor.graphite.ratesTimeUnit = SECONDS


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

monitor.graphite.durationsTimeUnit = MILLISECONDS


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.*