add logging module to make this easier for users but retain custom docs

Signed-off-by: Christopher Diaz <codingdiaz@icloud.com>

docs/features/software-catalog/configuration.md

@@ -195,7 +195,27 @@ Now you can install the events backend plugin in your backend.
 backend.add(import('@backstage/plugin-events-backend/alpha'));
 ```
 
-Next, create a backend module that subscribes to the catalog error events. The topic is `experimental.catalog.errors`.
+### Logging Errors
+
+If you want to log catalog errors you can install the `@backstage/plugin-catalog-backend-module-logs` module.
+
+```ts title="packages/backend/src/index.ts"
+backend.add(import('@backstage/plugin-catalog-backend-module-logs'));
+```
+
+This will log errors with a level of `warn`.
+
+You should now see logs as the catalog emits events. Example:
+
+```
+[1] 2024-06-07T00:00:28.787Z events warn Policy check failed for user:default/guest; caused by Error: Malformed envelope, /metadata/tags must be array entity=user:default/guest location=file:/Users/foobar/code/backstage-demo-instance/examples/org.yaml
+```
+
+### Custom Error Handling
+
+If you wish to handle catalog errors with logic the following should help you get started.
+
+Create a backend module that subscribes to the catalog error events. The topic is `experimental.catalog.errors`.
 
 ```ts title="packages/backend/src/index.ts"
 import { CATALOG_ERRORS_TOPIC } from '@backstage/plugin-catalog-backend';
@@ -231,6 +251,7 @@ const eventsModuleCatalogErrors = createBackendModule({
           async onEvent(params: EventParams): Promise<void> {
             const event = params as EventsParamsWithPayload;
             const { entity, location, errors } = event.eventPayload;
+            // Add custom logic here for responding to errors
             for (const error of errors) {
               logger.warn(error.message, {
                 entity,
@@ -250,9 +271,3 @@ Now install your module.
 ```ts title="packages/backend/src/index.ts"
 backend.add(eventsModuleCatalogErrors);
 ```
-
-You should now see logs as the catalog emits events. Example:
-
-```
-[1] 2024-06-07T00:00:28.787Z events warn Policy check failed for user:default/guest; caused by Error: Malformed envelope, /metadata/tags must be array entity=user:default/guest location=file:/Users/foobar/code/backstage-demo-instance/examples/org.yaml
-```

plugins/catalog-backend-module-logs/.eslintrc.js

@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

plugins/catalog-backend-module-logs/README.md

@@ -0,0 +1,30 @@
+# backstage-plugin-catalog-backend-module-logs
+
+A module that subscribes to catalog related events and logs them.
+
+Catalog errors are published to the [events plugin](https://github.com/backstage/backstage/tree/master/plugins/events-node): `@backstage/plugin-events-node`. You can subscribe to events and respond to errors, for example you may wish to log them.
+
+The first step is to add the events backend plugin to your Backstage application. Navigate to your Backstage application directory and add the plugin package.
+
+```ts
+# From your Backstage root directory
+yarn --cwd packages/backend add @backstage/plugin-events-node
+```
+
+Now you can install the events backend plugin in your backend.
+
+```ts title="packages/backend/src/index.ts"
+backend.add(import('@backstage/plugin-events-backend/alpha'));
+```
+
+Now install the catalog logs module.
+
+```ts title="packages/backend/src/index.ts"
+backend.add(import('@backstage/plugin-catalog-backend-module-logs'));
+```
+
+You should now see logs as the catalog emits events. Example:
+
+```
+[1] 2024-06-07T00:00:28.787Z events warn Policy check failed for user:default/guest; caused by Error: Malformed envelope, /metadata/tags must be array entity=user:default/guest location=file:/Users/foobar/code/backstage-demo-instance/examples/org.yaml
+```

plugins/catalog-backend-module-logs/catalog-info.yaml

@@ -0,0 +1,10 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: backstage-plugin-catalog-backend-module-logs
+  title: '@backstage/plugin-catalog-backend-module-logs'
+  description: A module that subscribes to catalog releated events and logs them.
+spec:
+  lifecycle: experimental
+  type: backstage-backend-plugin-module
+  owner: maintainers

plugins/catalog-backend-module-logs/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@backstage/plugin-catalog-backend-module-logs",
+  "description": "A module that subscribes to catalog releated events and logs them.",
+  "version": "0.0.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "license": "Apache-2.0",
+  "private": true,
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "backend-plugin-module"
+  },
+  "scripts": {
+    "start": "backstage-cli package start",
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack"
+  },
+  "dependencies": {
+    "@backstage/backend-common": "workspace:^",
+    "@backstage/backend-plugin-api": "workspace:^",
+    "@backstage/plugin-catalog-backend": "workspace:^",
+    "@backstage/plugin-events-node": "workspace:^"
+  },
+  "devDependencies": {
+    "@backstage/backend-test-utils": "workspace:^",
+    "@backstage/cli": "workspace:^"
+  },
+  "files": [
+    "dist"
+  ]
+}

plugins/catalog-backend-module-logs/src/index.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2024 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * The logs backend module for the catalog plugin.
+ *
+ * @packageDocumentation
+ */
+
+export { catalogModuleLogs as default } from './module';

plugins/catalog-backend-module-logs/src/module.ts

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2024 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  coreServices,
+  createBackendModule,
+} from '@backstage/backend-plugin-api';
+import { CATALOG_ERRORS_TOPIC } from '@backstage/plugin-catalog-backend';
+import { eventsServiceRef, EventParams } from '@backstage/plugin-events-node';
+
+interface EventsPayload {
+  entity: string;
+  location?: string;
+  errors: Error[];
+}
+
+interface EventsParamsWithPayload extends EventParams {
+  eventPayload: EventsPayload;
+}
+
+export const catalogModuleLogs = createBackendModule({
+  pluginId: 'catalog',
+  moduleId: 'logs',
+  register(env) {
+    env.registerInit({
+      deps: {
+        events: eventsServiceRef,
+        logger: coreServices.logger,
+      },
+      async init({ events, logger }) {
+        events.subscribe({
+          id: 'catalog',
+          topics: [CATALOG_ERRORS_TOPIC],
+          async onEvent(params: EventParams): Promise<void> {
+            const event = params as EventsParamsWithPayload;
+            const { entity, location, errors } = event.eventPayload;
+            for (const error of errors) {
+              logger.warn(error.message, {
+                entity,
+                location,
+              });
+            }
+          },
+        });
+      },
+    });
+  },
+});

yarn.lock

@@ -5440,6 +5440,19 @@ __metadata:
   languageName: unknown
   linkType: soft
 
+"@backstage/plugin-catalog-backend-module-logs@workspace:plugins/catalog-backend-module-logs":
+  version: 0.0.0-use.local
+  resolution: "@backstage/plugin-catalog-backend-module-logs@workspace:plugins/catalog-backend-module-logs"
+  dependencies:
+    "@backstage/backend-common": "workspace:^"
+    "@backstage/backend-plugin-api": "workspace:^"
+    "@backstage/backend-test-utils": "workspace:^"
+    "@backstage/cli": "workspace:^"
+    "@backstage/plugin-catalog-backend": "workspace:^"
+    "@backstage/plugin-events-node": "workspace:^"
+  languageName: unknown
+  linkType: soft
+
 "@backstage/plugin-catalog-backend-module-msgraph@workspace:plugins/catalog-backend-module-msgraph":
   version: 0.0.0-use.local
   resolution: "@backstage/plugin-catalog-backend-module-msgraph@workspace:plugins/catalog-backend-module-msgraph"