Soft-deprecate /metrics endpoint

/metrics is where notebook server publishes prometheus metrics.
Currently, if nbresuse is installed, it's impossible to get
prometheus metrics out of running notebooks.

Just removing /metrics caused issues with third-party
code (#36) that depended
on the JSON API from the endpoint, and so was reverted.

Instead, we 'soft' deprecate that endpoint.

1. Re-add /api/metrics/v1 endpoint, with exact same semantics as
   /metrics. This is enabled unconditionally.
2. /metrics is also enabled by default, but can be turned off with
   a notebook config. This allows admins who need prometheus metrics
   to turn it on.
3. The bundled notebook extension will read from /api/metrics/v1
   endpoint, so for those users things will 'just work'.

The path to removing /metrics is:

1. Release this as 0.4.0 even though there aren't any breaking changes.
   This makes it easier for code using legacy endpoints to simply pin
   to nbresuse<0.4.0
2. Find third party users relying on /metrics, and simply change them
   to use /api/metrics/v1 - should be a fairly simple change. They can
   then be pin to nbresuse>=0.4.0
3. When we're sure enough packages have switched, we can release a 0.5.0
   where /metrics is disabled by default, but enablable with a config.
4. Eventually, we can simply remove /metrics and the associated config.

Ref #36

Author: yuvipanda

nbresuse/__init__.py

@@ -35,9 +35,16 @@ def load_jupyter_server_extension(nbapp):
     resuseconfig = ResourceUseDisplay(parent=nbapp)
     nbapp.web_app.settings["nbresuse_display_config"] = resuseconfig
     base_url = nbapp.web_app.settings["base_url"]
+
+    if not resuseconfig.disable_legacy_endpoint:
+        nbapp.web_app.add_handlers(
+            ".*", [(url_path_join(base_url, "/metrics"), ApiHandler)]
+        )
+
     nbapp.web_app.add_handlers(
-        ".*", [(url_path_join(base_url, "/metrics"), ApiHandler)]
+        ".*", [(url_path_join(base_url, "/api/metrics/v1"), ApiHandler)]
     )
+
     callback = ioloop.PeriodicCallback(
         PrometheusHandler(PSUtilMetricsLoader(nbapp)), 1000
     )

nbresuse/config.py

@@ -36,6 +36,15 @@ class ResourceUseDisplay(Configurable):
     """
     Holds server-side configuration for nbresuse
     """
+    disable_legacy_endpoint = Bool(
+        True,
+        help="""
+        Disable legacy /metrics endpoint
+
+        This prevents nbresuse from shadowing the prometheus /metrics endpoint.
+        """,
+        config=True
+    )
 
     process_memory_metrics = List(
         trait=PSUtilMetric(),

nbresuse/static/main.js

@@ -34,7 +34,7 @@ define([
             return;
         }
         $.getJSON({
-            url: utils.get_body_data('baseUrl') + 'metrics',
+            url: utils.get_body_data('baseUrl') + 'api/metrics/v1',
             success: function (data) {
                 totalMemoryUsage = humanFileSize(data['rss']);