Move the logging one level up to send all logs and exceptions to the user

With this change, only failed builds are logged to the backend logger

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

packages/techdocs-common/api-report.md

@@ -53,6 +53,7 @@ export type GeneratorRunOptions = {
     outputDir: string;
     parsedLocationAnnotation?: ParsedLocationAnnotation;
     etag?: string;
+    logger: Logger;
     logStream?: Writable;
 };
 
@@ -167,7 +168,7 @@ export class TechdocsGenerator implements GeneratorBase {
         config: Config;
     });
     // (undocumented)
-    run({ inputDir, outputDir, parsedLocationAnnotation, etag, logStream: callerLogStream, }: GeneratorRunOptions): Promise<void>;
+    run({ inputDir, outputDir, parsedLocationAnnotation, etag, logger: childLogger, logStream, }: GeneratorRunOptions): Promise<void>;
 }
 
 // @public

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

@@ -17,8 +17,6 @@
 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,
@@ -36,18 +34,6 @@ type TechdocsGeneratorOptions = {
   runGeneratorIn: string;
 };
 
-const createStream = (): [string[], PassThrough] => {
-  const log = [] as Array<string>;
-
-  const stream = new PassThrough();
-  stream.on('data', chunk => {
-    const textValue = chunk.toString().trim();
-    if (textValue?.length > 1) log.push(textValue);
-  });
-
-  return [log, stream];
-};
-
 export class TechdocsGenerator implements GeneratorBase {
   private readonly logger: Logger;
   private readonly containerRunner: ContainerRunner;
@@ -75,25 +61,9 @@ export class TechdocsGenerator implements GeneratorBase {
     outputDir,
     parsedLocationAnnotation,
     etag,
-    logStream: callerLogStream,
+    logger: childLogger,
+    logStream,
   }: 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
@@ -153,7 +123,6 @@ export class TechdocsGenerator implements GeneratorBase {
       this.logger.debug(
         `Failed to generate docs from ${inputDir} into ${outputDir}`,
       );
-      childLogger.error(`Build failed with error: ${log}`);
       throw new Error(
         `Failed to generate docs from ${inputDir} into ${outputDir} with error ${error.message}`,
       );

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

@@ -13,8 +13,10 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 import { Entity } from '@backstage/catalog-model';
 import { Writable } from 'stream';
+import { Logger } from 'winston';
 import { ParsedLocationAnnotation } from '../../helpers';
 
 /**
@@ -24,13 +26,15 @@ import { ParsedLocationAnnotation } from '../../helpers';
  * @param {string} outputDir Directory to store generated docs in. Usually - a newly created temporary directory.
  * @param {ParsedLocationAnnotation} parsedLocationAnnotation backstage.io/techdocs-ref annotation of an entity
  * @param {string} etag A unique identifier for the prepared tree e.g. commit SHA. If provided it will be stored in techdocs_metadata.json.
- * @param {Writable} [logStream] A dedicated log stream
+ * @param {Logger} [logger] A logger that forwards the messages to the caller to be displayed outside of the backend.
+ * @param {Writable} [logStream] A log stream that can send raw log messages to the caller to be displayed outside of the backend..
  */
 export type GeneratorRunOptions = {
   inputDir: string;
   outputDir: string;
   parsedLocationAnnotation?: ParsedLocationAnnotation;
   etag?: string;
+  logger: Logger;
   logStream?: Writable;
 };