From 82f329dda8b7678a51cabf1524d10097c44eed2d Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Thu, 4 Mar 2021 14:22:25 -0500 Subject: [PATCH 1/5] Clarify file type Signed-off-by: Adam Harvey --- packages/techdocs-common/src/stages/generate/helpers.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/techdocs-common/src/stages/generate/helpers.ts b/packages/techdocs-common/src/stages/generate/helpers.ts index a88ed13231..2035eb8da9 100644 --- a/packages/techdocs-common/src/stages/generate/helpers.ts +++ b/packages/techdocs-common/src/stages/generate/helpers.ts @@ -252,7 +252,7 @@ export const patchMkdocsYmlPreBuild = async ( mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8'); } catch (error) { logger.warn( - `Could not read file ${mkdocsYmlPath} before running the generator. ${error.message}`, + `Could not read MkDocs YAML config file ${mkdocsYmlPath} before running the generator: ${error.message}`, ); return; } From f95804c311205c10ab2b7480f9b1874d709a2145 Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Thu, 4 Mar 2021 14:22:43 -0500 Subject: [PATCH 2/5] Change log msgs to debug Signed-off-by: Adam Harvey --- packages/techdocs-common/src/helpers.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/techdocs-common/src/helpers.ts b/packages/techdocs-common/src/helpers.ts index ec58bb7b40..d02297f2fd 100644 --- a/packages/techdocs-common/src/helpers.ts +++ b/packages/techdocs-common/src/helpers.ts @@ -216,12 +216,12 @@ export const getDocFilesFromRepository = async ( entity, ); - opts?.logger?.info(`Reading files from ${target}`); + opts?.logger?.debug(`Reading files from ${target}`); // readTree will throw NotModifiedError if etag has not changed. const readTreeResponse = await reader.readTree(target, { etag: opts?.etag }); const preparedDir = await readTreeResponse.dir(); - opts?.logger?.info(`Tree downloaded and stored at ${preparedDir}`); + opts?.logger?.debug(`Tree downloaded and stored at ${preparedDir}`); return { preparedDir, From 26e23b2c7d46159c8849e6c6ff97792bd07472e2 Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Thu, 4 Mar 2021 14:23:01 -0500 Subject: [PATCH 3/5] Refactor logging Signed-off-by: Adam Harvey --- .../src/DocsBuilder/builder.ts | 51 ++++++++++++------- 1 file changed, 34 insertions(+), 17 deletions(-) diff --git a/plugins/techdocs-backend/src/DocsBuilder/builder.ts b/plugins/techdocs-backend/src/DocsBuilder/builder.ts index 51f4d212ba..38cc7ca562 100644 --- a/plugins/techdocs-backend/src/DocsBuilder/builder.ts +++ b/plugins/techdocs-backend/src/DocsBuilder/builder.ts @@ -14,7 +14,7 @@ * limitations under the License. */ import { NotModifiedError } from '@backstage/backend-common'; -import { Entity } from '@backstage/catalog-model'; +import { Entity, serializeEntityRef } from '@backstage/catalog-model'; import { GeneratorBase, GeneratorBuilder, @@ -31,12 +31,6 @@ import path from 'path'; import { Logger } from 'winston'; import { BuildMetadataStorage } from '.'; -const getEntityId = (entity: Entity) => { - return `${entity.kind}:${entity.metadata.namespace ?? ''}:${ - entity.metadata.name - }`; -}; - type DocsBuilderArguments = { preparers: PreparerBuilder; generators: GeneratorBuilder; @@ -78,9 +72,15 @@ export class DocsBuilder { } /** - * Prepare and cache check + * Prepare (and cache check) */ + this.logger.info( + `Step 1 of 3: Preparing docs for entity ${serializeEntityRef( + this.entity, + )}`, + ); + // Use the in-memory storage for setting and getting etag for this entity. const buildMetadataStorage = new BuildMetadataStorage( this.entity.metadata.uid, @@ -92,6 +92,7 @@ export class DocsBuilder { // make sure to limit checking for cache invalidation to once per minute or so. let preparedDir: string; let etag: string; + try { const preparerResponse = await this.preparer.prepare(this.entity, { etag: buildMetadataStorage.getEtag(), @@ -102,21 +103,32 @@ export class DocsBuilder { } catch (err) { if (err instanceof NotModifiedError) { // No need to prepare anymore since cache is valid. + this.logger.debug( + `Docs for ${serializeEntityRef( + this.entity, + )} are unmodified. Using cache, skipping generate and prepare`, + ); return; } throw new Error(err.message); } this.logger.info( - `TechDocs prepare step completed for entity ${getEntityId(this.entity)}.`, + `Prepare step completed for entity ${serializeEntityRef( + this.entity, + )}, stored at ${preparedDir}`, ); - this.logger.debug(`Prepared files temporarily stored at ${preparedDir}`); /** * Generate */ - this.logger.info(`Running generator on entity ${getEntityId(this.entity)}`); + this.logger.info( + `Step 2 of 3: Generating docs for entity ${serializeEntityRef( + this.entity, + )}`, + ); + // Create a temporary directory to store the generated files in. const tmpdirPath = os.tmpdir(); // Fixes a problem with macOS returning a path that is a symlink @@ -133,13 +145,12 @@ export class DocsBuilder { etag, }); - this.logger.debug(`Generated files temporarily stored at ${outputDir}`); // Remove Prepared directory since it is no longer needed. // Caveat: Can not remove prepared directory in case of git preparer since the // local git repository is used to get etag on subsequent requests. if (this.preparer instanceof UrlPreparer) { this.logger.debug( - `Removing prepared directory ${preparedDir} since the site has been generated.`, + `Removing prepared directory ${preparedDir} since the site has been generated`, ); try { // Not a blocker hence no need to await this. @@ -153,17 +164,23 @@ export class DocsBuilder { * Publish */ - this.logger.info(`Running publisher on entity ${getEntityId(this.entity)}`); + this.logger.info( + `Step 3 of 3: Publishing docs for entity ${serializeEntityRef( + this.entity, + )}`, + ); + await this.publisher.publish({ entity: this.entity, directory: outputDir, }); - this.logger.debug( - `Removing generated directory ${outputDir} since the site has been published`, - ); + try { // Not a blocker hence no need to await this. fs.remove(outputDir); + this.logger.debug( + `Removing generated directory ${outputDir} since the site has been published`, + ); } catch (error) { this.logger.debug(`Error removing generated directory ${error.message}`); } From 6326963c98b97a7f9223c089c9dd49726d6efa48 Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Thu, 4 Mar 2021 14:24:01 -0500 Subject: [PATCH 4/5] Add changeset Signed-off-by: Adam Harvey --- .changeset/old-guests-add.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .changeset/old-guests-add.md diff --git a/.changeset/old-guests-add.md b/.changeset/old-guests-add.md new file mode 100644 index 0000000000..e4f991a1b6 --- /dev/null +++ b/.changeset/old-guests-add.md @@ -0,0 +1,6 @@ +--- +'@backstage/techdocs-common': patch +'@backstage/plugin-techdocs-backend': patch +--- + +Refactor log messaging to improve clarity From a501128dbda8215718ad29409e4ea48cc1c83cb2 Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Thu, 4 Mar 2021 14:33:35 -0500 Subject: [PATCH 5/5] Update changeset to trigger CODEOWNERS Signed-off-by: Adam Harvey --- .changeset/{old-guests-add.md => techdocs-old-guests-add.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .changeset/{old-guests-add.md => techdocs-old-guests-add.md} (100%) diff --git a/.changeset/old-guests-add.md b/.changeset/techdocs-old-guests-add.md similarity index 100% rename from .changeset/old-guests-add.md rename to .changeset/techdocs-old-guests-add.md