Upload flame graph report to pipeline timeline when System.Debug is…

… `true` (#1363)

* Attach flamegraph report to pipeline timeline when `System.Debug` is `true`

* Add documentation

* Fix formatting

.github/ISSUE_TEMPLATE/bug_report.md

@@ -25,8 +25,9 @@ Steps to reproduce the behavior:
 **Expected behavior**
 A clear and concise description of what you expected to happen.
 
-**Screenshots**
-If applicable, add screenshots to help explain your problem.
+**Logs and screenshots**
+If applicable, include relevant logs or screenshots to help explain your problem.
+See [extension troubleshooting](https://github.com/tinglesoftware/dependabot-azure-devops/blob/main/docs/extension.md#troubleshooting-issues) for more on how to collect additional diagnostic logs.
 
 **Extension (please complete the following information):**
  - Host: [e.g. Azure DevOps, Azure DevOps Server]

docs/extension.md

@@ -2,6 +2,7 @@
 # Table of Contents
 
 - [Using the extension](#using-the-extension)
+- [Troubleshooting issues](#troubleshooting-issues)
 - [Development guide](#development-guide)
    * [Getting the development environment ready](#getting-the-development-environment-ready)
    * [Building the extension](#building-the-extension)
@@ -16,6 +17,15 @@
 
 Refer to the extension [README.md](../extension/README.md).
 
+# Troubleshooting issues
+
+Dependabot will log more diagnostic information when [verbose logs are enabled](https://learn.microsoft.com/en-us/azure/devops/pipelines/troubleshooting/review-logs?view=azure-devops&tabs=windows-agent#configure-verbose-logs); i.e. `system.debug` variable is set to `true`.
+
+When verbose logs are enable, Dependabot will also generate a [Flame Graph performance metrics report](https://www.brendangregg.com/flamegraphs.html), which can be viewed by [downloading the pipeline logs](https://learn.microsoft.com/en-us/azure/devops/pipelines/troubleshooting/review-logs?view=azure-devops&tabs=windows-agent#view-and-download-logs), then locating the corresponding HTML report file in the `Job` folder. To understand how to read Flame Graph reports, see: https://www.brendangregg.com/flamegraphs.html#summary
+
+> [!WARNING]
+> When sharing pipeline logs, please be aware that the **task log contains potentionally sensitive information** such as your DevOps organisation name, project names, repository names, private package feeds URLs, list of used dependency names/versions, and the contents of any dependency files that are updated (e.g. `package.json`, `*.csproj`, etc). The Flame Graph report does **not** contain any sensitive information about your DevOps environment.
+
 # Development guide
 
 ## Getting the development environment ready

extension/.gitignore

@@ -1,4 +1,5 @@
 node_modules
 .taskkey
 **/*.js
-*.vsix
+*.vsix
+*flamegraph.html

extension/tasks/dependabotV2/index.ts

@@ -66,6 +66,7 @@ async function run() {
       collectorImage: undefined, // TODO: Add config for this?
       proxyImage: undefined, // TODO: Add config for this?
       updaterImage: undefined, // TODO: Add config for this?
+      flamegraph: taskInputs.debug,
     };
 
     // If update identifiers are specified, select them; otherwise handle all

extension/tasks/dependabotV2/utils/dependabot-cli/DependabotCli.ts

@@ -1,4 +1,4 @@
-import { debug, error, tool, which } from 'azure-pipelines-task-lib/task';
+import { command, debug, error, tool, which } from 'azure-pipelines-task-lib/task';
 import { ToolRunner } from 'azure-pipelines-task-lib/toolrunner';
 import * as fs from 'fs';
 import * as yaml from 'js-yaml';
@@ -44,6 +44,7 @@ export class DependabotCli {
       collectorImage?: string;
       proxyImage?: string;
       updaterImage?: string;
+      flamegraph?: boolean;
     },
   ): Promise<IDependabotUpdateOperationResult[] | undefined> {
     // Find the dependabot tool path, or install it if missing
@@ -62,7 +63,7 @@ export class DependabotCli {
     // Compile dependabot cmd arguments
     // See: https://github.com/dependabot/cli/blob/main/cmd/dependabot/internal/cmd/root.go
     //      https://github.com/dependabot/cli/blob/main/cmd/dependabot/internal/cmd/update.go
-    let dependabotArguments = ['update', '-f', jobInputPath, '-o', jobOutputPath];
+    let dependabotArguments = ['update', '--file', jobInputPath, '--output', jobOutputPath];
     if (options?.collectorImage) {
       dependabotArguments.push('--collector-image', options.collectorImage);
     }
@@ -72,6 +73,9 @@ export class DependabotCli {
     if (options?.updaterImage) {
       dependabotArguments.push('--updater-image', options.updaterImage);
     }
+    if (options?.flamegraph) {
+      dependabotArguments.push('--flamegraph');
+    }
 
     // Generate the job input file
     writeJobConfigFile(jobInputPath, operation);
@@ -94,6 +98,15 @@ export class DependabotCli {
       }
     }
 
+    // If flamegraph is enabled, upload the report to the pipeline timeline so the use can download it
+    const flamegraphPath = path.join(process.cwd(), 'flamegraph.html');
+    if (options?.flamegraph && fs.existsSync(flamegraphPath)) {
+      const jobFlamegraphPath = path.join(process.cwd(), `dependabot-${operation.job.id}-flamegraph.html`);
+      fs.renameSync(flamegraphPath, jobFlamegraphPath);
+      console.info(`Uploading flamegraph report '${jobFlamegraphPath}' to pipeline timeline...`);
+      command('task.uploadfile', {}, jobFlamegraphPath);
+    }
+
     // Process the job output
     const operationResults = Array<IDependabotUpdateOperationResult>();
     if (fs.existsSync(jobOutputPath)) {