From 21bef93e3535d310abea47bd1173e6ba0a0d4539 Mon Sep 17 00:00:00 2001 From: Christopher Diaz Date: Fri, 7 Jun 2024 11:52:48 -0400 Subject: [PATCH] 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"