From dcacad5d81c4bae38aab028006ad1fd1f315d2e2 Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Thu, 6 Jun 2024 20:15:46 -0400 Subject: [PATCH 01/24] docs: update catalog error eventing/logging Signed-off-by: Christopher Diaz --- .../software-catalog/life-of-an-entity.md | 124 +++++++++++++++++- 1 file changed, 120 insertions(+), 4 deletions(-) diff --git a/docs/features/software-catalog/life-of-an-entity.md b/docs/features/software-catalog/life-of-an-entity.md index 13fe496fc1..9c45bec814 100644 --- a/docs/features/software-catalog/life-of-an-entity.md +++ b/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 { + 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; + }>, + ): Promise { + 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 From 9809a3aadd232b5c74dc42871917ca48cd7e8cc4 Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Thu, 6 Jun 2024 20:28:19 -0400 Subject: [PATCH 02/24] fix formatting Signed-off-by: Christopher Diaz --- docs/features/software-catalog/life-of-an-entity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/software-catalog/life-of-an-entity.md b/docs/features/software-catalog/life-of-an-entity.md index 9c45bec814..3db33bf42b 100644 --- a/docs/features/software-catalog/life-of-an-entity.md +++ b/docs/features/software-catalog/life-of-an-entity.md @@ -384,7 +384,7 @@ enable the automated clean up with the following app-config option. ``` catalog: -orphanStrategy: delete + orphanStrategy: delete ``` From 12694f9a55b2550ed65d9d897067e843ecac80da Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Thu, 6 Jun 2024 20:28:39 -0400 Subject: [PATCH 03/24] fix formatting Signed-off-by: Christopher Diaz --- docs/features/software-catalog/life-of-an-entity.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/features/software-catalog/life-of-an-entity.md b/docs/features/software-catalog/life-of-an-entity.md index 3db33bf42b..6dfb656c4b 100644 --- a/docs/features/software-catalog/life-of-an-entity.md +++ b/docs/features/software-catalog/life-of-an-entity.md @@ -382,10 +382,8 @@ 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 - ``` ## Implicit Deletion From e2de06cf344ab9739a4e047b7df5f5a15f85e8b0 Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Thu, 6 Jun 2024 20:29:45 -0400 Subject: [PATCH 04/24] specify the log is an example Signed-off-by: Christopher Diaz --- docs/features/software-catalog/life-of-an-entity.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/features/software-catalog/life-of-an-entity.md b/docs/features/software-catalog/life-of-an-entity.md index 6dfb656c4b..017b5322be 100644 --- a/docs/features/software-catalog/life-of-an-entity.md +++ b/docs/features/software-catalog/life-of-an-entity.md @@ -282,7 +282,7 @@ Now install your module. backend.add(eventsModuleCatalogErrors); ``` -You should now see logs as the catalog emits events. +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 @@ -320,7 +320,7 @@ env.eventBroker.subscribe({ }); ``` -You should now see logs as the catalog emits events. +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 From 6dbe3921ca0fc383f32893f017840c24593c5942 Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Fri, 7 Jun 2024 11:17:10 -0400 Subject: [PATCH 05/24] update docs Signed-off-by: Christopher Diaz --- .../software-catalog/configuration.md | 79 ++++++++++++ .../software-catalog/life-of-an-entity.md | 116 +----------------- 2 files changed, 81 insertions(+), 114 deletions(-) diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md index 61366a91f7..54a2b99faf 100644 --- a/docs/features/software-catalog/configuration.md +++ b/docs/features/software-catalog/configuration.md @@ -177,3 +177,82 @@ here. Setting this value too low risks exhausting rate limits on external systems that are queried by processors, such as version control systems housing catalog-info files. + +## Subscribing to Catalog Errors + +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')); +``` + +Next, 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 { + 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. 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/life-of-an-entity.md b/docs/features/software-catalog/life-of-an-entity.md index 017b5322be..029778510a 100644 --- a/docs/features/software-catalog/life-of-an-entity.md +++ b/docs/features/software-catalog/life-of-an-entity.md @@ -197,8 +197,8 @@ cannot be parsed successfully, etc. There are two main ways that these errors are surfaced. -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. +First, the catalog backend will emit events using the [events backend plugin](https://github.com/backstage/backstage/tree/master/plugins/events-node). You can subscribe to the events. The events should contain +sufficient information for a reader to find the causes for errors. See the configuration documentation [here](./configuration.md#subscribing-to-catalog-errors) for how to subscribe and log these error events. 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 @@ -214,118 +214,6 @@ 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 { - 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. 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 -``` - -#### 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; - }>, - ): Promise { - 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. 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 -``` - ## Orphaning As mentioned earlier, entities internally form a graph. The edges go from From 21bef93e3535d310abea47bd1173e6ba0a0d4539 Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Fri, 7 Jun 2024 11:52:48 -0400 Subject: [PATCH 06/24] add logging module to make this easier for users but retain custom docs Signed-off-by: Christopher Diaz --- .../software-catalog/configuration.md | 29 ++++++--- .../catalog-backend-module-logs/.eslintrc.js | 1 + plugins/catalog-backend-module-logs/README.md | 30 +++++++++ .../catalog-info.yaml | 10 +++ .../catalog-backend-module-logs/package.json | 39 ++++++++++++ .../catalog-backend-module-logs/src/index.ts | 23 +++++++ .../catalog-backend-module-logs/src/module.ts | 61 +++++++++++++++++++ yarn.lock | 13 ++++ 8 files changed, 199 insertions(+), 7 deletions(-) create mode 100644 plugins/catalog-backend-module-logs/.eslintrc.js create mode 100644 plugins/catalog-backend-module-logs/README.md create mode 100644 plugins/catalog-backend-module-logs/catalog-info.yaml create mode 100644 plugins/catalog-backend-module-logs/package.json create mode 100644 plugins/catalog-backend-module-logs/src/index.ts create mode 100644 plugins/catalog-backend-module-logs/src/module.ts diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md index 54a2b99faf..4bab2313b8 100644 --- a/docs/features/software-catalog/configuration.md +++ b/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 { 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 -``` diff --git a/plugins/catalog-backend-module-logs/.eslintrc.js b/plugins/catalog-backend-module-logs/.eslintrc.js new file mode 100644 index 0000000000..e2a53a6ad2 --- /dev/null +++ b/plugins/catalog-backend-module-logs/.eslintrc.js @@ -0,0 +1 @@ +module.exports = require('@backstage/cli/config/eslint-factory')(__dirname); diff --git a/plugins/catalog-backend-module-logs/README.md b/plugins/catalog-backend-module-logs/README.md new file mode 100644 index 0000000000..6c84114306 --- /dev/null +++ b/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 +``` diff --git a/plugins/catalog-backend-module-logs/catalog-info.yaml b/plugins/catalog-backend-module-logs/catalog-info.yaml new file mode 100644 index 0000000000..f2223174c3 --- /dev/null +++ b/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 diff --git a/plugins/catalog-backend-module-logs/package.json b/plugins/catalog-backend-module-logs/package.json new file mode 100644 index 0000000000..f35a8b7816 --- /dev/null +++ b/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" + ] +} diff --git a/plugins/catalog-backend-module-logs/src/index.ts b/plugins/catalog-backend-module-logs/src/index.ts new file mode 100644 index 0000000000..3d5f606d27 --- /dev/null +++ b/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'; diff --git a/plugins/catalog-backend-module-logs/src/module.ts b/plugins/catalog-backend-module-logs/src/module.ts new file mode 100644 index 0000000000..0f41d2e1a6 --- /dev/null +++ b/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 { + const event = params as EventsParamsWithPayload; + const { entity, location, errors } = event.eventPayload; + for (const error of errors) { + logger.warn(error.message, { + entity, + location, + }); + } + }, + }); + }, + }); + }, +}); diff --git a/yarn.lock b/yarn.lock index a0a385ca66..542d9242da 100644 --- a/yarn.lock +++ b/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" From 97caf558236a4d2d9ac8029a186607cb9deddd4c Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Fri, 7 Jun 2024 11:56:36 -0400 Subject: [PATCH 07/24] add logging module to make this easier for users but retain custom docs Signed-off-by: Christopher Diaz --- .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')); ``` From c4c81bcc73446a29c6cda5456ffded2698c8a816 Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Fri, 7 Jun 2024 11:57:41 -0400 Subject: [PATCH 08/24] add logging module to make this easier for users but retain custom docs Signed-off-by: Christopher Diaz --- .changeset/ten-pots-walk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/ten-pots-walk.md b/.changeset/ten-pots-walk.md index 6265e8dd7f..e8f68afbe0 100644 --- a/.changeset/ten-pots-walk.md +++ b/.changeset/ten-pots-walk.md @@ -26,7 +26,7 @@ Install the catalog logs module. yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-logs ``` -Now install the catalog logs module. +Add the module to your backend. ```ts title="packages/backend/src/index.ts" backend.add(import('@backstage/plugin-catalog-backend-module-logs')); From 9c8518e29a1c1d40bf096f7a5e44ace9c4e70449 Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Fri, 7 Jun 2024 12:00:10 -0400 Subject: [PATCH 09/24] module should not be private Signed-off-by: Christopher Diaz --- .../catalog-backend-module-logs/package.json | 31 +++++++++---------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/plugins/catalog-backend-module-logs/package.json b/plugins/catalog-backend-module-logs/package.json index f35a8b7816..3d07b115ae 100644 --- a/plugins/catalog-backend-module-logs/package.json +++ b/plugins/catalog-backend-module-logs/package.json @@ -1,27 +1,29 @@ { "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, + "description": "A module that subscribes to catalog releated events and logs them.", + "backstage": { + "role": "backend-plugin-module" + }, "publishConfig": { "access": "public", "main": "dist/index.cjs.js", "types": "dist/index.d.ts" }, - "backstage": { - "role": "backend-plugin-module" - }, + "license": "Apache-2.0", + "main": "src/index.ts", + "types": "src/index.ts", + "files": [ + "dist" + ], "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", + "lint": "backstage-cli package lint", "prepack": "backstage-cli package prepack", - "postpack": "backstage-cli package postpack" + "postpack": "backstage-cli package postpack", + "start": "backstage-cli package start", + "test": "backstage-cli package test" }, "dependencies": { "@backstage/backend-common": "workspace:^", @@ -32,8 +34,5 @@ "devDependencies": { "@backstage/backend-test-utils": "workspace:^", "@backstage/cli": "workspace:^" - }, - "files": [ - "dist" - ] + } } From acb3c93b4ce5be9bbc4ed5d2ac4a9ab912bb908f Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Fri, 7 Jun 2024 12:10:05 -0400 Subject: [PATCH 10/24] add api report Signed-off-by: Christopher Diaz --- plugins/catalog-backend-module-logs/api-report.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 plugins/catalog-backend-module-logs/api-report.md diff --git a/plugins/catalog-backend-module-logs/api-report.md b/plugins/catalog-backend-module-logs/api-report.md new file mode 100644 index 0000000000..abad6c3095 --- /dev/null +++ b/plugins/catalog-backend-module-logs/api-report.md @@ -0,0 +1,13 @@ +## API Report File for "@backstage/plugin-catalog-backend-module-logs" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts +import { BackendFeature } from '@backstage/backend-plugin-api'; + +// Warning: (ae-missing-release-tag) "catalogModuleLogs" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// +// @public (undocumented) +const catalogModuleLogs: () => BackendFeature; +export default catalogModuleLogs; +``` From d9772b13cb1f37dca41b4219dc466ebe59916c72 Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Fri, 7 Jun 2024 12:17:27 -0400 Subject: [PATCH 11/24] add api report Signed-off-by: Christopher Diaz --- plugins/catalog-backend-module-logs/src/index.ts | 1 + plugins/catalog-backend-module-logs/src/module.ts | 5 +++++ 2 files changed, 6 insertions(+) diff --git a/plugins/catalog-backend-module-logs/src/index.ts b/plugins/catalog-backend-module-logs/src/index.ts index 3d5f606d27..6808046373 100644 --- a/plugins/catalog-backend-module-logs/src/index.ts +++ b/plugins/catalog-backend-module-logs/src/index.ts @@ -18,6 +18,7 @@ * The logs backend module for the catalog plugin. * * @packageDocumentation + * @public */ export { catalogModuleLogs as default } from './module'; diff --git a/plugins/catalog-backend-module-logs/src/module.ts b/plugins/catalog-backend-module-logs/src/module.ts index 0f41d2e1a6..13a96a64f8 100644 --- a/plugins/catalog-backend-module-logs/src/module.ts +++ b/plugins/catalog-backend-module-logs/src/module.ts @@ -14,6 +14,11 @@ * limitations under the License. */ +/** + * Logs catalog errors from events. + * + * @public + */ import { coreServices, createBackendModule, From 4118216077183039f33434011b0fc9cd0b7cdf8a Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Fri, 7 Jun 2024 12:22:25 -0400 Subject: [PATCH 12/24] add api report Signed-off-by: Christopher Diaz --- plugins/catalog-backend-module-logs/package.json | 5 +++++ plugins/catalog-backend-module-logs/src/index.ts | 3 +-- plugins/catalog-backend-module-logs/src/module.ts | 2 -- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/plugins/catalog-backend-module-logs/package.json b/plugins/catalog-backend-module-logs/package.json index 3d07b115ae..d2e76131fb 100644 --- a/plugins/catalog-backend-module-logs/package.json +++ b/plugins/catalog-backend-module-logs/package.json @@ -10,6 +10,11 @@ "main": "dist/index.cjs.js", "types": "dist/index.d.ts" }, + "repository": { + "type": "git", + "url": "https://github.com/backstage/backstage", + "directory": "plugins/catalog-backend-module-logs" + }, "license": "Apache-2.0", "main": "src/index.ts", "types": "src/index.ts", diff --git a/plugins/catalog-backend-module-logs/src/index.ts b/plugins/catalog-backend-module-logs/src/index.ts index 6808046373..717b7bde9e 100644 --- a/plugins/catalog-backend-module-logs/src/index.ts +++ b/plugins/catalog-backend-module-logs/src/index.ts @@ -16,9 +16,8 @@ /** * The logs backend module for the catalog plugin. - * - * @packageDocumentation * @public + * @packageDocumentation */ export { catalogModuleLogs as default } from './module'; diff --git a/plugins/catalog-backend-module-logs/src/module.ts b/plugins/catalog-backend-module-logs/src/module.ts index 13a96a64f8..84f92cfe92 100644 --- a/plugins/catalog-backend-module-logs/src/module.ts +++ b/plugins/catalog-backend-module-logs/src/module.ts @@ -16,8 +16,6 @@ /** * Logs catalog errors from events. - * - * @public */ import { coreServices, From abeb6b982ea01473e15207af6c7ae1a80392b75e Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Fri, 7 Jun 2024 12:27:24 -0400 Subject: [PATCH 13/24] add api report without warnings Signed-off-by: Christopher Diaz --- plugins/catalog-backend-module-logs/api-report.md | 2 -- plugins/catalog-backend-module-logs/src/index.ts | 5 ++--- plugins/catalog-backend-module-logs/src/module.ts | 4 +--- 3 files changed, 3 insertions(+), 8 deletions(-) diff --git a/plugins/catalog-backend-module-logs/api-report.md b/plugins/catalog-backend-module-logs/api-report.md index abad6c3095..7dd45e6119 100644 --- a/plugins/catalog-backend-module-logs/api-report.md +++ b/plugins/catalog-backend-module-logs/api-report.md @@ -5,8 +5,6 @@ ```ts import { BackendFeature } from '@backstage/backend-plugin-api'; -// Warning: (ae-missing-release-tag) "catalogModuleLogs" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) const catalogModuleLogs: () => BackendFeature; export default catalogModuleLogs; diff --git a/plugins/catalog-backend-module-logs/src/index.ts b/plugins/catalog-backend-module-logs/src/index.ts index 717b7bde9e..77a7d424eb 100644 --- a/plugins/catalog-backend-module-logs/src/index.ts +++ b/plugins/catalog-backend-module-logs/src/index.ts @@ -15,9 +15,8 @@ */ /** - * The logs backend module for the catalog plugin. - * @public + * A catalog module that logs catalog errors using the logger service. + * * @packageDocumentation */ - export { catalogModuleLogs as default } from './module'; diff --git a/plugins/catalog-backend-module-logs/src/module.ts b/plugins/catalog-backend-module-logs/src/module.ts index 84f92cfe92..54fc428cdf 100644 --- a/plugins/catalog-backend-module-logs/src/module.ts +++ b/plugins/catalog-backend-module-logs/src/module.ts @@ -14,9 +14,6 @@ * limitations under the License. */ -/** - * Logs catalog errors from events. - */ import { coreServices, createBackendModule, @@ -34,6 +31,7 @@ interface EventsParamsWithPayload extends EventParams { eventPayload: EventsPayload; } +/** @public */ export const catalogModuleLogs = createBackendModule({ pluginId: 'catalog', moduleId: 'logs', From 486ce82f7fa799725408728ee6dc04da541a81f8 Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Fri, 7 Jun 2024 14:07:22 -0400 Subject: [PATCH 14/24] add basic test Signed-off-by: Christopher Diaz --- .../catalog-backend-module-logs/package.json | 3 +- .../src/module.test.ts | 45 +++++++++++++++++++ yarn.lock | 1 + 3 files changed, 48 insertions(+), 1 deletion(-) create mode 100644 plugins/catalog-backend-module-logs/src/module.test.ts diff --git a/plugins/catalog-backend-module-logs/package.json b/plugins/catalog-backend-module-logs/package.json index d2e76131fb..879ed3176a 100644 --- a/plugins/catalog-backend-module-logs/package.json +++ b/plugins/catalog-backend-module-logs/package.json @@ -38,6 +38,7 @@ }, "devDependencies": { "@backstage/backend-test-utils": "workspace:^", - "@backstage/cli": "workspace:^" + "@backstage/cli": "workspace:^", + "@backstage/plugin-events-backend-test-utils": "workspace:^" } } diff --git a/plugins/catalog-backend-module-logs/src/module.test.ts b/plugins/catalog-backend-module-logs/src/module.test.ts new file mode 100644 index 0000000000..733474512e --- /dev/null +++ b/plugins/catalog-backend-module-logs/src/module.test.ts @@ -0,0 +1,45 @@ +/* + * 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 { mockServices, startTestBackend } from '@backstage/backend-test-utils'; +import { catalogModuleLogs } from './module'; +import { createServiceFactory } from '@backstage/backend-plugin-api'; +import { TestEventsService } from '@backstage/plugin-events-backend-test-utils'; +import { eventsServiceRef } from '@backstage/plugin-events-node'; + +describe('eventsModuleLogs', () => { + it('should be correctly wired and set up', async () => { + const events = new TestEventsService(); + const eventsServiceFactory = createServiceFactory({ + service: eventsServiceRef, + deps: {}, + async factory({}) { + return events; + }, + }); + + await startTestBackend({ + features: [ + mockServices.logger.factory(), + eventsServiceFactory(), + catalogModuleLogs(), + ], + }); + + expect(events.subscribed).toHaveLength(1); + expect(events.subscribed[0].id).toEqual('catalog'); + }); +}); diff --git a/yarn.lock b/yarn.lock index 542d9242da..6c298b9c89 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5449,6 +5449,7 @@ __metadata: "@backstage/backend-test-utils": "workspace:^" "@backstage/cli": "workspace:^" "@backstage/plugin-catalog-backend": "workspace:^" + "@backstage/plugin-events-backend-test-utils": "workspace:^" "@backstage/plugin-events-node": "workspace:^" languageName: unknown linkType: soft From 5f4090221f598ddfb101db3a629dcf577157edf0 Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Fri, 7 Jun 2024 14:08:31 -0400 Subject: [PATCH 15/24] add basic test Signed-off-by: Christopher Diaz --- plugins/catalog-backend-module-logs/src/module.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/catalog-backend-module-logs/src/module.test.ts b/plugins/catalog-backend-module-logs/src/module.test.ts index 733474512e..79f1b8c295 100644 --- a/plugins/catalog-backend-module-logs/src/module.test.ts +++ b/plugins/catalog-backend-module-logs/src/module.test.ts @@ -20,7 +20,7 @@ import { createServiceFactory } from '@backstage/backend-plugin-api'; import { TestEventsService } from '@backstage/plugin-events-backend-test-utils'; import { eventsServiceRef } from '@backstage/plugin-events-node'; -describe('eventsModuleLogs', () => { +describe('catalogModuleLogs', () => { it('should be correctly wired and set up', async () => { const events = new TestEventsService(); const eventsServiceFactory = createServiceFactory({ From 916449c0452b6e80df5b8a40ed4f3236f84f8d2b Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Wed, 19 Jun 2024 10:08:20 -0400 Subject: [PATCH 16/24] Update docs/features/software-catalog/life-of-an-entity.md Co-authored-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com> Signed-off-by: Christopher Diaz --- docs/features/software-catalog/life-of-an-entity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/software-catalog/life-of-an-entity.md b/docs/features/software-catalog/life-of-an-entity.md index 029778510a..d333b90565 100644 --- a/docs/features/software-catalog/life-of-an-entity.md +++ b/docs/features/software-catalog/life-of-an-entity.md @@ -198,7 +198,7 @@ cannot be parsed successfully, etc. There are two main ways that these errors are surfaced. First, the catalog backend will emit events using the [events backend plugin](https://github.com/backstage/backstage/tree/master/plugins/events-node). You can subscribe to the events. The events should contain -sufficient information for a reader to find the causes for errors. See the configuration documentation [here](./configuration.md#subscribing-to-catalog-errors) for how to subscribe and log these error events. +sufficient information for a reader to find the causes for errors. See the [configuration documentation](./configuration.md#subscribing-to-catalog-errors) for how to subscribe and log these error events. 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 From f304e99204b0c8a211f4a616daf4baec2c469974 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Wed, 19 Jun 2024 16:34:44 +0200 Subject: [PATCH 17/24] Update plugins/catalog-backend-module-logs/package.json MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- plugins/catalog-backend-module-logs/package.json | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/plugins/catalog-backend-module-logs/package.json b/plugins/catalog-backend-module-logs/package.json index 879ed3176a..e8ed120872 100644 --- a/plugins/catalog-backend-module-logs/package.json +++ b/plugins/catalog-backend-module-logs/package.json @@ -3,7 +3,9 @@ "version": "0.0.0", "description": "A module that subscribes to catalog releated events and logs them.", "backstage": { - "role": "backend-plugin-module" + "role": "backend-plugin-module", + "pluginId": "catalog", + "pluginPackage": "@backstage/plugin-catalog-backend" }, "publishConfig": { "access": "public", From 2a2de3984e6e261a0d0965595bbed5fd69a4bd60 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Wed, 19 Jun 2024 16:34:49 +0200 Subject: [PATCH 18/24] Update plugins/catalog-backend-module-logs/package.json MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- plugins/catalog-backend-module-logs/package.json | 1 - 1 file changed, 1 deletion(-) diff --git a/plugins/catalog-backend-module-logs/package.json b/plugins/catalog-backend-module-logs/package.json index e8ed120872..858f7ec198 100644 --- a/plugins/catalog-backend-module-logs/package.json +++ b/plugins/catalog-backend-module-logs/package.json @@ -33,7 +33,6 @@ "test": "backstage-cli package test" }, "dependencies": { - "@backstage/backend-common": "workspace:^", "@backstage/backend-plugin-api": "workspace:^", "@backstage/plugin-catalog-backend": "workspace:^", "@backstage/plugin-events-node": "workspace:^" From 066cc7143ef4c51f8baff98b914ab2c2cdb5ff95 Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Wed, 19 Jun 2024 11:09:50 -0400 Subject: [PATCH 19/24] remove verbage to docs that exist elsewhere Signed-off-by: Christopher Diaz --- docs/features/software-catalog/life-of-an-entity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/software-catalog/life-of-an-entity.md b/docs/features/software-catalog/life-of-an-entity.md index d333b90565..1489688720 100644 --- a/docs/features/software-catalog/life-of-an-entity.md +++ b/docs/features/software-catalog/life-of-an-entity.md @@ -204,7 +204,7 @@ 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. +> Prior to Backstage version v1.26.0 and `@backstage/plugin-catalog-backend` v1.21.9 catalog errors were logged by default. 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 From 16589947aa9bdc95fba049d17f3cecc50b869e78 Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Wed, 19 Jun 2024 11:12:30 -0400 Subject: [PATCH 20/24] remove duplicate module docs and point to backstage docs Signed-off-by: Christopher Diaz --- plugins/catalog-backend-module-logs/README.md | 37 ++----------------- 1 file changed, 3 insertions(+), 34 deletions(-) diff --git a/plugins/catalog-backend-module-logs/README.md b/plugins/catalog-backend-module-logs/README.md index 7e20a0161b..1771dbe02c 100644 --- a/plugins/catalog-backend-module-logs/README.md +++ b/plugins/catalog-backend-module-logs/README.md @@ -2,38 +2,7 @@ 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. +## Getting started -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. - -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')); -``` - -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 -``` +See [Backstage documentation](https://backstage.io/docs/features/software-catalog/configuration#subscribing-to-catalog-errors) for details on how to install +and configure the plugin. From d3f280b51fa7f0c0283cfbd02a7efad73f729aa9 Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Wed, 19 Jun 2024 11:21:41 -0400 Subject: [PATCH 21/24] remove un-needed line in docs and update changeset to use a link Signed-off-by: Christopher Diaz --- .changeset/ten-pots-walk.md | 35 ++----------------- .../software-catalog/configuration.md | 2 +- 2 files changed, 3 insertions(+), 34 deletions(-) diff --git a/.changeset/ten-pots-walk.md b/.changeset/ten-pots-walk.md index e8f68afbe0..cf540fd0e2 100644 --- a/.changeset/ten-pots-walk.md +++ b/.changeset/ten-pots-walk.md @@ -4,36 +4,5 @@ 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 -``` - -Add the module to your backend. - -```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 -``` +See [Backstage documentation](https://backstage.io/docs/features/software-catalog/configuration#subscribing-to-catalog-errors) for details on how to install +and configure the plugin. diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md index 9805eb06dd..3bbbfd6716 100644 --- a/docs/features/software-catalog/configuration.md +++ b/docs/features/software-catalog/configuration.md @@ -222,7 +222,7 @@ You should now see logs as the catalog emits events. Example: ### Custom Error Handling -If you wish to handle catalog errors with logic the following should help you get started. +If you wish to handle catalog errors with specific logic different from logging the errors the following should help you get started. For example, you may wish to send a notification or create a ticket for someone to investigate. Create a backend module that subscribes to the catalog error events. The topic is `experimental.catalog.errors`. From e61267416795b27e6530a40686c1459ac88b272f Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Wed, 19 Jun 2024 11:24:03 -0400 Subject: [PATCH 22/24] update lockfile Signed-off-by: Christopher Diaz --- yarn.lock | 1 - 1 file changed, 1 deletion(-) diff --git a/yarn.lock b/yarn.lock index 6c298b9c89..7d440ea43f 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5444,7 +5444,6 @@ __metadata: 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:^" From 26bd7a7a92971f9157f5a04fc537aed232414925 Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Wed, 19 Jun 2024 12:16:26 -0400 Subject: [PATCH 23/24] try to update api docs Signed-off-by: Christopher Diaz --- plugins/catalog-backend-module-logs/api-report.md | 2 +- plugins/catalog-backend-module-logs/src/module.ts | 7 ++++++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/plugins/catalog-backend-module-logs/api-report.md b/plugins/catalog-backend-module-logs/api-report.md index 7dd45e6119..bb08280566 100644 --- a/plugins/catalog-backend-module-logs/api-report.md +++ b/plugins/catalog-backend-module-logs/api-report.md @@ -5,7 +5,7 @@ ```ts import { BackendFeature } from '@backstage/backend-plugin-api'; -// @public (undocumented) +// @public const catalogModuleLogs: () => BackendFeature; export default catalogModuleLogs; ``` diff --git a/plugins/catalog-backend-module-logs/src/module.ts b/plugins/catalog-backend-module-logs/src/module.ts index 54fc428cdf..bdc916e958 100644 --- a/plugins/catalog-backend-module-logs/src/module.ts +++ b/plugins/catalog-backend-module-logs/src/module.ts @@ -31,7 +31,12 @@ interface EventsParamsWithPayload extends EventParams { eventPayload: EventsPayload; } -/** @public */ +/** + * A catalog module that logs catalog errors using the logger service. + * + * @packageDocumentation + * @public + */ export const catalogModuleLogs = createBackendModule({ pluginId: 'catalog', moduleId: 'logs', From c057720a67cd0b34a322de0d492091d42a81a94a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Wed, 19 Jun 2024 19:36:51 +0200 Subject: [PATCH 24/24] api report MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- plugins/catalog-backend-module-logs/api-report.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/catalog-backend-module-logs/api-report.md b/plugins/catalog-backend-module-logs/api-report.md index bb08280566..0be2197c9a 100644 --- a/plugins/catalog-backend-module-logs/api-report.md +++ b/plugins/catalog-backend-module-logs/api-report.md @@ -3,9 +3,9 @@ > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). ```ts -import { BackendFeature } from '@backstage/backend-plugin-api'; +import { BackendFeatureCompat } from '@backstage/backend-plugin-api'; // @public -const catalogModuleLogs: () => BackendFeature; +const catalogModuleLogs: BackendFeatureCompat; export default catalogModuleLogs; ```