Merge pull request #27052 from deejay1/stitcher

feat(catalog-backend): Add configuration parameters for deferred stitcher

docs/features/software-catalog/configuration.md

@@ -165,7 +165,7 @@ catalog:
 
 ## Processing Interval
 
-The [processing loop](https://backstage.io/docs/features/software-catalog/life-of-an-entity) is
+The [processing loop](./life-of-an-entity.md#processing) is
 responsible for running your registered processors on all entities, on a certain
 interval. That interval can be configured with the `processingInterval`
 app-config parameter.
@@ -192,13 +192,43 @@ Setting this value too low risks exhausting rate limits on external systems that
 are queried by processors, such as version control systems housing catalog-info
 files.
 
+## Stitching strategy
+
+[Stitching](./life-of-an-entity.md#stitching) finalizes the entity. It can be run in
+two modes:
+
+- `immediate` - performs stitching in-band immediately when needed
+- `deferred` - performs the stitching asynchronously
+
+It can be configured with the `stitchingStrategy` app-config parameter.
+
+```yaml title="app-config.yaml"
+catalog:
+  stitchingStrategy: immediate
+```
+
+For the `deferred` mode you can set up additional parameters to further tune the process,
+by setting the following parameters:
+
+- `pollingInterval` - the interval between polling for entities that need stitching
+- `stitchTimeout` - the maximum time to wait for an entity to be stitched
+
+These parameters accept a duration object, similar to the `processingInterval` parameter.
+
+```yaml title="app-config.yaml"
+catalog:
+  stitchingStrategy: deferred
+  pollingInterval: { seconds: 1 }
+  stitchTimeout: { minutes: 1 };
+```
+
 ## Subscribing to Catalog Errors
 
 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 title="From your Backstage root directory"
+```bash title="From your Backstage root directory"
 yarn --cwd packages/backend add @backstage/plugin-events-backend
 ```
 
@@ -214,7 +244,7 @@ If you want to log catalog errors you can install the `@backstage/plugin-catalog
 
 Install the catalog logs module.
 
-```ts title="From your Backstage root directory"
+```bash title="From your Backstage root directory"
 yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-logs
 ```