Merge pull request #6741 from QuantamHD/prometheus_integration

utl: Adds live prometheus monitoring to OpenROAD

etc/monitoring/README.md

@@ -0,0 +1,65 @@
+## Compose sample
+### Prometheus & Grafana
+
+Project structure:
+```
+.
+├── compose.yaml
+├── grafana
+│   └── datasource.yml
+├── prometheus
+│   └── prometheus.yml
+└── README.md
+```
+
+[_compose.yaml_](compose.yaml)
+```
+services:
+  prometheus:
+    image: prom/prometheus
+    ...
+    ports:
+      - 9090:9090
+  grafana:
+    image: grafana/grafana
+    ...
+    ports:
+      - 3000:3000
+```
+The compose file defines a stack with two services `prometheus` and `grafana`.
+When deploying the stack, docker compose maps port the default ports for each service to the equivalent ports on the host in order to inspect easier the web interface of each service.
+Make sure the ports 9090 and 3000 on the host are not already in use.
+
+## Deploy with docker compose
+
+```
+$ docker compose up -d
+Creating network "prometheus-grafana_default" with the default driver
+Creating volume "prometheus-grafana_prom_data" with default driver
+...
+Creating grafana    ... done
+Creating prometheus ... done
+Attaching to prometheus, grafana
+
+```
+
+## Expected result
+
+Listing containers must show two containers running and the port mapping as below:
+```
+$ docker ps
+CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                    NAMES
+dbdec637814f        prom/prometheus     "/bin/prometheus --c…"   8 minutes ago       Up 8 minutes        0.0.0.0:9090->9090/tcp   prometheus
+79f667cb7dc2        grafana/grafana     "/run.sh"                8 minutes ago       Up 8 minutes        0.0.0.0:3000->3000/tcp   grafana
+```
+
+Navigate to `http://localhost:3000` in your web browser and use the login credentials (username=admin, password=grafana) specified in the compose file to access Grafana. It is already configured with prometheus as the default datasource.
+
+![page](/docs/images/grafana.png)
+
+Navigate to `http://localhost:9090` in your web browser to access directly the web interface of prometheus.
+
+Stop and remove the containers. Use `-v` to remove the volumes if looking to erase all data.
+```
+$ docker compose down -v
+```

etc/monitoring/compose.yaml

@@ -0,0 +1,30 @@
+services:
+  prometheus:
+    image: prom/prometheus
+    container_name: prometheus
+    command:
+      - '--config.file=/etc/prometheus/prometheus.yml'
+    ports:
+      - 9090:9090
+    restart: unless-stopped
+    volumes:
+      - ./prometheus:/etc/prometheus
+      - prom_data:/prometheus
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+
+  grafana:
+    image: grafana/grafana
+    container_name: grafana
+    ports:
+      - 3000:3000
+    restart: unless-stopped
+    environment:
+      - GF_SECURITY_ADMIN_USER=admin
+      - GF_SECURITY_ADMIN_PASSWORD=grafana
+    volumes:
+      - ./grafana/datasource:/etc/grafana/provisioning/datasources
+      - ./grafana/dashboards:/etc/grafana/provisioning/dashboards
+      - ./grafana/dashboard_definitions:/var/lib/grafana/dashboards
+volumes:
+  prom_data:

etc/monitoring/grafana/dashboard_definitions/openroad.json

@@ -0,0 +1,148 @@
+{
+    "annotations": {
+      "list": [
+        {
+          "builtIn": 1,
+          "datasource": {
+            "type": "grafana",
+            "uid": "-- Grafana --"
+          },
+          "enable": true,
+          "hide": true,
+          "iconColor": "rgba(0, 211, 255, 1)",
+          "name": "Annotations & Alerts",
+          "type": "dashboard"
+        }
+      ]
+    },
+    "editable": true,
+    "fiscalYearStartMonth": 0,
+    "graphTooltip": 0,
+    "id": 1,
+    "links": [],
+    "panels": [
+      {
+        "datasource": {
+          "type": "prometheus",
+          "uid": "PBFA97CFB590B2093"
+        },
+        "fieldConfig": {
+          "defaults": {
+            "color": {
+              "mode": "palette-classic"
+            },
+            "custom": {
+              "axisBorderShow": false,
+              "axisCenteredZero": false,
+              "axisColorMode": "text",
+              "axisLabel": "",
+              "axisPlacement": "auto",
+              "barAlignment": 0,
+              "barWidthFactor": 0.6,
+              "drawStyle": "line",
+              "fillOpacity": 0,
+              "gradientMode": "none",
+              "hideFrom": {
+                "legend": false,
+                "tooltip": false,
+                "viz": false
+              },
+              "insertNulls": false,
+              "lineInterpolation": "linear",
+              "lineStyle": {
+                "fill": "solid"
+              },
+              "lineWidth": 2,
+              "pointSize": 5,
+              "scaleDistribution": {
+                "type": "linear"
+              },
+              "showPoints": "auto",
+              "spanNulls": false,
+              "stacking": {
+                "group": "A",
+                "mode": "none"
+              },
+              "thresholdsStyle": {
+                "mode": "off"
+              }
+            },
+            "mappings": [],
+            "thresholds": {
+              "mode": "absolute",
+              "steps": [
+                {
+                  "color": "green",
+                  "value": null
+                },
+                {
+                  "color": "red",
+                  "value": 80
+                }
+              ]
+            }
+          },
+          "overrides": []
+        },
+        "gridPos": {
+          "h": 10,
+          "w": 24,
+          "x": 0,
+          "y": 0
+        },
+        "id": 1,
+        "interval": "2",
+        "options": {
+          "legend": {
+            "calcs": [],
+            "displayMode": "list",
+            "placement": "bottom",
+            "showLegend": true
+          },
+          "tooltip": {
+            "hideZeros": false,
+            "mode": "single",
+            "sort": "none"
+          }
+        },
+        "pluginVersion": "11.5.1",
+        "targets": [
+          {
+            "datasource": {
+              "type": "prometheus",
+              "uid": "PBFA97CFB590B2093"
+            },
+            "disableTextWrap": false,
+            "editorMode": "builder",
+            "expr": "ord_hpwl",
+            "fullMetaSearch": false,
+            "includeNullMetadata": true,
+            "interval": "",
+            "legendFormat": "__auto",
+            "range": true,
+            "refId": "A",
+            "useBackend": false
+          }
+        ],
+        "title": "Half Perimeter Wire Length Global Placement",
+        "type": "timeseries"
+      }
+    ],
+    "preload": false,
+    "refresh": "",
+    "schemaVersion": 40,
+    "tags": [],
+    "templating": {
+      "list": []
+    },
+    "time": {
+      "from": "now-2d",
+      "to": "now"
+    },
+    "timepicker": {},
+    "timezone": "browser",
+    "title": "OpenROAD",
+    "uid": "bedke9uv3g5q8d",
+    "version": 6,
+    "weekStart": ""
+  }

etc/monitoring/grafana/dashboards/default.yml

@@ -0,0 +1,9 @@
+apiVersion: 1
+
+providers:
+  - name: Default # A uniquely identifiable name for the provider
+    folder: Services # The folder where to place the dashboards
+    type: file
+    options:
+      path:
+        /var/lib/grafana/dashboards

etc/monitoring/grafana/datasource/datasource.yml

@@ -0,0 +1,9 @@
+apiVersion: 1
+
+datasources:
+- name: Prometheus
+  type: prometheus
+  url: http://prometheus:9090 
+  isDefault: true
+  access: proxy
+  editable: true

etc/monitoring/prometheus/prometheus.yml

@@ -0,0 +1,25 @@
+global:
+  scrape_interval: 15s
+  scrape_timeout: 10s
+  evaluation_interval: 15s
+
+alerting:
+  alertmanagers:
+    - static_configs:
+        - targets: []  # Keep this as is, or add your Alertmanager targets if you have any.
+      scheme: http  # This is already correct
+      timeout: 10s    # This is also fine
+      api_version: v2  # Changed from v1 to v2
+      path_prefix: /   # ADD THIS - Required for v2
+
+scrape_configs:
+  - job_name: prometheus
+    honor_timestamps: true  # This section is all good as is.
+    scrape_interval: 5s
+    scrape_timeout: 3s
+    metrics_path: /metrics
+    scheme: http
+    static_configs:
+      - targets:
+          - localhost:9090
+          - host.docker.internal:8080

src/gpl/src/nesterovPlace.cpp

@@ -227,6 +227,15 @@ void NesterovPlace::init()
     totalBaseWireLengthCoeff += nb->getBaseWireLengthCoef();
   }
 
+  std::shared_ptr<utl::PrometheusRegistry> registry = log_->getRegistry();
+  auto& hpwl_gauge_family
+      = utl::BuildGauge()
+            .Name("ord_hpwl")
+            .Help("The half perimeter wire length of the block")
+            .Register(*registry);
+  auto& hpwl_gauge = hpwl_gauge_family.Add({});
+  hpwl_gauge_ = &hpwl_gauge;
+
   average_overflow_ = total_sum_overflow_ / nbVec_.size();
   baseWireLengthCoef_ = totalBaseWireLengthCoeff / nbVec_.size();
   updateWireLengthCoef(average_overflow_);
@@ -753,6 +762,7 @@ void NesterovPlace::updateNextIter(const int iter)
   // Update divergence snapshot
   if (!npVars_.disableRevertIfDiverge) {
     int64_t hpwl = nbc_->getHpwl();
+    hpwl_gauge_->Set(hpwl);
     if (hpwl < min_hpwl_ && average_overflow_unscaled_ <= 0.25) {
       min_hpwl_ = hpwl;
       diverge_snapshot_average_overflow_unscaled_ = average_overflow_unscaled_;

src/gpl/src/nesterovPlace.h

@@ -40,6 +40,7 @@
 #include "nesterovBase.h"
 #include "odb/dbBlockCallBackObj.h"
 #include "point.h"
+#include "utl/prometheus/gauge.h"
 
 namespace utl {
 class Logger;
@@ -135,6 +136,9 @@ class NesterovPlace
   float wireLengthCoefX_ = 0;
   float wireLengthCoefY_ = 0;
 
+  // observability metrics
+  utl::Gauge<double>* hpwl_gauge_;
+
   // half-parameter-wire-length
   int64_t prevHpwl_ = 0;
 

src/utl/CMakeLists.txt

@@ -73,6 +73,7 @@ add_library(utl_lib
   src/ScopedTemporaryFile.cpp
   src/Logger.cpp
   src/timer.cpp
+  src/prometheus/metrics_server.cpp
 )
 
 target_include_directories(utl_lib

src/utl/README.md

@@ -9,6 +9,32 @@ The utility module contains the `man` command.
 - Parameters without square brackets `-param2 param2` are required.
 ```
 
+### Prometheus Metrics
+
+OpenROAD includes a metrics endpoint server that can track internal tool metrics over time.
+
+![page](/docs/images/grafana.png)
+
+To use this feature you need to do the following start the prometheus and grafana collectors
+
+[Detailed instructions](/etc/monitoring/README.md):
+```shell
+$ cd etc/monitoring
+$ docker compose up -d
+```
+
+This will start a grafana endpoint ready to collect from the OpenROAD application you would
+like to track. By default it's looking for an http server running on port 8080 on your localhost.
+
+To start the metrics endpoint in OpenROAD, run:
+```tcl
+utl::startPrometheusEndpoint 8080
+```
+
+This is all configurable in the docker compose file, and you should be able to access grafana by going to
+http://localhost:3000 username: admin, password: grafana. Go to the dashboard tab and click service,
+then OpenROAD to see the pre-made dashboard.
+
 ## Man installation
 
 The `man` command can be installed optionally as part of the OpenROAD