Version Packages

packages/backend-common/CHANGELOG.md

@@ -1,5 +1,99 @@
 # @backstage/backend-common
 
+## 0.4.0
+
+### Minor Changes
+
+- 12bbd748c: Removes the Prometheus integration from `backend-common`.
+
+  Rational behind this change is to keep the metrics integration of Backstage
+  generic. Instead of directly relying on Prometheus, Backstage will expose
+  metrics in a generic way. Integrators can then export the metrics in their
+  desired format. For example using Prometheus.
+
+  To keep the existing behavior, you need to integrate Prometheus in your
+  backend:
+
+  First, add a dependency on `express-prom-bundle` and `prom-client` to your backend.
+
+  ```diff
+  // packages/backend/package.json
+    "dependencies": {
+  +   "express-prom-bundle": "^6.1.0",
+  +   "prom-client": "^12.0.0",
+  ```
+
+  Then, add a handler for metrics and a simple instrumentation for the endpoints.
+
+  ```typescript
+  // packages/backend/src/metrics.ts
+  import { useHotCleanup } from '@backstage/backend-common';
+  import { RequestHandler } from 'express';
+  import promBundle from 'express-prom-bundle';
+  import prom from 'prom-client';
+  import * as url from 'url';
+
+  const rootRegEx = new RegExp('^/([^/]*)/.*');
+  const apiRegEx = new RegExp('^/api/([^/]*)/.*');
+
+  export function normalizePath(req: any): string {
+    const path = url.parse(req.originalUrl || req.url).pathname || '/';
+
+    // Capture /api/ and the plugin name
+    if (apiRegEx.test(path)) {
+      return path.replace(apiRegEx, '/api/$1');
+    }
+
+    // Only the first path segment at root level
+    return path.replace(rootRegEx, '/$1');
+  }
+
+  /**
+   * Adds a /metrics endpoint, register default runtime metrics and instrument the router.
+   */
+  export function metricsHandler(): RequestHandler {
+    // We can only initialize the metrics once and have to clean them up between hot reloads
+    useHotCleanup(module, () => prom.register.clear());
+
+    return promBundle({
+      includeMethod: true,
+      includePath: true,
+      // Using includePath alone is problematic, as it will include path labels with high
+      // cardinality (e.g. path params). Instead we would have to template them. However, this
+      // is difficult, as every backend plugin might use different routes. Instead we only take
+      // the first directory of the path, to have at least an idea how each plugin performs:
+      normalizePath,
+      promClient: { collectDefaultMetrics: {} },
+    });
+  }
+  ```
+
+  Last, extend your router configuration with the `metricsHandler`:
+
+  ```diff
+  +import { metricsHandler } from './metrics';
+
+  ...
+
+    const service = createServiceBuilder(module)
+      .loadConfig(config)
+      .addRouter('', await healthcheck(healthcheckEnv))
+  +   .addRouter('', metricsHandler())
+      .addRouter('/api', apiRouter);
+  ```
+
+  Your Prometheus metrics will be available at the `/metrics` endpoint.
+
+### Patch Changes
+
+- 38e24db00: Move the core url and auth logic to integration for the four major providers
+- Updated dependencies [38e24db00]
+- Updated dependencies [b8ecf6f48]
+- Updated dependencies [e3bd9fc2f]
+- Updated dependencies [e3bd9fc2f]
+  - @backstage/integration@0.1.3
+  - @backstage/config@0.1.2
+
 ## 0.3.3
 
 ### Patch Changes

packages/backend-common/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/backend-common",
   "description": "Common functionality library for Backstage backends",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "private": false,
@@ -30,9 +30,9 @@
   },
   "dependencies": {
     "@backstage/cli-common": "^0.1.1",
-    "@backstage/config": "^0.1.1",
+    "@backstage/config": "^0.1.2",
     "@backstage/config-loader": "^0.4.0",
-    "@backstage/integration": "^0.1.2",
+    "@backstage/integration": "^0.1.3",
     "@types/cors": "^2.8.6",
     "@types/express": "^4.17.6",
     "archiver": "^5.0.2",
@@ -65,8 +65,8 @@
     }
   },
   "devDependencies": {
-    "@backstage/cli": "^0.4.0",
-    "@backstage/test-utils": "^0.1.4",
+    "@backstage/cli": "^0.4.1",
+    "@backstage/test-utils": "^0.1.5",
     "@types/archiver": "^3.1.1",
     "@types/compression": "^1.7.0",
     "@types/concat-stream": "^1.6.0",