Skip to content

Monitoring Installation & Setup

Monitoring needs two open-source packages beside IMan:

  1. Prometheus, which scrapes the metrics the WebAPI publishes and keeps them in a time-series database.
  2. Grafana, which draws them.

This page installs both on the IMan server itself, on Windows.

What the WebAPI publishes

The WebAPI serves its metrics at /IManWebAPI/metrics, in the Prometheus text format, two series per endpoint, method and status code:

  • realisable_webapi_request_total, a counter of requests;
  • realisable_webapi_request_time, a histogram of response times in milliseconds.

The route requires a bearer token from the IMan Authorisation Service, the same kind an OAuth web user obtains, so Prometheus has to be able to fetch one. Create a web user with the authentication type oAuth 2.0 for Prometheus and keep its Client Id and Client Secret for the configuration below. The user does not need to be assigned to any endpoint.

Prometheus installation and configuration

  1. Download Prometheus. There is no installer for Windows: unblock the zip and unzip it where you want it.

  2. Open prometheus.yml in the root of the unzipped folder and add a job for the WebAPI under scrape_configs. The scrape goes over HTTPS with the token the oauth2 block fetches; insecure_skip_verify is only for a self-signed certificate.

    scrape_configs:
  - job_name: "webapi"
    metrics_path: /IManWebAPI/metrics
    scheme: https
    static_configs:
      - targets: ["imanserver"]
    oauth2:
      client_id: "<the web user's Client Id>"
      client_secret: "<its Client Secret>"
      token_url: https://imanserver:44390/connect/token
      scopes: ["httpListener_scope"]
      tls_config:
        insecure_skip_verify: true
    tls_config:
      insecure_skip_verify: true

  3. Run prometheus.exe from that folder. Prometheus must be running for anything to be collected.

    A console window running prometheus.exe, logging that it has loaded its configuration and is listening on port 9090

  4. For a production server run it as a Windows service, with a wrapper such as AlwaysUp.

Prometheus's own page at http://localhost:9090/targets shows the scrape and its last error, which is the place to look when the dashboard stays empty: a 401 there means the token was refused.

Grafana installation and configuration

Download and install Grafana following the instructions on that page.

Data sources

Grafana needs two: Prometheus, for the metrics, and a SQL Server connection to the IMan database, from which the dashboard lists the endpoints.

Prometheus

  1. Open Grafana at http://localhost:3000 and sign in. The initial user and password are both admin; Grafana asks for a new password at once.

  2. Open the Data sources menu.

    Grafana's left-hand menu with Configuration expanded and Data sources highlighted

  3. Add a Prometheus data source.

    The Add data source page with Prometheus at the top of the list and its Select button

  4. The one setting that matters is the URL. With Prometheus on the same server and its defaults, http://localhost:9090 is right.

    The Prometheus data source settings with the URL http://localhost:9090

  5. Press Save & Test.

    The Save & Test button with the message Data source is working

IMan SQL Server

  1. Add a Microsoft SQL Server data source; the SQL sources are two thirds of the way down the list.

    The Add data source page scrolled to the SQL section, with Microsoft SQL Server and its Select button

  2. Set the host, the IMan database and the authentication.

    The Microsoft SQL Server data source settings: Host, Database, User and Password

  3. Save & Test.

Importing the IMan dashboard

A ready-made dashboard ships with IMan.

  1. From the left-hand menu choose Add, then Import.

    Grafana's Add menu with Import highlighted

  2. Press Upload JSON File and choose C:\IMan\config\Realisable-WebAPI-Dashboard.json.

    The Import page with the Upload JSON file button

  3. Select the SQL Server data source created above.

    The import options with the SQL Server data source selected for the dashboard's endpoint list

  4. Press Import. The dashboard opens, and Monitoring WebAPI describes it.