diff --git a/.changeset/thick-comics-fold.md b/.changeset/thick-comics-fold.md new file mode 100644 index 0000000000..5faf2fd399 --- /dev/null +++ b/.changeset/thick-comics-fold.md @@ -0,0 +1,11 @@ +--- +'@backstage/plugin-tech-insights': patch +'@backstage/plugin-tech-insights-backend': patch +--- + +Improved the Tech-Insights documentation: + +- `lifecycle` examples used `ttl` when it should be `timeToLive` +- Added list of included FactRetrievers +- Added full backend example using all included FactRetrievers +- Added boolean scorecard example image showing results of backend example diff --git a/plugins/tech-insights-backend/README.md b/plugins/tech-insights-backend/README.md index 275adaa15c..60c3477efe 100644 --- a/plugins/tech-insights-backend/README.md +++ b/plugins/tech-insights-backend/README.md @@ -92,8 +92,8 @@ FactRetrieverRegistration also accepts an optional `lifecycle` configuration val ```ts const maxItems = { maxItems: 7 }; // Deletes all but 7 latest facts for each id/entity pair -const ttl = { ttl: 1209600000 }; // (2 weeks) Deletes items older than 2 weeks -const ttlWithAHumanReadableValue = { ttl: { weeks: 2 } }; // Deletes items older than 2 weeks +const ttl = { timeToLive: 1209600000 }; // (2 weeks) Deletes items older than 2 weeks +const ttlWithAHumanReadableValue = { timeToLive: { weeks: 2 } }; // Deletes items older than 2 weeks ``` To register these fact retrievers to your application you can modify the example `techInsights.ts` file shown above like this: @@ -235,3 +235,130 @@ const myFactCheckerFactory = new JsonRulesEngineFactCheckerFactory({ }), ``` + +## Included FactRetrievers + +There are three FactRetrievers that come out of the box with Tech Insights: + +- `entityMetadataFactRetriever`: Generates facts which indicate the completeness of entity metadata +- `entityOwnershipFactRetriever`: Generates facts which indicate the quality of data in the spec.owner field +- `techdocsFactRetriever`: Generates facts related to the completeness of techdocs configuration for entities + +## Backend Example + +Here's an example backend setup that will use the three included fact retrievers so you can get an idea of how this all works. This will be the entire contents of your `techInsights.ts` file found at `\packages\backend\src\plugins` as per [Adding the plugin to your `packages/backend`](#adding-the-plugin-to-your-packagesbackend) + +```ts +import { + createRouter, + buildTechInsightsContext, + createFactRetrieverRegistration, + entityOwnershipFactRetriever, + entityMetadataFactRetriever, + techdocsFactRetriever, +} from '@backstage/plugin-tech-insights-backend'; +import { Router } from 'express'; +import { PluginEnvironment } from '../types'; +import { + JsonRulesEngineFactCheckerFactory, + JSON_RULE_ENGINE_CHECK_TYPE, +} from '@backstage/plugin-tech-insights-backend-module-jsonfc'; + +const ttlTwoWeeks = { timeToLive: { weeks: 2 } }; + +export default async function createPlugin( + env: PluginEnvironment, +): Promise { + const techInsightsContext = await buildTechInsightsContext({ + logger: env.logger, + config: env.config, + database: env.database, + discovery: env.discovery, + factRetrievers: [ + createFactRetrieverRegistration({ + cadence: '0 */6 * * *', // Run every 6 hours - https://crontab.guru/#0_*/6_*_*_* + factRetriever: entityOwnershipFactRetriever, + lifecycle: ttlTwoWeeks, + }), + createFactRetrieverRegistration({ + cadence: '0 */6 * * *', + factRetriever: entityMetadataFactRetriever, + lifecycle: ttlTwoWeeks, + }), + createFactRetrieverRegistration({ + cadence: '0 */6 * * *', + factRetriever: techdocsFactRetriever, + lifecycle: ttlTwoWeeks, + }), + ], + factCheckerFactory: new JsonRulesEngineFactCheckerFactory({ + logger: env.logger, + checks: [ + { + id: 'groupOwnerCheck', + type: JSON_RULE_ENGINE_CHECK_TYPE, + name: 'Group Owner Check', + description: + 'Verifies that a Group has been set as the owner for this entity', + factIds: ['entityOwnershipFactRetriever'], + rule: { + conditions: { + all: [ + { + fact: 'hasGroupOwner', + operator: 'equal', + value: true, + }, + ], + }, + }, + }, + { + id: 'titleCheck', + type: JSON_RULE_ENGINE_CHECK_TYPE, + name: 'Title Check', + description: + 'Verifies that a Title, used to improve readability, has been set for this entity', + factIds: ['entityMetadataFactRetriever'], + rule: { + conditions: { + all: [ + { + fact: 'hasTitle', + operator: 'equal', + value: true, + }, + ], + }, + }, + }, + { + id: 'techDocsCheck', + type: JSON_RULE_ENGINE_CHECK_TYPE, + name: 'TechDocs Check', + description: + 'Verifies that TechDocs has been enabled for this entity', + factIds: ['techdocsFactRetriever'], + rule: { + conditions: { + all: [ + { + fact: 'hasAnnotationBackstageIoTechdocsRef', + operator: 'equal', + value: true, + }, + ], + }, + }, + }, + ], + }), + }); + + return await createRouter({ + ...techInsightsContext, + logger: env.logger, + config: env.config, + }); +} +``` diff --git a/plugins/tech-insights/README.md b/plugins/tech-insights/README.md index db69808df1..068f88c035 100644 --- a/plugins/tech-insights/README.md +++ b/plugins/tech-insights/README.md @@ -47,12 +47,8 @@ const serviceEntityPage = ( It is not obligatory to pass title and description props to `EntityTechInsightsScorecardContent`. If those are left out, default values from `defaultCheckResultRenderers` in `CheckResultRenderer` will be taken, hence `Boolean scorecard` and `This card represents an overview of default boolean Backstage checks`. -### Customize scorecards overview title and description: +## Boolean Scorecard Example -```tsx -// packages/app/src/components/catalog/EntityPage.tsx +If you follow the [Backend Example](https://github.com/backstage/backstage/tree/master/plugins/tech-insights-backend#backend-example), once the needed facts have been generated the boolean scorecard will look like this: -## Links - -- [The Backstage homepage](https://backstage.io) -``` +![Boolean Scorecard Example](./docs/boolean-scorecard-example.png) diff --git a/plugins/tech-insights/docs/boolean-scorecard-example.png b/plugins/tech-insights/docs/boolean-scorecard-example.png new file mode 100644 index 0000000000..f7860afc2c Binary files /dev/null and b/plugins/tech-insights/docs/boolean-scorecard-example.png differ diff --git a/plugins/tech-insights/package.json b/plugins/tech-insights/package.json index 1740fc66b1..8ae665508a 100644 --- a/plugins/tech-insights/package.json +++ b/plugins/tech-insights/package.json @@ -12,6 +12,11 @@ "backstage": { "role": "frontend-plugin" }, + "repository": { + "type": "git", + "url": "https://github.com/backstage/backstage", + "directory": "plugins/tech-insights" + }, "scripts": { "build": "backstage-cli package build", "start": "backstage-cli package start",