@backstage/plugin-catalog-node 2.0.0 → 2.1.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @backstage/plugin-catalog-node
 
+## 2.1.0-next.0
+
+### Minor Changes
+
+- bf71677: Added the ability for SCM events subscribers to mark the fact that they have taken actions based on events, which produces output metrics:
+
+  - `catalog.events.scm.actions` with attribute `action`: Counter for the number of actions actually taken by catalog internals or other subscribers, based on SCM events. The `action` is currently either `create`, `delete`, `refresh`, or `move`.
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/backend-plugin-api@1.7.1-next.0
+  - @backstage/catalog-client@1.13.1-next.0
+  - @backstage/backend-test-utils@1.11.1-next.0
+  - @backstage/catalog-model@1.7.6
+  - @backstage/errors@1.2.7
+  - @backstage/types@1.2.2
+  - @backstage/plugin-catalog-common@1.1.8
+  - @backstage/plugin-permission-common@0.9.6
+  - @backstage/plugin-permission-node@0.10.11-next.0
+
 ## 2.0.0
 
 ### Minor Changes

package/dist/alpha.d.ts

@@ -45,6 +45,25 @@ interface CatalogScmEventsService {
      * guarantees.
      */
     publish(events: CatalogScmEvent[]): Promise<void>;
+    /**
+     * As a consumer of SCM events, mark that you have taken an action as a result
+     * of an SCM event.
+     *
+     * This is typically used to record metrics or other observability signals
+     * about how SCM events are handled, for example counting how many refresh,
+     * delete, create, or move operations are triggered by incoming events.
+     */
+    markEventActionTaken(options: {
+        /**
+         * The number of actions taken of the given type. Defaults to 1.
+         */
+        count?: number;
+        /**
+         * The type of action taken - typically "refresh", "delete",
+         * "create", or "move".
+         */
+        action: string;
+    }): void;
 }
 /**
  * Voluntary contextual information related to a {@link CatalogScmEvent}.

package/dist/scmEvents/DefaultCatalogScmEventsService.cjs.js

@@ -2,8 +2,16 @@
 
 class DefaultCatalogScmEventsService {
   #subscribers;
-  constructor() {
+  #metrics;
+  constructor(metrics) {
     this.#subscribers = /* @__PURE__ */ new Set();
+    const meter = metrics.getMeter("default");
+    this.#metrics = {
+      actions: meter.createCounter("catalog.events.scm.actions", {
+        description: "Number of actions taken as a result of SCM event messages",
+        unit: "short"
+      })
+    };
   }
   subscribe(subscriber) {
     this.#subscribers.add(subscriber);
@@ -23,6 +31,9 @@ class DefaultCatalogScmEventsService {
       })
     );
   }
+  markEventActionTaken(options) {
+    this.#metrics.actions.add(options.count ?? 1, { action: options.action });
+  }
 }
 
 exports.DefaultCatalogScmEventsService = DefaultCatalogScmEventsService;

package/dist/scmEvents/DefaultCatalogScmEventsService.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"DefaultCatalogScmEventsService.cjs.js","sources":["../../src/scmEvents/DefaultCatalogScmEventsService.ts"],"sourcesContent":["/*\n * Copyright 2026 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  CatalogScmEvent,\n  CatalogScmEventsService,\n  CatalogScmEventsServiceSubscriber,\n} from './types';\n\n/**\n * The default implementation of the {@link CatalogScmEventsService}/{@link catalogScmEventsServiceRef}.\n *\n * @internal\n * @remarks\n *\n * This implementation is in-memory, which requires the producers and consumer\n * (the catalog backend) to be deployed together.\n */\nexport class DefaultCatalogScmEventsService implements CatalogScmEventsService {\n  readonly #subscribers: Set<CatalogScmEventsServiceSubscriber>;\n\n  constructor() {\n    this.#subscribers = new Set();\n  }\n\n  subscribe(subscriber: CatalogScmEventsServiceSubscriber): {\n    unsubscribe: () => void;\n  } {\n    this.#subscribers.add(subscriber);\n    return {\n      unsubscribe: () => {\n        this.#subscribers.delete(subscriber);\n      },\n    };\n  }\n\n  async publish(events: CatalogScmEvent[]): Promise<void> {\n    await Promise.all(\n      Array.from(this.#subscribers).map(async subscriber => {\n        try {\n          await subscriber.onEvents(events);\n        } catch (error) {\n          // The subscribers are expected to handle errors themselves.\n        }\n      }),\n    );\n  }\n}\n"],"names":[],"mappings":";;AA+BO,MAAM,8BAAA,CAAkE;AAAA,EACpE,YAAA;AAAA,EAET,WAAA,GAAc;AACZ,IAAA,IAAA,CAAK,YAAA,uBAAmB,GAAA,EAAI;AAAA,EAC9B;AAAA,EAEA,UAAU,UAAA,EAER;AACA,IAAA,IAAA,CAAK,YAAA,CAAa,IAAI,UAAU,CAAA;AAChC,IAAA,OAAO;AAAA,MACL,aAAa,MAAM;AACjB,QAAA,IAAA,CAAK,YAAA,CAAa,OAAO,UAAU,CAAA;AAAA,MACrC;AAAA,KACF;AAAA,EACF;AAAA,EAEA,MAAM,QAAQ,MAAA,EAA0C;AACtD,IAAA,MAAM,OAAA,CAAQ,GAAA;AAAA,MACZ,MAAM,IAAA,CAAK,IAAA,CAAK,YAAY,CAAA,CAAE,GAAA,CAAI,OAAM,UAAA,KAAc;AACpD,QAAA,IAAI;AACF,UAAA,MAAM,UAAA,CAAW,SAAS,MAAM,CAAA;AAAA,QAClC,SAAS,KAAA,EAAO;AAAA,QAEhB;AAAA,MACF,CAAC;AAAA,KACH;AAAA,EACF;AACF;;;;"}
+{"version":3,"file":"DefaultCatalogScmEventsService.cjs.js","sources":["../../src/scmEvents/DefaultCatalogScmEventsService.ts"],"sourcesContent":["/*\n * Copyright 2026 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Counter, MetricsAPI } from '@opentelemetry/api';\nimport {\n  CatalogScmEvent,\n  CatalogScmEventsService,\n  CatalogScmEventsServiceSubscriber,\n} from './types';\n\n/**\n * The default implementation of the\n * {@link CatalogScmEventsService}/{@link catalogScmEventsServiceRef}.\n *\n * @internal\n * @remarks\n *\n * This implementation is in-memory, which requires the producers and consumer\n * (the catalog backend) to be deployed together.\n *\n * It's defined in here instead of in the catalog-backend plugin because this\n * allows us to have a default factory whether you happen to be co-installed\n * with the catalog-backend plugin or not.\n */\nexport class DefaultCatalogScmEventsService implements CatalogScmEventsService {\n  readonly #subscribers: Set<CatalogScmEventsServiceSubscriber>;\n  readonly #metrics: {\n    actions: Counter<{ action: string }>;\n  };\n\n  constructor(metrics: MetricsAPI) {\n    this.#subscribers = new Set();\n\n    const meter = metrics.getMeter('default');\n    this.#metrics = {\n      actions: meter.createCounter('catalog.events.scm.actions', {\n        description:\n          'Number of actions taken as a result of SCM event messages',\n        unit: 'short',\n      }),\n    };\n  }\n\n  subscribe(subscriber: CatalogScmEventsServiceSubscriber): {\n    unsubscribe: () => void;\n  } {\n    this.#subscribers.add(subscriber);\n    return {\n      unsubscribe: () => {\n        this.#subscribers.delete(subscriber);\n      },\n    };\n  }\n\n  async publish(events: CatalogScmEvent[]): Promise<void> {\n    await Promise.all(\n      Array.from(this.#subscribers).map(async subscriber => {\n        try {\n          await subscriber.onEvents(events);\n        } catch (error) {\n          // The subscribers are expected to handle errors themselves.\n        }\n      }),\n    );\n  }\n\n  markEventActionTaken(options: { count?: number; action: string }): void {\n    this.#metrics.actions.add(options.count ?? 1, { action: options.action });\n  }\n}\n"],"names":[],"mappings":";;AAqCO,MAAM,8BAAA,CAAkE;AAAA,EACpE,YAAA;AAAA,EACA,QAAA;AAAA,EAIT,YAAY,OAAA,EAAqB;AAC/B,IAAA,IAAA,CAAK,YAAA,uBAAmB,GAAA,EAAI;AAE5B,IAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,QAAA,CAAS,SAAS,CAAA;AACxC,IAAA,IAAA,CAAK,QAAA,GAAW;AAAA,MACd,OAAA,EAAS,KAAA,CAAM,aAAA,CAAc,4BAAA,EAA8B;AAAA,QACzD,WAAA,EACE,2DAAA;AAAA,QACF,IAAA,EAAM;AAAA,OACP;AAAA,KACH;AAAA,EACF;AAAA,EAEA,UAAU,UAAA,EAER;AACA,IAAA,IAAA,CAAK,YAAA,CAAa,IAAI,UAAU,CAAA;AAChC,IAAA,OAAO;AAAA,MACL,aAAa,MAAM;AACjB,QAAA,IAAA,CAAK,YAAA,CAAa,OAAO,UAAU,CAAA;AAAA,MACrC;AAAA,KACF;AAAA,EACF;AAAA,EAEA,MAAM,QAAQ,MAAA,EAA0C;AACtD,IAAA,MAAM,OAAA,CAAQ,GAAA;AAAA,MACZ,MAAM,IAAA,CAAK,IAAA,CAAK,YAAY,CAAA,CAAE,GAAA,CAAI,OAAM,UAAA,KAAc;AACpD,QAAA,IAAI;AACF,UAAA,MAAM,UAAA,CAAW,SAAS,MAAM,CAAA;AAAA,QAClC,SAAS,KAAA,EAAO;AAAA,QAEhB;AAAA,MACF,CAAC;AAAA,KACH;AAAA,EACF;AAAA,EAEA,qBAAqB,OAAA,EAAmD;AACtE,IAAA,IAAA,CAAK,QAAA,CAAS,OAAA,CAAQ,GAAA,CAAI,OAAA,CAAQ,KAAA,IAAS,GAAG,EAAE,MAAA,EAAQ,OAAA,CAAQ,MAAA,EAAQ,CAAA;AAAA,EAC1E;AACF;;;;"}

package/dist/scmEvents/catalogScmEventsServiceRef.cjs.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var backendPluginApi = require('@backstage/backend-plugin-api');
+var api = require('@opentelemetry/api');
 var DefaultCatalogScmEventsService = require('./DefaultCatalogScmEventsService.cjs.js');
 
 const catalogScmEventsServiceRef = backendPluginApi.createServiceRef({
@@ -9,7 +10,7 @@ const catalogScmEventsServiceRef = backendPluginApi.createServiceRef({
     service,
     deps: {},
     createRootContext() {
-      return new DefaultCatalogScmEventsService.DefaultCatalogScmEventsService();
+      return new DefaultCatalogScmEventsService.DefaultCatalogScmEventsService(api.metrics);
     },
     factory(_, ctx) {
       return ctx;

package/dist/scmEvents/catalogScmEventsServiceRef.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"catalogScmEventsServiceRef.cjs.js","sources":["../../src/scmEvents/catalogScmEventsServiceRef.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  createServiceFactory,\n  createServiceRef,\n} from '@backstage/backend-plugin-api';\nimport { CatalogScmEventsService } from './types';\nimport { DefaultCatalogScmEventsService } from './DefaultCatalogScmEventsService';\n\n/**\n * A service that allows publishing and subscribing to source control management\n * system events.\n *\n * @alpha\n * @remarks\n *\n * The default implementation of this service acts in-memory, which requires the\n * producers and consumer (the catalog backend) to be deployed together.\n */\nexport const catalogScmEventsServiceRef =\n  createServiceRef<CatalogScmEventsService>({\n    id: 'catalog.scm-events.alpha',\n    defaultFactory: async service =>\n      createServiceFactory({\n        service,\n        deps: {},\n        createRootContext() {\n          return new DefaultCatalogScmEventsService();\n        },\n        factory(_, ctx) {\n          return ctx;\n        },\n      }),\n  });\n"],"names":["createServiceRef","createServiceFactory","DefaultCatalogScmEventsService"],"mappings":";;;;;AAiCO,MAAM,6BACXA,iCAAA,CAA0C;AAAA,EACxC,EAAA,EAAI,0BAAA;AAAA,EACJ,cAAA,EAAgB,OAAM,OAAA,KACpBC,qCAAA,CAAqB;AAAA,IACnB,OAAA;AAAA,IACA,MAAM,EAAC;AAAA,IACP,iBAAA,GAAoB;AAClB,MAAA,OAAO,IAAIC,6DAAA,EAA+B;AAAA,IAC5C,CAAA;AAAA,IACA,OAAA,CAAQ,GAAG,GAAA,EAAK;AACd,MAAA,OAAO,GAAA;AAAA,IACT;AAAA,GACD;AACL,CAAC;;;;"}
+{"version":3,"file":"catalogScmEventsServiceRef.cjs.js","sources":["../../src/scmEvents/catalogScmEventsServiceRef.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  createServiceFactory,\n  createServiceRef,\n} from '@backstage/backend-plugin-api';\nimport { metrics } from '@opentelemetry/api';\nimport { CatalogScmEventsService } from './types';\nimport { DefaultCatalogScmEventsService } from './DefaultCatalogScmEventsService';\n\n/**\n * A service that allows publishing and subscribing to source control management\n * system events.\n *\n * @alpha\n * @remarks\n *\n * The default implementation of this service acts in-memory, which requires the\n * producers and consumer (the catalog backend) to be deployed together.\n */\nexport const catalogScmEventsServiceRef =\n  createServiceRef<CatalogScmEventsService>({\n    id: 'catalog.scm-events.alpha',\n    defaultFactory: async service =>\n      createServiceFactory({\n        service,\n        deps: {},\n        createRootContext() {\n          return new DefaultCatalogScmEventsService(metrics);\n        },\n        factory(_, ctx) {\n          return ctx;\n        },\n      }),\n  });\n"],"names":["createServiceRef","createServiceFactory","DefaultCatalogScmEventsService","metrics"],"mappings":";;;;;;AAkCO,MAAM,6BACXA,iCAAA,CAA0C;AAAA,EACxC,EAAA,EAAI,0BAAA;AAAA,EACJ,cAAA,EAAgB,OAAM,OAAA,KACpBC,qCAAA,CAAqB;AAAA,IACnB,OAAA;AAAA,IACA,MAAM,EAAC;AAAA,IACP,iBAAA,GAAoB;AAClB,MAAA,OAAO,IAAIC,8DAA+BC,WAAO,CAAA;AAAA,IACnD,CAAA;AAAA,IACA,OAAA,CAAQ,GAAG,GAAA,EAAK;AACd,MAAA,OAAO,GAAA;AAAA,IACT;AAAA,GACD;AACL,CAAC;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-catalog-node",
-  "version": "2.0.0",
+  "version": "2.1.0-next.0",
   "description": "The plugin-catalog-node module for @backstage/plugin-catalog-backend",
   "backstage": {
     "role": "node-library",
@@ -72,24 +72,25 @@
     "test": "backstage-cli package test"
   },
   "dependencies": {
-    "@backstage/backend-plugin-api": "^1.7.0",
-    "@backstage/catalog-client": "^1.13.0",
-    "@backstage/catalog-model": "^1.7.6",
-    "@backstage/errors": "^1.2.7",
-    "@backstage/plugin-catalog-common": "^1.1.8",
-    "@backstage/plugin-permission-common": "^0.9.6",
-    "@backstage/plugin-permission-node": "^0.10.10",
-    "@backstage/types": "^1.2.2",
+    "@backstage/backend-plugin-api": "1.7.1-next.0",
+    "@backstage/catalog-client": "1.13.1-next.0",
+    "@backstage/catalog-model": "1.7.6",
+    "@backstage/errors": "1.2.7",
+    "@backstage/plugin-catalog-common": "1.1.8",
+    "@backstage/plugin-permission-common": "0.9.6",
+    "@backstage/plugin-permission-node": "0.10.11-next.0",
+    "@backstage/types": "1.2.2",
+    "@opentelemetry/api": "^1.9.0",
     "lodash": "^4.17.21",
     "yaml": "^2.0.0"
   },
   "devDependencies": {
-    "@backstage/backend-test-utils": "^1.11.0",
-    "@backstage/cli": "^0.35.4",
+    "@backstage/backend-test-utils": "1.11.1-next.0",
+    "@backstage/cli": "0.35.5-next.0",
     "msw": "^1.0.0"
   },
   "peerDependencies": {
-    "@backstage/backend-test-utils": "^1.11.0"
+    "@backstage/backend-test-utils": "1.11.1-next.0"
   },
   "peerDependenciesMeta": {
     "@backstage/backend-test-utils": {