Merge branch 'master' into feat-root-logger-service-overrides

Signed-off-by: Thomas Cardonne <thomas.cardonne@adevinta.com>

docs/backend-system/core-services/root-logger.md

@@ -13,11 +13,13 @@ If you want to override the implementation for logging across all of the backend
 
 ## Configuring the service
 
+### Configuration parameters
+
 The Root Logger Service can be configured with the `backend.logger` section of your `app-config.yaml`.
 
 The following parameters are available:
 
-- `level` (string, optional): Sets the global log level. Possible values are 'debug', 'info', 'warn', or 'error'. Only messages at or above this level will be logged. This can also be set via the `LOG_LEVEL` environment variable, which takes precedence. Defaults to 'info'.
+- `level` (string, optional): Sets the global log level. Possible values are `debug`, `info`, `warn`, or `error`. Only messages at or above this level will be logged. This can also be set via the `LOG_LEVEL` environment variable, which takes precedence. Defaults to `info`. See [Modifying the log level](#modifying-the-log-level).
 
 - `meta` (object, optional): Additional metadata to include with every log entry.
 
@@ -56,7 +58,24 @@ backend:
         level: warn
 ```
 
-## Overriding the service
+### Modifying the log level
+
+The available log levels, in order of decreasing verbosity, are:
+
+- `debug`: Detailed information, typically useful only when troubleshooting.
+- `info`: General information about the application's operation. This is the default level.
+- `warn`: Indicates potential issues or situations that may require attention.
+- `error`: Indicates errors that have occurred but may not necessarily prevent the application from continuing.
+
+The verbosity of the logging can be controlled by setting the log level. The log level determines the minimum severity level of events that will be output to the console. For example, if the log level is set to `info`, events with a severity level of `debug` will be ignored.
+
+To increase the log level, you can set the `LOG_LEVEL` environment variable to a higher severity level, such as `warn` or `error`. However, be aware that increasing the log level might not result in more output if the existing code primarily emits logs at lower severity levels (e.g., `debug` or `info`). In such cases, you may need to adjust the logging statements within the code to use higher severity levels to see more output.
+
+No additional steps are required beyond setting the `LOG_LEVEL` environment variable, but the effectiveness depends on the existing logging statements in the code.
+
+To learn more, see the [Debugging Backstage](https://backstage.io/docs/tooling/local-dev/debugging) guide.
+
+### Overriding the default implementation
 
 The following example is how you can override the root logger service to add additional metadata to all log lines.
 

docs/backend-system/core-services/scheduler.md

@@ -129,3 +129,24 @@ Responds with
 - `200 OK` if successful
 - `404 Not Found` if there was no such registered task for this plugin
 - `409 Conflict` if the task was already in a running state
+
+## Testing
+
+The `@backstage/backend-test-utils` package provides `mockServices.scheduler`, which provides a mocked implementation of the scheduler service that can be used in tests. This mocked implementation is used by default in `startTestBackend`, and it will immediately run any registered tasks on startup as long as they're not configured to run manually or with an initial delay.
+
+A dedicated instance can be used for more control during testing:
+
+```ts
+it('should trigger a task', async () => {
+  const scheduler = mockServices.scheduler();
+
+  const { server } = await startTestBackend({
+    features: [scheduler.factory()],
+  });
+
+  await scheduler.triggerTask('some-task-id');
+
+  // Next verify that the plugin state is updated accordingly
+  // e.g. by calling the API or verifying database state
+});
+```