Provide an optional logStream: Writable argument to the GeneratorBase#run(...) command

Signed-off-by: Dominik Henneke <dominik.henneke@sda-se.com>

.changeset/techdocs-new-candles-sell.md

@@ -0,0 +1,6 @@
+---
+'@backstage/techdocs-common': patch
+---
+
+Provide an optional `logStream: Writable` argument to the `GeneratorBase#run(...)` command.
+The stream receives all log messages that are emitted during the generator run.

packages/techdocs-common/api-report.md

@@ -47,6 +47,15 @@ export type GeneratorBuilder = {
     get(entity: Entity): GeneratorBase;
 };
 
+// @public
+export type GeneratorRunOptions = {
+    inputDir: string;
+    outputDir: string;
+    parsedLocationAnnotation?: ParsedLocationAnnotation;
+    etag?: string;
+    logStream?: Writable;
+};
+
 // @public (undocumented)
 export class Generators implements GeneratorBuilder {
     // (undocumented)
@@ -158,7 +167,7 @@ export class TechdocsGenerator implements GeneratorBase {
         config: Config;
     });
     // (undocumented)
-    run({ inputDir, outputDir, parsedLocationAnnotation, etag, }: GeneratorRunOptions): Promise<void>;
+    run({ inputDir, outputDir, parsedLocationAnnotation, etag, logStream: callerLogStream, }: GeneratorRunOptions): Promise<void>;
 }
 
 // @public

packages/techdocs-common/src/stages/generate/index.ts

@@ -15,4 +15,8 @@
  */
 export { TechdocsGenerator } from './techdocs';
 export { Generators } from './generators';
-export type { GeneratorBuilder, GeneratorBase } from './types';
+export type {
+  GeneratorBuilder,
+  GeneratorBase,
+  GeneratorRunOptions,
+} from './types';

packages/techdocs-common/src/stages/generate/techdocs.ts

@@ -18,6 +18,7 @@ import { ContainerRunner } from '@backstage/backend-common';
 import { Config } from '@backstage/config';
 import path from 'path';
 import { PassThrough } from 'stream';
+import * as winston from 'winston';
 import { Logger } from 'winston';
 import {
   addBuildTimestampMetadata,
@@ -74,9 +75,25 @@ export class TechdocsGenerator implements GeneratorBase {
     outputDir,
     parsedLocationAnnotation,
     etag,
+    logStream: callerLogStream,
   }: GeneratorRunOptions): Promise<void> {
+    // create a copy of the logger. we want to keep all settings but want to add a new logger target.
+    // without the copy, we would add the target to the original (parent) logger.
+    const childLogger = winston.createLogger(this.logger);
+
     const [log, logStream] = createStream();
 
+    // Forward the logs to the caller
+    if (callerLogStream) {
+      childLogger.add(
+        new winston.transports.Stream({ stream: callerLogStream }),
+      );
+      // don't use logStream.pipe(callerLogStream) because it would block others to write to callerLogStream
+      logStream.on('data', data => {
+        callerLogStream.write(data);
+      });
+    }
+
     // TODO: In future mkdocs.yml can be mkdocs.yaml. So, use a config variable here to find out
     // the correct file name.
     // Do some updates to mkdocs.yml before generating docs e.g. adding repo_url
@@ -84,7 +101,7 @@ export class TechdocsGenerator implements GeneratorBase {
     if (parsedLocationAnnotation) {
       await patchMkdocsYmlPreBuild(
         mkdocsYmlPath,
-        this.logger,
+        childLogger,
         parsedLocationAnnotation,
       );
     }
@@ -108,7 +125,7 @@ export class TechdocsGenerator implements GeneratorBase {
             },
             logStream,
           });
-          this.logger.info(
+          childLogger.info(
             `Successfully generated docs from ${inputDir} into ${outputDir} using local mkdocs`,
           );
           break;
@@ -123,7 +140,7 @@ export class TechdocsGenerator implements GeneratorBase {
             // write to, otherwise they will just fail trying to write to /
             envVars: { HOME: '/tmp' },
           });
-          this.logger.info(
+          childLogger.info(
             `Successfully generated docs from ${inputDir} into ${outputDir} using techdocs-container`,
           );
           break;
@@ -136,7 +153,7 @@ export class TechdocsGenerator implements GeneratorBase {
       this.logger.debug(
         `Failed to generate docs from ${inputDir} into ${outputDir}`,
       );
-      this.logger.error(`Build failed with error: ${log}`);
+      childLogger.error(`Build failed with error: ${log}`);
       throw new Error(
         `Failed to generate docs from ${inputDir} into ${outputDir} with error ${error.message}`,
       );
@@ -150,7 +167,7 @@ export class TechdocsGenerator implements GeneratorBase {
     // Creates techdocs_metadata.json if file does not exist.
     await addBuildTimestampMetadata(
       path.join(outputDir, 'techdocs_metadata.json'),
-      this.logger,
+      childLogger,
     );
 
     // Add etag of the prepared tree to techdocs_metadata.json