Monitoring With the 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.

Tip

The default username and password for Grafana is admin and admin.

To set up a Grafana dashboard with IDM metrics using Prometheus, add your Prometheus installation to Grafana, as a data source. Select Configuration > Data Sources from the left navigation panel in Grafana, then select 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.

Give your data source a name, in this case, ForgeRockIDM.
Select Prometheus as the type.
Set the URL (by default, http://localhost:9090).
Set Access to proxy.
Enable Basic Auth.
Set a username and password of prometheus and prometheus.
Select Save & then 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, select Home > Import and import the noted file.
- Select Create > Dashboard.
- Select Graph.
- Select Panel Title > Edit.
  Enter the metrics you want to display (which will be available in autocomplete as you type), or build more complex queries using the Prometheus query language.

To display a Grafana chart directly in IDM, create a new dashboard in the Admin UI. Configure the dashboard to be an Embedded URL and set the URL to your Grafana installation (http://localhost:3000 by default).