sqlwriter logging : minor formatting updates and corrections

Author: Guillaume-Fourrat

docs/relational-databases/backup-restore/sql-server-vss-writer-logging.md

@@ -20,17 +20,17 @@ As [SQL Server Back up Applications - Volume Shadow Copy Service (VSS) and SQL W
 
 ## Overview
 
-[!INCLUDE [sssql19-md](../../includes/sssql19-md.md)] introduces a new Logging feature for its VSS  Writer “SQLWriter” service. Its main characteristics are:
+[!INCLUDE [sssql19-md](../../includes/sssql19-md.md)] introduces a new Logging feature for its VSS  Writer `SQLWriter` service. Its main characteristics are:
 
 - It's on by default
 - It's system-wide (it will trace SQL Writer activity against all SQL Server instances running on the server)
 - It's text-based
-- Its working directory is **C:\Program Files\Microsoft SQL Server\90\Shared**
+- Its working directory is **`C:\Program Files\Microsoft SQL Server\90\Shared`**
 - Within that directory:
-  - Logging takes place in file **SqlWriterLogger.txt**
-  - This file gets renamed to “SqlWriterLogger1.txt” when reaching a maximum size (by default 1 MB), with logging continuing in main SqlWriterLogger.txt. 
-  - There's only one rollover file, so the second rollover would overwrite the existing SqlWriterLogger1.txt.
-  - Parameters are managed by file **SqlWriterConfig.ini**
+  - Logging takes place in file **`SqlWriterLogger.txt`**
+  - This file gets renamed to `SqlWriterLogger1.txt` when reaching a maximum size (by default 1 MB), with logging continuing in main `SqlWriterLogger.txt`. 
+  - There's only one rollover file, so the second rollover would overwrite the existing `SqlWriterLogger1.txt`.
+  - Parameters are managed by file **`SqlWriterConfig.ini`**
 
 SQL Writer being a [!INCLUDE[ssSQL11](../../includes/ssnoversion-md.md)] shared component, it has a single instance on a system and its major version will be the same as the highest major version of any installed [!INCLUDE[ssSQL11](../../includes/ssnoversion-md.md)] Instance. For example, if instances of, say,[!INCLUDE[ssSQL11](../../includes/sssql11-md.md)], [!INCLUDE[ssSQL14](../../includes/sssql14-md.md)], [!INCLUDE[sssql15-md](../../includes/sssql16-md.md)] SP2 and [!INCLUDE[sssql19-md](../../includes/sssql19-md.md)] are collocated on the same system, the SQL Writer binary will be the one provided by [!INCLUDE[sssql19-md](../../includes/sssql19-md.md)] and will service all running instances from all major versions (even though its home directory remains under \90). Local instances and versions will benefit from the new [!INCLUDE[sssql19-md](../../includes/sssql19-md.md)] tracing described here. It also implies that only [!INCLUDE[sssql19-md](../../includes/sssql19-md.md)] cumulative updates will upgrade SQL Writer binaries in this situation.
 
@@ -39,7 +39,7 @@ SQL Writer being a [!INCLUDE[ssSQL11](../../includes/ssnoversion-md.md)] shared
 
 ## Basic Operations
 
-You can benefit from the new logging without any manual change. You can open, or get a copy of, the main SqlWriterLogger.txt log file in “C:\Program Files\Microsoft SQL Server\90\Shared\”.
+You can benefit from the new logging without any manual change. You can open, or get a copy of, the main `SqlWriterLogger.txt` log file in `C:\Program Files\Microsoft SQL Server\90\Shared\`.
 The file will reflect all VSS events reaching SQL Writer, which would mainly be:
 - `OnIdentify` events, as triggered by command `vssadmin list writers`
 - Backup events
@@ -93,12 +93,12 @@ In order of appearance, we can see the following information is logged:
 [01/12/2021 08:23:40, TID 464c] Skip User Instances Enumeration
 ```
 
-OnIdentify is a common VSS operation. It's triggered by “vssadmin list writers” command. Most VSS requestors would start any VSS backup or restore operation by a “OnIdentify” event.
+OnIdentify is a common VSS operation. It's triggered by `vssadmin list writers` command. Most VSS requestors would start any VSS backup or restore operation by a `OnIdentify` event.
 
 Previously, only active profiler tracing would allow the DBA to detect such an event. With the new logging feature, each event will lead to the above entry.
 
 In order of appearance, we can see the following information is logged:
-- An explicit mention of the OnIdentify VSS event.
+- An explicit mention of the `OnIdentify` VSS event.
 - A list of all active (running) [!INCLUDE[ssSQL11](../../includes/ssnoversion-md.md)] instances, along with their instance name, major version, and Edition.
 - The indication we didn’t attempt to list “User Instances” – a specific [!INCLUDE[ssSQL11](../../includes/ssnoversion-md.md)] feature also known as [LocalDB](/sql/database-engine/configure-windows/sql-server-express-localdb) and typically not involved on enterprise database servers.
 
@@ -138,29 +138,29 @@ In order of appearance, we can see the following information is logged:
 This event leads to a more sizeable set of entries.
 In order of appearance, we can see the following information is logged:
 
-- A full “OnIdentify” section, which as already indicated often leads a backup.
+- A full `OnIdentify` section, which as already indicated often leads a backup.
 - Mention of every main VSS phase of backup, with pattern “Entering SQL Writer xxxx”.
-  -  First one here being ‘Entering SQL Writer OnPrepareBackup.
+  -  First one here being `Entering SQL Writer OnPrepareBackup`.
 - A conspicuous entry indicating the start of a VSS SQL Backup 
   - (ID being the threadId that is doing the logging for that backup attempt in SQLWriter)
 - The VSS backup API selected by the VSS requestor, “component” or “non-component / Volume”
 - The count of Databases included in the component-list sent by VSS requestor, here a single DB (1).
 - A confirmation that each Requestor-provided database name (here ‘db_on_G’) is found (or not found) on the [!INCLUDE[ssSQL11](../../includes/ssnoversion-md.md)] instance it’s been associated with by the VSS requestor (here default instance ‘GF19’).
-- The Flavor of VSS backup requested. Usually VSS_BT_FULL or VSS_BT_COPY. See the VSS_BACKUP_TYPE enum. 
-- Another OnIdentify section
-- More entries identifying main phases of VSS Backup (OnFreeze, OnThaw, OnPostSnapshot)
-- A final OnIdentify Section.
-- A final VSS phase report, which names makes it a useful “closing event”: OnBackupComplete.
+- The Flavor of VSS backup requested. Usually `VSS_BT_FULL` or `VSS_BT_COPY`. See the [VSS_BACKUP_TYPE](/windows/win32/api/vss/ne-vss-vss_backup_type) enum. 
+- Another `OnIdentify` section
+- More entries identifying main phases of VSS Backup (`OnFreeze`, `OnThaw`, `OnPostSnapshot`)
+- A final `OnIdentify` Section.
+- A final VSS phase report, which names makes it a useful “closing event”: `OnBackupComplete`.
 
 These entries provide details on the VSS operations that were previously difficult to establish quickly and required advanced tracing to do so. A prime example is the "Component" or "non-Component" mode of any VSS backup request. With [!INCLUDE[ssql19-md](../../includes/sssql19-md.md)] SQL Writer, they're logged for every single VSS request by default and are easily accessible.
 
 
 
 ### Failure Situation: torn database
 
-To illustrate the earlier statement that SQL Writer logging complements original EventLog architecture, let’s look at the entries associated to a well-known failure situation: a Torn Database. It can occur when a volume-based VSS backup attempts to snapshot a drive where only a subset of database files is present, as opposed to making sure all drives supporting the Databases Files are included in the snapshot set. SQL Writer will block it as per VSS conventions.
+To illustrate the earlier statement that SQL Writer logging complements original EventLog architecture, let’s look at the entries associated to a well-known failure situation: a Torn Database. It can occur when a  VSS backup attempts to create a snapshot set of volumes where only a partial set of files of a given database is included. SQL Writer will block it as per VSS conventions.
 
-This extract is the content of **SqlWriterLogger.txt** for the operation:
+This extract is the content of **`SqlWriterLogger.txt`** for the operation:
 
 ``` txt
 [01/11/2021 02:57:00, TID 5a88] Entering SQL Writer OnIdentify.
@@ -235,17 +235,17 @@ Context:
    Process ID: 22628
 ```
 
-Event Log is a better source of information on the error itself here. However, the SqlWriterLogger contents provide details on the backup request (a VSS_BT_FULL, non-component VSS backup request that failed during the OnPrepareSnapshot phase of SQL Writer). Any investigation of VSS errors involving SQL Server should therefore collect and review *both* sources.
+Event Log is a better source of information on the error itself here. However, the SqlWriterLogger contents provide details on the backup request (a `VSS_BT_FULL`, non-component VSS backup request that failed during the `OnPrepareSnapshot` phase of SQL Writer). Any investigation of VSS errors involving SQL Server should therefore collect and review *both* sources.
 
 ## Modifying SQL Writer logging parameters
 
-SQL Writer logging can be configured by editing the SqlWriterConfig.INI text file. The file itself contains a quick inline description of the available parameters, which we’ll review below.
+SQL Writer logging can be configured by editing the `SqlWriterConfig.INI` text file. The file itself contains a quick inline description of the available parameters, which we’ll review below.
 
 > [!IMPORTANT]
 > The .ini file is under a Windows-Protected folder (Program Files). As such it requires elevated administrator privileges to edit. A double-click in explorer will open Notepad without elevation: it will allow the user to read the contents, but attempts to save any change will fail.   
 Either start Notepad as administrator and then open SqlWriterConfig.INI, or use a text editor which is able to prompt for elevation as needed at ‘save file’ time.
 
-Duplicating the SqlWriterConfig.ini file comments here:
+Duplicating the `SqlWriterConfig.ini` file comments here:
 
 ``` txt
 ; EnableLogging = TRUE | FALSE(true is the default behavior)
@@ -256,10 +256,10 @@ Duplicating the SqlWriterConfig.ini file comments here:
 ```
 
 - **EnableLogging** allows the user to disable the whole new logging feature, in the unlikely case it's needed.
-- **TraceFile** would allow the user to change the path and filename of the trace file. It's not recommended to change it as the fixed location makes it easy to go straight to the right place on any SQL Server for DBAs and Logs Collection tools alike.
+- **TraceFile** would allow the user to change the path and filename of the trace file. It's not recommended to change it as the default, well-known location makes it easy to go straight to the right place on any SQL Server.
 - **Tracelevel** is the verbosity of the logging. More details further on.
-- **TraceFileSizeMb** is the max file size before rollover. The .txt file uses UTF-8 encoding and consumes 2 bytes per character. Increasing this value is valid for instance with intense VSS activity or where it is required to retain long periods of log entries, or if non-default TraceLevels are enabled for long durations. The default 1-MB value with default TraceLevel should provide ample history for most situations.
-- **ForceFlush** setting this option to TRUE would only be useful in the  rare circumstances where the SQL Writer service would crash before it got the chance to flush its last log entries; otherwise keep the default value.
+- **TraceFileSizeMb** is the max file size before rollover. The .txt file uses UTF-8 encoding and consumes 2 bytes per character. Increasing this value is valid for instance with intense VSS activity or where it is required to retain long periods of log entries, or if non-default `TraceLevel` values are enabled for long durations. The default 1-MB value with default `TraceLevel` should provide ample history for most situations.
+- **ForceFlush** setting this option to `TRUE` would only be useful in the  rare circumstances where the SQL Writer service would crash before it got the chance to flush its last log entries; otherwise keep the default value.
 
 ### Applying Changes
 
@@ -268,15 +268,15 @@ Any change to the settings requires a restart of SQL Writer service to activate.
 > [!TIP]
 >Restarting SQL Writer is extremely fast and can be done at will as SQL Writer doesn’t have any activity and doesn’t retain any stateful information in-between VSS calls. The only precaution is to avoid a restart while a VSS operation (backup, restore) is taking place.
 
-SQL Writer will report active parameters in its log file upon (re)start, as can be seen in ‘Service Start’ sample extract.
+SQL Writer will report active parameters in its log file upon (re)start, as can be seen in [Service Start](#service-start) sample extract.
 
 ## TraceLevel details
 
 The INI file lists the following level: DEFAULT | MINIMAL | VERBOSE.
 
 - **DEFAULT**: The default verbosity parameters should be adequate for most needs: refer to the [Review of typical logging entries](#review-of-typical-logging-entries) section to observe what is already generated by default. In addition to errors, successful VSS calls, along with VSS metadata, will be logged by default.
-- **MINIMAL**: This level will retain the formatting of Default mode, and its events. It will also generate output in many key places of the code. Most notably it will log all the files and database iterations that are commonplace in the SQLWriter logic. It can increase the number of entries logged for each VSS operation (including mundane OnIdentify event) by a large margin, especially on instances hosting a large number of databases: every single physical file of every single Database may be reported more than once over the course of a VSS backup. This level only helps giving a more precise idea of the logical position of SQL Writer logic at the time of a failure, or for exploration purposes. It’s not useful to keep it active beyond momentary investigations, as it will greatly reduce the history depth of the default 1-MB file size as each operation will generate at least five times as many entries. Increasing the TraceFileSizeMb value may be relevant.
-- **VERBOSE**: Currently this level reports the same events as Minimal, but prefixes each entry with source code object and methods descriptors. It makes the output wider (larger in size than Minimal) and less readable. The added information wouldn't be useful outside of interactions with Microsoft Support Services. The same comment as minimal would apply: keep this level active for long duration will greatly reduce the history depth of the default 1-MB file size as each operation will generate at least five times as many entries, and wider entries: increasing the TraceFileSizeMb value may be relevant.
+- **MINIMAL**: This level will retain the formatting of `DEFAULT` mode, and its events. It will also generate output in many key places of the code. Most notably it will log all the files and database iterations that are commonplace in the SQLWriter logic. It can increase the number of entries logged for each VSS operation (including mundane OnIdentify event) by a large margin, especially on instances hosting a large number of databases: every single physical file of every single Database may be reported more than once over the course of a VSS backup. This level only helps giving a more precise idea of the logical position of SQL Writer logic at the time of a failure. It's also convenient for exploration purposes. It’s not useful to keep it active beyond momentary investigations, as the level of details will greatly reduce the history depth of the default 1-MB file size. Increasing the `TraceFileSizeMb` value may be relevant.
+- **VERBOSE**: Currently this level reports the same events as `MINIMAL`, but prefixes each entry with source code object and methods descriptors. It makes the output wider (larger in size than Minimal) and less readable. The added information wouldn't be useful outside of interactions with Microsoft Support Services. The same comment as `MINIMAL` would apply: keep this level active for long duration will greatly reduce the history depth of the default 1-MB file size as each operation will generate at least five times as many entries, and wider entries: increasing the `TraceFileSizeMb` value may be relevant.
 
 > [!NOTE]
 > **MINIMAL** (and **VERBOSE**) level will *not* provide additional error details in case of failure, only additional *progress details* for each low level operation related to SQL Writer activities.