From 97caf558236a4d2d9ac8029a186607cb9deddd4c Mon Sep 17 00:00:00 2001
From: Christopher Diaz <codingdiaz@icloud.com>
Date: Fri, 7 Jun 2024 11:56:36 -0400
Subject: [PATCH] add logging module to make this easier for users but retain
 custom docs

Signed-off-by: Christopher Diaz <codingdiaz@icloud.com>
---
 .changeset/ten-pots-walk.md                   | 39 +++++++++++++++++++
 .../software-catalog/configuration.md         |  9 +++++
 plugins/catalog-backend-module-logs/README.md |  9 +++++
 3 files changed, 57 insertions(+)
 create mode 100644 .changeset/ten-pots-walk.md

diff --git a/.changeset/ten-pots-walk.md b/.changeset/ten-pots-walk.md
new file mode 100644
index 0000000000..6265e8dd7f
--- /dev/null
+++ b/.changeset/ten-pots-walk.md
@@ -0,0 +1,39 @@
+---
+'@backstage/plugin-catalog-backend-module-logs': patch
+---
+
+Creates a new module to make logging catalog errors simple. This module subscribes to catalog 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'));
+```
+
+Install the catalog logs module.
+
+```ts
+# From your Backstage root directory
+yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-logs
+```
+
+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
+```
diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md
index 4bab2313b8..9805eb06dd 100644
--- a/docs/features/software-catalog/configuration.md
+++ b/docs/features/software-catalog/configuration.md
@@ -199,6 +199,15 @@ backend.add(import('@backstage/plugin-events-backend/alpha'));
 
 If you want to log catalog errors you can install the `@backstage/plugin-catalog-backend-module-logs` module.
 
+Install the catalog logs module.
+
+```ts
+# From your Backstage root directory
+yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-logs
+```
+
+Add the module to your backend.
+
 ```ts title="packages/backend/src/index.ts"
 backend.add(import('@backstage/plugin-catalog-backend-module-logs'));
 ```
diff --git a/plugins/catalog-backend-module-logs/README.md b/plugins/catalog-backend-module-logs/README.md
index 6c84114306..7e20a0161b 100644
--- a/plugins/catalog-backend-module-logs/README.md
+++ b/plugins/catalog-backend-module-logs/README.md
@@ -13,6 +13,15 @@ yarn --cwd packages/backend add @backstage/plugin-events-node
 
 Now you can install the events backend plugin in your backend.
 
+Install the catalog logs module.
+
+```ts
+# From your Backstage root directory
+yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-logs
+```
+
+Add the module to your backend.
+
 ```ts title="packages/backend/src/index.ts"
 backend.add(import('@backstage/plugin-events-backend/alpha'));
 ```