Fact Collectors

One of the foundational elements of Soundcheck, Fact Collectors collect raw data (facts) about your components. These facts are then used by checks to determine the health of your components.

NOTE: Fact Collectors are called Integrations in No-Code UI.

Fact Framework

• Soundcheck allows organizations to push results through the Soundcheck API.
• Organizations may also leverage the Soundcheck Fact Framework, which provides a mechanism by which Soundcheck itself can collect facts about an entity in Backstage, and execute checks based on those facts.
• The Fact Framework allows Soundcheck to collect facts (un-opinionated information) about an entity in the software catalog. Facts are made available to Soundcheck through fact collectors.

Soundcheck comes with two built-in fact collectors: the Catalog Collector and the Soundcheck Collector. A fact collector collects one or more facts about entities, and Soundcheck can be extended with additional fact collectors.

Configuring a fact collector (integration) via the no-code UI

To configure a fact collector (integration), make sure you are on the Integrations tab. Click on an integration's Configure link to open a page that displays the integration's configuration form.

• WARNING: If you already have a config YAML file setup, No-Code UI configuration will be merged with the existing YAML configuration. It's preferable to choose a single source for the Fact Collectors configuration (either No-Code UI or YAML) to avoid confusing merge results.

Once you choose to configure an integration, you will see the following page with multiple configuration options for different fact types. You can see what each configuration collects in its description. All configs have the following options:

A Note on Multiple Backstage Instances

If you are running backstage with multiple instances which include multiple instances of Soundcheck, read on. Otherwise, you may skip this section.

When configuring Soundcheck in an environment with multiple Soundcheck instances there is a delay between when you save a configuration and when you will consistently see the changes reflected in the Soundcheck UI. This is because while the configurations are stored in the database immediately, the instances synchronize their configuration once a minute.

The more instances you have, the less likely you are to see configuration changes reflected immediately in the UI, depending on which Soundcheck instance ends up serving the UI request.

Frequency

You can set the frequency of how often to collect details from each collector option. The frequency of runs can be set using regular intervals or defined as custom cron expressions.

Filters

You can set filters for each option as well. These filters contain the same options as Tracks. You can learn by going to the Creating a new track section.

Caching

Lastly, you can enable Caching and set up an optional duration for said cache.

Once you have finished making your desired changes, make sure to click on the save button in order to properly save you configuration. Optionally, you can click on the cancel button at anytime to discard your changes.

Configuring fact collectors via yaml configuration

Soundcheck can be extended with additional fact collectors. A fact collector can collect one or more facts on a given entity.

These fact collectors are provided by default with additional configuration required. A check using facts from these collectors can be defined normally.

• Catalog
• Soundcheck

Overall shape of a fact collector configuration file

However, if you'd like to use any of the available integrations or create any custom collectors yourself, you will need to create a <COLLECTOR_NAME>-fact-collector.yaml file. Here is an example for the GitHub TPI Fact Collector plugin:

github-fact-collector.yaml

---
frequency:
  cron: '* * * * *'
initialDelay:
  seconds: 30
batchSize: 1
filter:
  kind: 'Component'
cache:
  duration:
    hours: 24
collects:
  - factName: repo_details
    type: RepositoryDetails
  - factName: protections
    type: BranchProtections

Fact Collector Configuration

Each collector defines their own configuration parameters. Please refer to the documentation for the specific collector you are using for more information.

Adding yaml fact collectors to your fact library

To add fact collectors to your fact library, you will need to add the following to your app-config.yaml file:

app-config.yaml

soundcheck:
  collectors:
    - $include: ./path-to-local-folder/github-fact-collector.yaml
    - $include: ./path-to-local-folder/scm-fact-collector.yaml
    - $include: ./path-to-local-folder/pagerduty-fact-collector.yaml

Note: unlike checks and tracks, most fact collectors cannot be managed via a remote repo, but we are working to add this capability. Your fact collector configuration must be present in the local Backstage instance. The exception to this is the SCM fact collector, which accepts a remote URL from which it can fetch its configuration.

Notes

• The remote URL must be accessible by the Backstage instance, and that Soundcheck will use Backstage's shared URLReader to fetch the configuration. You must therefore have proper integration(s) setup in Backstage for the URLReader to be able to fetch the configuration. For example, to use the URL provided above, you would need to have a GitHub integration setup in Backstage.
• The remote URL must be a URL to a YAML file, not a JSON file or any other format.
• There is a known limitation with configuring the SCM Fact Collector with a remote URL: The configuration will schedule fact collection appropriately on initial load, but subsequent changes to the configuration will not change which facts are collected nor their collection schedules. The SCM Fact Collector will only pick up changes to its fact collection configuration on a restart of the Backstage instance.

REST API

We include a REST API for Facts. See API Reference for details.

Third Party Integrations

We are always adding new third-party integrations to Soundcheck. You can find the list of available integrations here.