Speclet for terminallogger progress

terminal-logger-progress.md

Progress speclet

• allows to specify the progress of the task
• allows describing the overall operation
• allows describing the 'instant' state
• allows determinate status (x/y)
• allows indeterminate status

Example API usage:

var reporter = LoggingService.GetProgressReporter("Test under linux-x64");
// Terminal Logger at this point starts rendering a progress tracker that looks something like
// Test under linux-x64: [-------------------]

int succeeded = 10;
int failed = 5;
int skipped = 2;
int total = 100;

// run tests

// periodically report progress. percentage is optional, if not specified an indeterminate progress is shown
// description is optional, if not specified only a progress bar is shown
// if description is too long to render a reasonable progress, description may be truncated
reporter.ReportProgress(percentage: (10 + 5 + 2)/100, description: $"{succeeded} succeeded, {failed} failed, {skipped} skipped");
// Terminal Logger at this point renders a progress tracker that looks something like
//      Test under linux-x64: [##########---------] 10 succeeded, 5 failed, 2 skipped (17%)
// NOTE: the layout coulod change - for example this might also be viable:
//      Test under linux-x64: [##########---------(10 succeeded, 5 failed, 2 skipped)] (17%)
// The key concept is that these are just rearrangements of the same core sections (defined below).

// finish the operation
reporter.CompleteProgress(finalMessage: $"{succeeded} succeeded, {failed} failed, {skipped} skipped, {total} tests run.");
// the MSbuild Logging engine would send a final summary message to the binlog
// terminal logger may show the completed progress item for a period of time, but the progress-reporting area may clear 
// as the overall projects are completed.

The overall progress reporting in Terminal Logger specifically should be thought of as a new 'area' of the rendering. Today we have a 'project summary' area and a 'node status' area. Progress would be reported in a new area in between the two. Each progress item would have its own line, and each line would have up to 4 components:

• The name of the progress item, set by GetProgressReporter
• The progress bar, which is a visual representation of the progress. This could be showing a known or unknown quantity of work items.
• An optional description, which is a textual representation/summary of the progress shown in the bar.
• An optional percentage, which is shown if the progress is deterministic.

Questions for the engine:

• what frequency/how should messages from child nodes be sent to the central node, to not swamp the system?
• how should rendering of the description be controlled? Is allowing users to emit their own ANSI codes for color/etc fine for now?

References:

• Work Done Progress in the LSP Spec

I can see this working well:

 Test under linux-x64: [##########---------] (17%) 10 succeeded, 5 failed, 2 skipped                  Passed Abc (time)
So basically
<text> : <your progress + percent> <left text> <right text> (optional time)

Lot of random thoughts here:

• please add duration

• please let us colorize the texts, I will try my best to not communicate essential information just by color

• can the complete message be multiline?

• How do we report summary for all projects (like the test summary that is now hardcoded in terminal logger)?

Today we have a 'project summary' area and a 'node status' area. Progress would be reported in a new area in between the two.

What if the nodes take 2 lines if the are reporting progress? That way I don't have to repeat the information twice on the screen, and user does not have to connect info from 16 nodes to progress from 16 nodes.

• if the info does not fit on the screen horizontally, will it shrink somehow? For example for us the Test under linux-x64: is not so useful if the node would be reported right above. But if not and it would be project name and tfm, then it is essential.

Feedback from meeting today:

please add duration

Agreed - the overall duration of the 'progress operation' should be reportable

can the complete message be multiline

This seems very reasonable - the example above is meant to be illustrative but not exhaustive.

How do we report summary for all projects (like the test summary that is now hardcoded in terminal logger)?

This might be solvable when an MSBuild XML expression of the Task API - e.g. CreateProgress/ReportProgress/FinishProgress Tasks that authors could use in their targets.

please let us colorize the texts, I will try my best to not communicate essential information just by color

We want to not solve this with the progress APIs - we want to solve this uniformly across MSBuild's Message logging infrastructure in another issue.

general formatting rendering questions

We need to do more design work here, the above examples aren't locked-in by any means! The team already has a few ideas to try out around where the progress should appear and how it should render in circumstances like small viewports, etc.

Some kind of IsEnabled flag would need to be available for Managed Code Task authors and MSBuild logic authors to see if progress reporting is supported for the current session to avoid taking the perf hit.