🔧 Repository: tech-insights setup documentation incomplete

[jackmtpt]

📜 Description

https://github.com/backstage/community-plugins/blob/main/workspaces/tech-insights/plugins/tech-insights-backend/README.md

This readme contains some instructions for setting up tech-insights with the new backend, but not everything is covered e.g. how to register the fact checker.

👍 Expected behavior

Everything should be documented for the new backend, and optionally for the old backend as well.

👎 Current Behavior

Not everything has docs for the new backend

👟 Reproduction steps

n/a

📃 Provide the context for the Bug.

No response

👀 Have you spent some time to check if this bug has been raised before?

• [X] I checked and didn't find similar issue

🏢 Have you read the Code of Conduct?

• [X] I have read the Code of Conduct

Are you willing to submit PR?

None

[awanlin]

Contributions welcome 👍

[jackmtpt]

As soon as I figure out how to do it I can write something...

[LegendSebastiano-L]

I'd love to know it as well how to do it, is the last plugin that I have in the old BE but I have a lot of custom checks to migrate.

I remember asking about this in Discord but I never had time to dig into it, this is part of what they replied:

The extension point is:

let factCheckerFactory:
  | FactCheckerFactory<TechInsightCheck, CheckResult>
  | undefined = undefined;
env.registerExtensionPoint(techInsightsFactCheckerFactoryExtensionPoint, {
  setFactCheckerFactory<
    CheckType extends TechInsightCheck,
    CheckResultType extends CheckResult,
  >(factory: FactCheckerFactory<CheckType, CheckResultType>): void {
    factCheckerFactory = factory;
  },
});

Where you can add your own fact check factory. That allows you to implement that interface with your own implementation.

and this is the link to the discord discussion :)

[kurtaking]

Working on updated documentation in https://github.com/backstage/community-plugins/pull/807. 👋🏼 Feel free to provide feedback directly on the PR.

[LegendSebastiano-L]

is there any news on this?

[kurtaking]

is there any news on this?

@LegendSebastianoL, you can follow my docs PR and offer feedback. This is almost at the top of my to-do list. I've had other priorities.

[LegendSebastiano-L]

hey @kurtaking I was taking a look yesterday and I saw the PR was closed and then reopened for that I asked :)

[kurtaking]

I made more edits this morning and put the PR up for review.

[LegendSebastiano-L]

hey 👋 I refactored my tech insight this morning but something wrong 🤔

here are some of the warnings I get:

[1] 2024-09-23T07:22:13.684Z tech-insights warn Validation failed for check Links Check. Reference to value websiteHasLinks does not exists in referred fact schemas: websiteFactRetriever

[1] 2024-09-23T07:22:13.685Z tech-insights warn Validation failed for check Resources Check. Reference to value systemHasResources does not exists in referred fact schemas: systemFactRetriever

[1] 2024-09-23T07:22:13.685Z tech-insights warn Validation failed for check Lifecycle Check. Reference to value lifecycleUnknown does not exists in referred fact schemas: lifecycleFactRetriever

and the code is as follow

• app.config.yaml:

      systemHasResources:
        type: json-rules-engine
        name: Resources Check
        description: Verifies that the system has some resources defined in catalog-info.yaml
        factIds:
          - systemFactRetriever
        rule:
          conditions:
            all:
              - fact: systemHasResources
                operator: equal
                value: true
      lifecycleUnknown:
        type: json-rules-engine
        name: Lifecycle Check
        description: Verifies that the lifecycle is set to a well-known type (such as production or experimental)
        factIds:
          - lifecycleFactRetriever
        rule:
          conditions:
            all:
              - fact: lifecycleUnknown
                operator: equal
                value: true

fact retriever:

export const lifecycleFactRetriever: FactRetriever = {
  id: 'lifecycleFactRetriever',
  version: '0.0.1',
  title: 'LifecycleFactRetriever',
  description: 'Generates facts related to the lifecycle of an entity',
  schema: {
    lifecycleUnknown: {
      type: 'boolean',
      description: 'The entity has an unknown lifecycle',
    },
  },
  handler: async ({
    discovery,
    entityFilter,
    auth,
  }: FactRetrieverContext) => {
    const { token } = await auth.getPluginRequestToken({
      onBehalfOf: await auth.getOwnServiceCredentials(),
      targetPluginId: 'catalog',
    });
    const catalogClient = new CatalogClient({
      discoveryApi: discovery,
    });
    const entities = await catalogClient.getEntities(
      { filter: entityFilter },
      { token },
    );

    return entities.items.map((entity: Entity) => {
      return {
        entity: {
          namespace: entity.metadata.namespace!,
          kind: entity.kind,
          name: entity.metadata.name,
        },
        facts: {
          lifecycleUnknown: Boolean(entity.spec?.lifecycle === 'unknown'),
        },
      };
    });
  },
};

and finally the module

export const techInsightsModuleCustomTechInsights = createBackendModule({
  pluginId: 'tech-insights',
  moduleId: 'custom-tech-insights',
  register(reg) {
    reg.registerInit({
      deps: {
        providers: techInsightsFactRetrieversExtensionPoint,
      },
      async init({ providers }) {
        providers.addFactRetrievers({
          apiFactRetriever,
          githubFactRetriever,
          lifecycleFactRetriever,
          systemFactRetriever,
          websiteFactRetriever,
        });

[LegendSebastiano-L]

oh, my bad...

I forgot this:

techInsights:
  factRetrievers:
    entityOwnershipFactRetriever:
      cadence: '*/15 * * * *'
      lifecycle: { timeToLive: { weeks: 1 } }
    entityMetadataFactRetriever:
      cadence: '*/15 * * * *'
      lifecycle: { timeToLive: { weeks: 1 } }
    apiFactRetriever:
      cadence: '*/15 * * * *'
      lifecycle: { timeToLive: { weeks: 1 } }

I had only the entityOwnershipFactRetriever and not the others, now looks all good :)

[kurtaking]

oh, my bad...

I forgot this:

techInsights:
  factRetrievers:
    entityOwnershipFactRetriever:
      cadence: '*/15 * * * *'
      lifecycle: { timeToLive: { weeks: 1 } }
    entityMetadataFactRetriever:
      cadence: '*/15 * * * *'
      lifecycle: { timeToLive: { weeks: 1 } }
    apiFactRetriever:
      cadence: '*/15 * * * *'
      lifecycle: { timeToLive: { weeks: 1 } }

I had only the entityOwnershipFactRetriever and not the others, now looks all good :)

Glad you figured it out. That was the number 1 thing that caused pain when I was migrating.

[kurtaking]

@jackmtpt, the updated instructions were merged. Can this be closed out?

[jackmtpt]

Yep looks good, cheers