From b4bee28f39235cafc0c5c24b76805b6d4586a03f Mon Sep 17 00:00:00 2001 From: Mariana Dematte Date: Tue, 22 Oct 2024 13:54:20 +0200 Subject: [PATCH 1/7] First draft of logging behaviour doc --- documentation/Logging-behaviour.md | 44 ++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 documentation/Logging-behaviour.md diff --git a/documentation/Logging-behaviour.md b/documentation/Logging-behaviour.md new file mode 100644 index 00000000000..19465641238 --- /dev/null +++ b/documentation/Logging-behaviour.md @@ -0,0 +1,44 @@ +## Logging behaviour +MSBuild has a few different built-in loggers, which have different behaviours depending on verbosity. For more information on loggers you can visit the [Microsoft Learn page](ttps://learn.microsoft.com/visualstudio/msbuild/obtaining-build-logs-with-msbuild), or take a look at the [high-level overview of MSBuild](https://github.com/dotnet/msbuild/blob/main/documentation/High-level-overview.md#diagnosability--loggers). + +If you are expecting to see a certain type of message (like test logs) but are unable to find it in one of our loggers, check if the verbosity is correct and if the message has the correct type and importance. + +### Message types +There are various types of messages within MSBuild with different importances and purposes. . +There are some message types that are built-in within the engine, `errors`, `warnings`, and MSBuild engine information. The custom messages, that can come either from the engine or other sources, are selected and displayed based on the `importance` of the message. There can be high, normal, and low importance messages being displayed. + +For more information on custom messages you can more ou Microsoft Learn page for the [MSBuild Message Task](https://learn.microsoft.com/visualstudio/msbuild/message-task) + +### Console logger +Console logger refers to the logger that outputs to the consolse in VS or the terminal that is being used. It is not the default logger after the [.NET 9 update](https://learn.microsoft.com/en-us/dotnet/core/compatibility/sdk/9.0/terminal-logger) but still can be accessed by opting out of the Terminal Logger feature. +The console logger defaults to normal verbosity, and can be overriden by passing the `-verbosity` parameter. +| Verbosity | Quiet | Minimal | Normal | Detailed | Diagnostic | +| --------- | ----- | ------- | ------ | -------- | ---------- | +| Errors |✓| ✓ | ✓| ✓ | ✓ | +| Warnings |✓| ✓ | ✓| ✓ | ✓ | +| High-importance messages | | ✓ | ✓| ✓ | ✓ | +| Normal-importance messages | | | ✓| ✓ | ✓ | +| Low-importance messages | | | | ✓ | ✓ | +| MSBuild engine information | | | | | | + +### Terminal logger +Terminal logger is a new feature which improves the console experience. +For more information on how the terminal logger behaves see the [dotnet build options](https://learn.microsoft.com/dotnet/core/tools/dotnet-build#options) under `-tl` + + +For other messages the display follows the table below: +| Verbosity | Quiet | Minimal | Normal | Detailed | Diagnostic | +| --------- | ----- | ------- | ------ | -------- | ---------- | +| Errors |✓| +| Warnings |✓| +| High-importance messages | +| Normal-importance messages | +| Low-importance messages | +| MSBuild engine information | + +### Text logger +The text logger saves all the build data to a file. It's verbosity is determined by passing the `verbosity` parameter to the command, and it follows the same message display rules as the console logger. + +### Binary logger / build logger +The binary logger is a bit different as it does not have a verbosity option. It includes all messages, projects and files from the build by default. +You can find more information about the binlogs on [MSBuild Github Documentation](https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md). From 47a6ebb17a73ecbba752b4496e2af8c5aef9c236 Mon Sep 17 00:00:00 2001 From: Mariana Dematte Date: Mon, 11 Nov 2024 14:25:18 +0100 Subject: [PATCH 2/7] Filled out missing info --- documentation/Logging-behaviour.md | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/documentation/Logging-behaviour.md b/documentation/Logging-behaviour.md index 19465641238..fe3cf153260 100644 --- a/documentation/Logging-behaviour.md +++ b/documentation/Logging-behaviour.md @@ -1,17 +1,19 @@ ## Logging behaviour -MSBuild has a few different built-in loggers, which have different behaviours depending on verbosity. For more information on loggers you can visit the [Microsoft Learn page](ttps://learn.microsoft.com/visualstudio/msbuild/obtaining-build-logs-with-msbuild), or take a look at the [high-level overview of MSBuild](https://github.com/dotnet/msbuild/blob/main/documentation/High-level-overview.md#diagnosability--loggers). +MSBuild has a few different built-in loggers, which have different behaviours depending on verbosity. For more information on loggers you can visit the [Microsoft Learn page](https://learn.microsoft.com/visualstudio/msbuild/obtaining-build-logs-with-msbuild), or take a look at the [high-level overview of MSBuild](https://github.com/dotnet/msbuild/blob/main/documentation/High-level-overview.md#diagnosability--loggers). If you are expecting to see a certain type of message (like test logs) but are unable to find it in one of our loggers, check if the verbosity is correct and if the message has the correct type and importance. ### Message types -There are various types of messages within MSBuild with different importances and purposes. . -There are some message types that are built-in within the engine, `errors`, `warnings`, and MSBuild engine information. The custom messages, that can come either from the engine or other sources, are selected and displayed based on the `importance` of the message. There can be high, normal, and low importance messages being displayed. +There are various types of messages within MSBuild with different importances and purposes. +There are some message types that are built-in within the engine, `errors`, `warnings`, and MSBuild engine information. The custom messages, that can come either from the engine or other sources, are selected and displayed based on the `importance` of the message. There can be high, normal, and low importance messages being displayed. More detail on which messages are displayed on individual loggers are on their respective sections. For more information on custom messages you can more ou Microsoft Learn page for the [MSBuild Message Task](https://learn.microsoft.com/visualstudio/msbuild/message-task) ### Console logger -Console logger refers to the logger that outputs to the consolse in VS or the terminal that is being used. It is not the default logger after the [.NET 9 update](https://learn.microsoft.com/en-us/dotnet/core/compatibility/sdk/9.0/terminal-logger) but still can be accessed by opting out of the Terminal Logger feature. -The console logger defaults to normal verbosity, and can be overriden by passing the `-verbosity` parameter. +Console logger refers to the logger that outputs to the console in VS or the terminal that is being used. It is not the default logger after the [.NET 9 update](https://learn.microsoft.com/en-us/dotnet/core/compatibility/sdk/9.0/terminal-logger) but still can be accessed by opting out of the Terminal Logger feature. + +The console logger defaults to normal verbosity, and can be overriden by passing the `-verbosity` attribute, or passing the `verbosity` property to the console logger `clp:verbosity={verbosity level}`. + | Verbosity | Quiet | Minimal | Normal | Detailed | Diagnostic | | --------- | ----- | ------- | ------ | -------- | ---------- | | Errors |✓| ✓ | ✓| ✓ | ✓ | @@ -23,21 +25,21 @@ The console logger defaults to normal verbosity, and can be overriden by passing ### Terminal logger Terminal logger is a new feature which improves the console experience. -For more information on how the terminal logger behaves see the [dotnet build options](https://learn.microsoft.com/dotnet/core/tools/dotnet-build#options) under `-tl` +For more information on how the terminal logger behaves see the [dotnet build options](https://learn.microsoft.com/dotnet/core/tools/dotnet-build#options) under `-tl`. +To specify verbosity the `-verbosity` flag or `/tlp:verbosity={verbosity level}` -For other messages the display follows the table below: | Verbosity | Quiet | Minimal | Normal | Detailed | Diagnostic | | --------- | ----- | ------- | ------ | -------- | ---------- | -| Errors |✓| -| Warnings |✓| -| High-importance messages | +| Errors |✓| ✓ | ✓| ✓ | ✓ | +| Warnings |✓| ✓ | ✓| ✓ | ✓ | +| High-importance messages | | | | ✓ | ✓ | | Normal-importance messages | | Low-importance messages | | MSBuild engine information | -### Text logger -The text logger saves all the build data to a file. It's verbosity is determined by passing the `verbosity` parameter to the command, and it follows the same message display rules as the console logger. +### File logger +The File logger saves all the build data to a file. It's verbosity is determined by passing the `verbosity` parameter to the `flp` attribute, or the default is set to `diagnostic`, and it follows the same message display rules as the console logger. ### Binary logger / build logger The binary logger is a bit different as it does not have a verbosity option. It includes all messages, projects and files from the build by default. From acb25a066c6f9f020cbef9a217e88ee76a0f715f Mon Sep 17 00:00:00 2001 From: Mariana Dematte Date: Mon, 18 Nov 2024 15:39:41 +0100 Subject: [PATCH 3/7] PR comments --- documentation/Logging-behaviour.md | 35 +++++++++++++++--------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/documentation/Logging-behaviour.md b/documentation/Logging-behaviour.md index fe3cf153260..48a4dafabce 100644 --- a/documentation/Logging-behaviour.md +++ b/documentation/Logging-behaviour.md @@ -9,20 +9,6 @@ There are some message types that are built-in within the engine, `errors`, `war For more information on custom messages you can more ou Microsoft Learn page for the [MSBuild Message Task](https://learn.microsoft.com/visualstudio/msbuild/message-task) -### Console logger -Console logger refers to the logger that outputs to the console in VS or the terminal that is being used. It is not the default logger after the [.NET 9 update](https://learn.microsoft.com/en-us/dotnet/core/compatibility/sdk/9.0/terminal-logger) but still can be accessed by opting out of the Terminal Logger feature. - -The console logger defaults to normal verbosity, and can be overriden by passing the `-verbosity` attribute, or passing the `verbosity` property to the console logger `clp:verbosity={verbosity level}`. - -| Verbosity | Quiet | Minimal | Normal | Detailed | Diagnostic | -| --------- | ----- | ------- | ------ | -------- | ---------- | -| Errors |✓| ✓ | ✓| ✓ | ✓ | -| Warnings |✓| ✓ | ✓| ✓ | ✓ | -| High-importance messages | | ✓ | ✓| ✓ | ✓ | -| Normal-importance messages | | | ✓| ✓ | ✓ | -| Low-importance messages | | | | ✓ | ✓ | -| MSBuild engine information | | | | | | - ### Terminal logger Terminal logger is a new feature which improves the console experience. For more information on how the terminal logger behaves see the [dotnet build options](https://learn.microsoft.com/dotnet/core/tools/dotnet-build#options) under `-tl`. @@ -38,9 +24,24 @@ To specify verbosity the `-verbosity` flag or `/tlp:verbosity={verbosity level}` | Low-importance messages | | MSBuild engine information | +### Binary logger / build logger +The binary logger does not have a verbosity option. It includes all messages, projects and files from the build by default. +You can find more information about the binlogs on [MSBuild Github Documentation](https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md). + +### Console logger +Console logger refers to the logger that outputs to the console in VS or the terminal that is being used. It is not the default logger after the [.NET 9 update](https://learn.microsoft.com/en-us/dotnet/core/compatibility/sdk/9.0/terminal-logger) but still can be accessed by opting out of the Terminal Logger feature. + +The console logger defaults to normal verbosity, and can be overriden by passing the `-verbosity` attribute, or passing the `verbosity` property to the console logger `clp:verbosity={verbosity level}`. + +| Verbosity | Quiet | Minimal | Normal | Detailed | Diagnostic | +| --------- | ----- | ------- | ------ | -------- | ---------- | +| Errors |✓| ✓ | ✓| ✓ | ✓ | +| Warnings |✓| ✓ | ✓| ✓ | ✓ | +| High-importance messages | | ✓ | ✓| ✓ | ✓ | +| Normal-importance messages | | | ✓| ✓ | ✓ | +| Low-importance messages | | | | ✓ | ✓ | +| MSBuild engine information | | | | | | + ### File logger The File logger saves all the build data to a file. It's verbosity is determined by passing the `verbosity` parameter to the `flp` attribute, or the default is set to `diagnostic`, and it follows the same message display rules as the console logger. -### Binary logger / build logger -The binary logger is a bit different as it does not have a verbosity option. It includes all messages, projects and files from the build by default. -You can find more information about the binlogs on [MSBuild Github Documentation](https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md). From f932e52fdfc5bdd0088b3b3f9080b8af957069ee Mon Sep 17 00:00:00 2001 From: Mariana Dematte Date: Mon, 18 Nov 2024 15:46:38 +0100 Subject: [PATCH 4/7] More PR revisions --- documentation/Logging-behaviour.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/Logging-behaviour.md b/documentation/Logging-behaviour.md index 48a4dafabce..fec263992ef 100644 --- a/documentation/Logging-behaviour.md +++ b/documentation/Logging-behaviour.md @@ -7,7 +7,7 @@ If you are expecting to see a certain type of message (like test logs) but are u There are various types of messages within MSBuild with different importances and purposes. There are some message types that are built-in within the engine, `errors`, `warnings`, and MSBuild engine information. The custom messages, that can come either from the engine or other sources, are selected and displayed based on the `importance` of the message. There can be high, normal, and low importance messages being displayed. More detail on which messages are displayed on individual loggers are on their respective sections. -For more information on custom messages you can more ou Microsoft Learn page for the [MSBuild Message Task](https://learn.microsoft.com/visualstudio/msbuild/message-task) +For more information on custom messages please reference the Microsoft Learn page for the MSBuild [Message](https://learn.microsoft.com/visualstudio/msbuild/message-task) Task. ### Terminal logger Terminal logger is a new feature which improves the console experience. @@ -25,7 +25,7 @@ To specify verbosity the `-verbosity` flag or `/tlp:verbosity={verbosity level}` | MSBuild engine information | ### Binary logger / build logger -The binary logger does not have a verbosity option. It includes all messages, projects and files from the build by default. +The binary logger does not have a verbosity option. It includes all messages, projects and files from the build by default. It is intended to be a tooling-friendly way to get detailed information about what happened during a build, for analysis or automated processing. You can find more information about the binlogs on [MSBuild Github Documentation](https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md). ### Console logger From 76411a0f1b9370583ab12e71845bb6dd5219703a Mon Sep 17 00:00:00 2001 From: Mariana Dematte Date: Mon, 18 Nov 2024 17:07:24 +0100 Subject: [PATCH 5/7] PR revisions once again --- documentation/Logging-behaviour.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/documentation/Logging-behaviour.md b/documentation/Logging-behaviour.md index fec263992ef..3856556f91a 100644 --- a/documentation/Logging-behaviour.md +++ b/documentation/Logging-behaviour.md @@ -10,7 +10,7 @@ There are some message types that are built-in within the engine, `errors`, `war For more information on custom messages please reference the Microsoft Learn page for the MSBuild [Message](https://learn.microsoft.com/visualstudio/msbuild/message-task) Task. ### Terminal logger -Terminal logger is a new feature which improves the console experience. +Terminal logger is a new feature which improves the console experience for end users by focusing the output on the diagnostics raised from a build for each project. It also allows users to see at-a-glance information about how the engine is building their projects at any time. It is opinionated and explicitly hides some build messages and output to deliver a more streamlined end-user experience. Users that need more detailed output should use the [console logger](#console-logger) or a [binary log](#binary-logger-build-logger) along with the [Structured Log Viewer](https://msbuildlog.com/) to drive their investigations. For more information on how the terminal logger behaves see the [dotnet build options](https://learn.microsoft.com/dotnet/core/tools/dotnet-build#options) under `-tl`. To specify verbosity the `-verbosity` flag or `/tlp:verbosity={verbosity level}` @@ -26,11 +26,14 @@ To specify verbosity the `-verbosity` flag or `/tlp:verbosity={verbosity level}` ### Binary logger / build logger The binary logger does not have a verbosity option. It includes all messages, projects and files from the build by default. It is intended to be a tooling-friendly way to get detailed information about what happened during a build, for analysis or automated processing. + You can find more information about the binlogs on [MSBuild Github Documentation](https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md). ### Console logger Console logger refers to the logger that outputs to the console in VS or the terminal that is being used. It is not the default logger after the [.NET 9 update](https://learn.microsoft.com/en-us/dotnet/core/compatibility/sdk/9.0/terminal-logger) but still can be accessed by opting out of the Terminal Logger feature. +The console logger is a 1:1 textual representation of the data that are emitted during the build. It attempts small amounts of formatting, but it writes received messages from all of the worker nodes in an unbuffered format so can be difficult to follow the chain of execution. + The console logger defaults to normal verbosity, and can be overriden by passing the `-verbosity` attribute, or passing the `verbosity` property to the console logger `clp:verbosity={verbosity level}`. | Verbosity | Quiet | Minimal | Normal | Detailed | Diagnostic | From ba134578239cc5c761c2ad2df239d4a75556e18f Mon Sep 17 00:00:00 2001 From: Mariana Dematte Date: Mon, 18 Nov 2024 17:17:18 +0100 Subject: [PATCH 6/7] Forgot to save before commiting changes --- documentation/Logging-behaviour.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/Logging-behaviour.md b/documentation/Logging-behaviour.md index 3856556f91a..af8187970a0 100644 --- a/documentation/Logging-behaviour.md +++ b/documentation/Logging-behaviour.md @@ -5,7 +5,7 @@ If you are expecting to see a certain type of message (like test logs) but are u ### Message types There are various types of messages within MSBuild with different importances and purposes. -There are some message types that are built-in within the engine, `errors`, `warnings`, and MSBuild engine information. The custom messages, that can come either from the engine or other sources, are selected and displayed based on the `importance` of the message. There can be high, normal, and low importance messages being displayed. More detail on which messages are displayed on individual loggers are on their respective sections. +Some message types are built-in within the engine, such as `errors`, `warnings`, and MSBuild engine information. Others are custom messages, that can come either from the engine or other sources, and are selected and displayed based on the `importance` of the message. There can be high, normal, and low importance messages being displayed. More detail on which messages are displayed on individual loggers are on their respective sections. For more information on custom messages please reference the Microsoft Learn page for the MSBuild [Message](https://learn.microsoft.com/visualstudio/msbuild/message-task) Task. From 25c80f9cec179daed2d4809e82df8a34ee2af97d Mon Sep 17 00:00:00 2001 From: Mariana Dematte Date: Wed, 11 Dec 2024 14:33:52 +0100 Subject: [PATCH 7/7] behaviour -> behavior --- documentation/{Logging-behaviour.md => Logging-behavior.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename documentation/{Logging-behaviour.md => Logging-behavior.md} (92%) diff --git a/documentation/Logging-behaviour.md b/documentation/Logging-behavior.md similarity index 92% rename from documentation/Logging-behaviour.md rename to documentation/Logging-behavior.md index af8187970a0..ee71a236c05 100644 --- a/documentation/Logging-behaviour.md +++ b/documentation/Logging-behavior.md @@ -1,5 +1,5 @@ -## Logging behaviour -MSBuild has a few different built-in loggers, which have different behaviours depending on verbosity. For more information on loggers you can visit the [Microsoft Learn page](https://learn.microsoft.com/visualstudio/msbuild/obtaining-build-logs-with-msbuild), or take a look at the [high-level overview of MSBuild](https://github.com/dotnet/msbuild/blob/main/documentation/High-level-overview.md#diagnosability--loggers). +## Logging behavior +MSBuild has a few different built-in loggers, which have different behaviors depending on verbosity. For more information on loggers you can visit the [Microsoft Learn page](https://learn.microsoft.com/visualstudio/msbuild/obtaining-build-logs-with-msbuild), or take a look at the [high-level overview of MSBuild](https://github.com/dotnet/msbuild/blob/main/documentation/High-level-overview.md#diagnosability--loggers). If you are expecting to see a certain type of message (like test logs) but are unable to find it in one of our loggers, check if the verbosity is correct and if the message has the correct type and importance.