Improved Tech-Insights documentation

Signed-off-by: Andre Wanlin <awanlin@rapidrtc.com>
2022-03-18 13:13:20 -05:00
parent f9653d19eb
commit 2fe58c7285
5 changed files with 148 additions and 9 deletions
@@ -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 the 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<Router> {
+  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,
+  });
+}
+```