IDM 7.2.2

Monitoring

IDM includes the following tools for monitoring metrics:

  • A Dropwizard dashboard widget, for viewing metrics within IDM.

  • A Prometheus endpoint, for viewing metrics through external resources such as Prometheus and Grafana.

The tool that you choose will depend on the metrics you monitor and on what you plan to use the metrics for.

IDM does not gather metrics by default. To enable metrics gathering, open conf/metrics.json and set the enabled property to true.

To verify that metrics are successfully enabled, run:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
'http://localhost:8080/openidm/metrics/api?_queryFilter=true'

If you have enabled metrics, this command returns information about the metrics that are being collected. Otherwise, the command returns a bad request response.

Metrics are reported only after they have been triggered by activity in IDM, such as a reconciliation.

For a list of available metrics, see Metrics reference.

Dropwizard widget

The Dropwizard widget creates a graph of metrics based on server activity.

To add the Dropwizard widget, click Add Widget on any Dashboard in the admin UI, and select Dropwizard Table with Graph from the list.

The Dropwizard widget is useful for lightweight, live monitoring of IDM; however, it has a few limitations:

  • The graphs created by the widget do not persist; they are restarted if you reload or navigate away from the page.

  • The widget only works with time-based metrics (other forms of metrics are not displayed in the widget).

Prometheus endpoint

Prometheus is a third-party tool used for gathering and processing monitoring data. Prometheus uses the openidm/metrics/prometheus endpoint to gather information. This endpoint is protected by a basic authentication filter, using the following credentials, set in the resolver/boot.properties file:

openidm.prometheus.username=username
openidm.prometheus.password=password

This section describes how to install Prometheus and Grafana to collect IDM metrics. These third-party tools are not supported by ForgeRock. For more information running Prometheus, see the Prometheus documentation.

Configure Prometheus

You must configure Prometheus using a prometheus.yml configuration file. For more information, see the Prometheus configuration documentation. An example prometheus.yml file would be:

global:
  scrape_interval: 15s
  external_labels:
    monitor: 'my_prometheus'

# https://prometheus.io/docs/operating/configuration/#scrape_config
scrape_configs:
  - job_name: 'openidm'
    scrape_interval: 15s
    scrape_timeout: 5s
    metrics_path: 'openidm/metrics/prometheus'
    scheme: http
    basic_auth:
      username: 'prometheus'
      password: 'prometheus'
    static_configs:
      - targets: ['localhost:8080']

This example configures Prometheus to poll the IDM endpoint every 5 seconds (scrape_interval: 5s), receiving metrics in a plain text format (_fields: ['text'] and _mimeType: ['text/plain;version=0.0.4']). For more information about reporting formats, see the Prometheus documentation on Exposition Formats. Use curl to validate that this configuration returns the expected results:

curl \
--user prometheus:prometheus \
--header "Accept-API-Version: resource=1.0" \
--request GET \
'http://localhost:8080/openidm/metrics/prometheus'

Start Prometheus with your prometheus.yml configuration file by running:

prometheus --config.file=/path/to/prometheus.yml

You can confirm that Prometheus is gathering data from IDM by navigating to the Prometheus monitoring page (by default, http://localhost:9090).

Configure Grafana

Prometheus lets you monitor and process information provided by IDM. If you need deeper analytics, you can use tools such as Grafana to create customized charts and graphs based on Prometheus data. For information on installing and running Grafana, see the Grafana website.

The default username and password for Grafana are both admin.

To set up a Grafana dashboard with IDM metrics using Prometheus, add your Prometheus installation to Grafana, as a data source. Click Configuration > Data Sources from the left navigation panel in Grafana, and click Add Data Source.

Complete the options on the Add Data Source screen. The options in this list match the settings in the monitoring.dashboard.json file.

  1. Give your data source a name, in this case, ForgeRockIDM.

  2. Set the Type to Prometheus.

  3. Set the URL (by default, http://localhost:9090).

  4. Set Access to Server (default).

  5. Enable Basic Auth.

  6. Set a username and password of prometheus.

  7. Click Save, and click Test Connection. If the configuration succeeds, you’ll see the following message: "Data source is working."

When Prometheus has been set up as a data source in Grafana, you can create a dashboard with IDM metrics. Create a dashboard in one of the following ways:

  • Download the Monitoring Dashboard Samples from the ForgeRock BackStage download site. Find monitoring.dashboard.json in the downloaded .zip file. In the Grafana administrative screen, click Home > Import, and import the noted file.

  • Click Create > Dashboard.

    1. Click Graph.

    2. Click Panel Title > Edit.

    3. Enter the metrics to display (which will be available in autocomplete as you type), or build more complex queries using the Prometheus query language.