docs: update catalog error eventing/logging

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

docs/features/software-catalog/life-of-an-entity.md

@@ -197,13 +197,15 @@ cannot be parsed successfully, etc.
 
 There are two main ways that these errors are surfaced.
 
-First, the catalog backend will produce detailed logs that should contain
-sufficient information for a reader to find the causes for errors. Since these
-logs are typically not easily found by end users, this can mainly be a useful
+First, the catalog backend will emit [events](https://github.com/backstage/backstage/tree/master/plugins/events-node) you can subscribe to that should contain
+sufficient information for a reader to find the causes for errors.
+Since these events are typically not easily found by end users, this can mainly be a useful
 tool for Backstage operators who want to debug problems either with statically
 registered entities that are under their control, or to help end users find
 problems.
 
+> Prior to Backstage version v1.26.0 and `@backstage/plugin-catalog-backend` v1.21.9 catalog errors were logged by default. See the docs below on how to enable these logs and an example on how you can further customize how you ingest these errors.
+
 Second, for most classes of errors, the entity itself will contain a status
 field that describes the problem. The contents of this field is shown at the top
 of your entity page in Backstage, if you have placed the corresponding error
@@ -212,6 +214,118 @@ callout component (`EntityProcessingErrorsPanel`) there.
 We are still working to improve the surfacing and observability around
 processing loop errors.
 
+### Subscribing to Catalog Errors
+
+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.
+
+#### New Backend System
+
+Make sure you have the events plugin installed.
+
+```ts title="packages/backend/src/index.ts"
+backend.add(import('@backstage/plugin-events-backend/alpha'));
+```
+
+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';
+import {
+  coreServices,
+  createBackendModule,
+} from '@backstage/backend-plugin-api';
+import { eventsServiceRef, EventParams } from '@backstage/plugin-events-node';
+
+interface EventsPayload {
+  entity: string;
+  location?: string;
+  errors: Error[];
+}
+
+interface EventsParamsWithPayload extends EventParams {
+  eventPayload: EventsPayload;
+}
+
+const eventsModuleCatalogErrors = createBackendModule({
+  pluginId: 'events',
+  moduleId: 'catalog-errors',
+  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,
+              });
+            }
+          },
+        });
+      },
+    });
+  },
+});
+```
+
+Now install your module.
+
+```ts title="packages/backend/src/index.ts"
+backend.add(eventsModuleCatalogErrors);
+```
+
+You should now see logs as the catalog emits events.
+
+```
+[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
+```
+
+#### Legacy Backend
+
+Make sure you have the events plugin installed. See the legacy backend instructions [here](https://github.com/backstage/backstage/tree/master/plugins/events-node#legacy-backend-system).
+
+Subscribe to the events using the `eventBroker` set in the environment.
+
+```ts
+import { CATALOG_ERRORS_TOPIC } from '@backstage/plugin-catalog-backend';
+
+env.eventBroker.subscribe({
+  supportsEventTopics(): string[] {
+    return [CATALOG_ERRORS_TOPIC];
+  },
+
+  async onEvent(
+    params: EventParams<{
+      entity: string;
+      location?: string;
+      errors: Array<Error>;
+    }>,
+  ): Promise<void> {
+    const { entity, location, errors } = params.eventPayload;
+    for (const error of errors) {
+      env.logger.warn(error.message, {
+        entity,
+        location,
+      });
+    }
+  },
+});
+```
+
+You should now see logs as the catalog emits events.
+
+```
+[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
+```
+
 ## Orphaning
 
 As mentioned earlier, entities internally form a graph. The edges go from
@@ -268,8 +382,10 @@ However, if you want to delete orphaned entities automatically anyway, you can
 enable the automated clean up with the following app-config option.
 
 ```
+
 catalog:
-  orphanStrategy: delete
+orphanStrategy: delete
+
 ```
 
 ## Implicit Deletion