@backstage/plugin-scaffolder-backend 1.7.0 → 1.8.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @backstage/plugin-scaffolder-backend
 
+## 1.8.0-next.0
+
+### Minor Changes
+
+- ea14eb62a2: Added a set of default Prometheus metrics around scaffolding. See below for a list of metrics and an explanation of their labels:
+
+  - `scaffolder_task_count`: Tracks successful task runs.
+
+    Labels:
+
+    - `template`: The entity ref of the scaffolded template
+    - `user`: The entity ref of the user that invoked the template run
+    - `result`: A string describing whether the task ran successfully, failed, or was skipped
+
+  - `scaffolder_task_duration`: a histogram which tracks the duration of a task run
+
+    Labels:
+
+    - `template`: The entity ref of the scaffolded template
+    - `result`: A boolean describing whether the task ran successfully
+
+  - `scaffolder_step_count`: a count that tracks each step run
+
+    Labels:
+
+    - `template`: The entity ref of the scaffolded template
+    - `step`: The name of the step that was run
+    - `result`: A string describing whether the task ran successfully, failed, or was skipped
+
+  - `scaffolder_step_duration`: a histogram which tracks the duration of each step run
+
+    Labels:
+
+    - `template`: The entity ref of the scaffolded template
+    - `step`: The name of the step that was run
+    - `result`: A string describing whether the task ran successfully, failed, or was skipped
+
+  You can find a guide for running Prometheus metrics here: https://github.com/backstage/backstage/blob/master/contrib/docs/tutorials/prometheus-metrics.md
+
+### Patch Changes
+
+- 7573b65232: Internal refactor of imports to avoid circular dependencies
+- Updated dependencies
+  - @backstage/backend-common@0.16.0-next.0
+  - @backstage/plugin-catalog-backend@1.5.1-next.0
+  - @backstage/integration@1.4.0-next.0
+  - @backstage/backend-tasks@0.3.7-next.0
+  - @backstage/catalog-model@1.1.3-next.0
+  - @backstage/plugin-auth-node@0.2.7-next.0
+  - @backstage/types@1.0.1-next.0
+  - @backstage/backend-plugin-api@0.1.4-next.0
+  - @backstage/plugin-catalog-node@1.2.1-next.0
+  - @backstage/catalog-client@1.1.2-next.0
+  - @backstage/config@1.0.4-next.0
+  - @backstage/errors@1.1.3-next.0
+  - @backstage/plugin-scaffolder-common@1.2.2-next.0
+
 ## 1.7.0
 
 ### Minor Changes

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-scaffolder-backend",
-  "version": "1.7.0",
+  "version": "1.8.0-next.0",
   "main": "../dist/index.cjs.js",
   "types": "../dist/index.alpha.d.ts"
 }

package/dist/index.cjs.js

@@ -30,6 +30,7 @@ var winston = require('winston');
 var nunjucks = require('nunjucks');
 var lodash = require('lodash');
 var jsonschema = require('jsonschema');
+var promClient = require('prom-client');
 var pluginScaffolderCommon = require('@backstage/plugin-scaffolder-common');
 var express = require('express');
 var Router = require('express-promise-router');
@@ -4188,6 +4189,23 @@ function generateExampleOutput(schema) {
   return "<unknown>";
 }
 
+function createCounterMetric(config) {
+  let metric = promClient.register.getSingleMetric(config.name);
+  if (!metric) {
+    metric = new promClient.Counter(config);
+    promClient.register.registerMetric(metric);
+  }
+  return metric;
+}
+function createHistogramMetric(config) {
+  let metric = promClient.register.getSingleMetric(config.name);
+  if (!metric) {
+    metric = new promClient.Histogram(config);
+    promClient.register.registerMetric(metric);
+  }
+  return metric;
+}
+
 const isValidTaskSpec = (taskSpec) => {
   return taskSpec.apiVersion === "scaffolder.backstage.io/v1beta3";
 };
@@ -4217,6 +4235,7 @@ const createStepLogger = ({
 class NunjucksWorkflowRunner {
   constructor(options) {
     this.options = options;
+    this.tracker = scaffoldingTracker();
   }
   isSingleTemplateString(input) {
     var _a, _b;
@@ -4287,16 +4306,15 @@ class NunjucksWorkflowRunner {
       additionalTemplateGlobals: this.options.additionalTemplateGlobals
     });
     try {
+      const taskTrack = await this.tracker.taskStart(task);
       await fs__default["default"].ensureDir(workspacePath);
-      await task.emitLog(
-        `Starting up task with ${task.spec.steps.length} steps`
-      );
       const context = {
         parameters: task.spec.parameters,
         steps: {},
         user: task.spec.user
       };
       for (const step of task.spec.steps) {
+        const stepTrack = await this.tracker.stepStart(task, step);
         try {
           if (step.if) {
             const ifResult = await this.render(
@@ -4305,17 +4323,10 @@ class NunjucksWorkflowRunner {
               renderTemplate
             );
             if (!isTruthy(ifResult)) {
-              await task.emitLog(
-                `Skipping step ${step.id} because it's if condition was false`,
-                { stepId: step.id, status: "skipped" }
-              );
+              await stepTrack.skipFalsy();
               continue;
             }
           }
-          await task.emitLog(`Beginning step ${step.name}`, {
-            stepId: step.id,
-            status: "processing"
-          });
           const action = this.options.actionRegistry.get(step.action);
           const { taskLogger, streamLogger } = createStepLogger({ task, step });
           if (task.isDryRun) {
@@ -4341,13 +4352,7 @@ class NunjucksWorkflowRunner {
               )}`
             );
             if (!action.supportsDryRun) {
-              task.emitLog(
-                `Skipping because ${action.id} does not support dry-run`,
-                {
-                  stepId: step.id,
-                  status: "skipped"
-                }
-              );
+              await taskTrack.skipDryRun(step, action);
               const outputSchema = (_c = action.schema) == null ? void 0 : _c.output;
               if (outputSchema) {
                 context.steps[step.id] = {
@@ -4402,19 +4407,15 @@ class NunjucksWorkflowRunner {
             await fs__default["default"].remove(tmpDir);
           }
           context.steps[step.id] = { output: stepOutput };
-          await task.emitLog(`Finished step ${step.name}`, {
-            stepId: step.id,
-            status: "completed"
-          });
+          await stepTrack.markSuccessful();
         } catch (err) {
-          await task.emitLog(String(err.stack), {
-            stepId: step.id,
-            status: "failed"
-          });
+          await taskTrack.markFailed(step, err);
+          await stepTrack.markFailed();
           throw err;
         }
       }
       const output = this.render(task.spec.output, context, renderTemplate);
+      await taskTrack.markSuccessful();
       return { output };
     } finally {
       if (workspacePath) {
@@ -4423,6 +4424,116 @@ class NunjucksWorkflowRunner {
     }
   }
 }
+function scaffoldingTracker() {
+  const taskCount = createCounterMetric({
+    name: "scaffolder_task_count",
+    help: "Count of task runs",
+    labelNames: ["template", "user", "result"]
+  });
+  const taskDuration = createHistogramMetric({
+    name: "scaffolder_task_duration",
+    help: "Duration of a task run",
+    labelNames: ["template", "result"]
+  });
+  const stepCount = createCounterMetric({
+    name: "scaffolder_step_count",
+    help: "Count of step runs",
+    labelNames: ["template", "step", "result"]
+  });
+  const stepDuration = createHistogramMetric({
+    name: "scaffolder_step_duration",
+    help: "Duration of a step runs",
+    labelNames: ["template", "step", "result"]
+  });
+  async function taskStart(task) {
+    var _a, _b;
+    await task.emitLog(`Starting up task with ${task.spec.steps.length} steps`);
+    const template = ((_a = task.spec.templateInfo) == null ? void 0 : _a.entityRef) || "";
+    const user = ((_b = task.spec.user) == null ? void 0 : _b.ref) || "";
+    const taskTimer = taskDuration.startTimer({
+      template
+    });
+    async function skipDryRun(step, action) {
+      task.emitLog(`Skipping because ${action.id} does not support dry-run`, {
+        stepId: step.id,
+        status: "skipped"
+      });
+    }
+    async function markSuccessful() {
+      taskCount.inc({
+        template,
+        user,
+        result: "ok"
+      });
+      taskTimer({ result: "ok" });
+    }
+    async function markFailed(step, err) {
+      await task.emitLog(String(err.stack), {
+        stepId: step.id,
+        status: "failed"
+      });
+      taskCount.inc({
+        template,
+        user,
+        result: "failed"
+      });
+      taskTimer({ result: "failed" });
+    }
+    return {
+      skipDryRun,
+      markSuccessful,
+      markFailed
+    };
+  }
+  async function stepStart(task, step) {
+    var _a;
+    await task.emitLog(`Beginning step ${step.name}`, {
+      stepId: step.id,
+      status: "processing"
+    });
+    const template = ((_a = task.spec.templateInfo) == null ? void 0 : _a.entityRef) || "";
+    const stepTimer = stepDuration.startTimer({
+      template,
+      step: step.name
+    });
+    async function markSuccessful() {
+      await task.emitLog(`Finished step ${step.name}`, {
+        stepId: step.id,
+        status: "completed"
+      });
+      stepCount.inc({
+        template,
+        step: step.name,
+        result: "ok"
+      });
+      stepTimer({ result: "ok" });
+    }
+    async function markFailed() {
+      stepCount.inc({
+        template,
+        step: step.name,
+        result: "failed"
+      });
+      stepTimer({ result: "failed" });
+    }
+    async function skipFalsy() {
+      await task.emitLog(
+        `Skipping step ${step.id} because its if condition was false`,
+        { stepId: step.id, status: "skipped" }
+      );
+      stepTimer({ result: "skipped" });
+    }
+    return {
+      markSuccessful,
+      markFailed,
+      skipFalsy
+    };
+  }
+  return {
+    taskStart,
+    stepStart
+  };
+}
 
 class TaskWorker {
   constructor(options) {