From c18e8eb91006165328d040b58251c8648d7bf006 Mon Sep 17 00:00:00 2001 From: Dominik Henneke Date: Mon, 5 Jul 2021 11:56:28 +0200 Subject: [PATCH] Provide an optional `logStream: Writable` argument to the `GeneratorBase#run(...)` command Signed-off-by: Dominik Henneke --- .changeset/techdocs-new-candles-sell.md | 6 +++++ packages/techdocs-common/api-report.md | 11 +++++++- .../src/stages/generate/index.ts | 6 ++++- .../src/stages/generate/techdocs.ts | 27 +++++++++++++++---- 4 files changed, 43 insertions(+), 7 deletions(-) create mode 100644 .changeset/techdocs-new-candles-sell.md diff --git a/.changeset/techdocs-new-candles-sell.md b/.changeset/techdocs-new-candles-sell.md new file mode 100644 index 0000000000..b9ff9c3c4b --- /dev/null +++ b/.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. diff --git a/packages/techdocs-common/api-report.md b/packages/techdocs-common/api-report.md index 3fff030eee..12bf066b78 100644 --- a/packages/techdocs-common/api-report.md +++ b/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; + run({ inputDir, outputDir, parsedLocationAnnotation, etag, logStream: callerLogStream, }: GeneratorRunOptions): Promise; } // @public diff --git a/packages/techdocs-common/src/stages/generate/index.ts b/packages/techdocs-common/src/stages/generate/index.ts index 382712ccbc..eb015a5c2d 100644 --- a/packages/techdocs-common/src/stages/generate/index.ts +++ b/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'; diff --git a/packages/techdocs-common/src/stages/generate/techdocs.ts b/packages/techdocs-common/src/stages/generate/techdocs.ts index 041dff1d2f..f31bc86905 100644 --- a/packages/techdocs-common/src/stages/generate/techdocs.ts +++ b/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 { + // 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