diff --git a/windows/client-management/mdm/diagnosticlog-csp.md b/windows/client-management/mdm/diagnosticlog-csp.md index 98c675ebf6..bb3dd36d2a 100644 --- a/windows/client-management/mdm/diagnosticlog-csp.md +++ b/windows/client-management/mdm/diagnosticlog-csp.md @@ -9,13 +9,12 @@ ms.topic: article ms.prod: w10 ms.technology: windows author: manikadhiman -ms.date: 06/26/2017 +ms.date: 06/27/2019 --- # DiagnosticLog CSP - -The DiagnosticLog configuration service provider (CSP) is used for generating and collecting diagnostic information from the device: Event Tracing for Windows (ETW) log files and current MDM configured state of the device. +The DiagnosticLog CSP is used for generating and collecting diagnostic information from the device: Event Tracing for Windows (ETW) log files and current MDM configured state of the device. DiagnosticLog CSP supports the following type of event tracing: @@ -49,11 +48,10 @@ For each registered provider in this collector, the user can: The changes on **State**, **Keywords** and **TraceLevel** takes effect immediately while trace session is in progress. -> **Note**  Microsoft-WindowsPhone-Enterprise-Diagnostics-Provider (GUID - 3da494e4-0fe2-415C-b895-fb5265c5c83b) has the required debug resource files built into Windows OS, which will allow the logs files to be decoded on the remote machine. Any other logs may not have the debug resources required to decode. +> [!Note] +> Microsoft-WindowsPhone-Enterprise-Diagnostics-Provider (GUID - 3da494e4-0fe2-415C-b895-fb5265c5c83b) has the required debug resource files built into Windows OS, which will allow the logs files to be decoded on the remote machine. Any other logs may not have the debug resources required to decode. - - -### Channel-based tracing + ### Channel-based tracing The type of event tracing exports event data from a specific channel. This is only supported on the desktop. @@ -74,35 +72,29 @@ Here are the links to the DDFs: - [DiagnosticLog CSP version 1.2](diagnosticlog-ddf.md#version-1-2) - [DiagnosticLog CSP version 1.3](diagnosticlog-ddf.md#version-1-3) -The following diagram shows the DiagnosticLog configuration service provider in tree format. +The following diagram shows the DiagnosticLog CSP in tree format. ![diagnosticlog csp diagram](images/provisioning-csp-diagnosticlog.png) **./Vendor/MSFT/DiagnosticLog** -The root node for the DiagnosticLog configuration service provider. +The root node for the DiagnosticLog CSP. -The following steps describe the process for gathering diagnostics using this CSP. +To gather diagnostics using this CSP: 1. Specify a *CollectorName* for the container of the target ETW providers. 2. (Optional) Set logging and log file parameters using the following options: - - **TraceLogFileMode** - - **LogFileSizeLimitMB** - - Each of these are described later in this topic. + - TraceLogFileMode + - LogFileSizeLimitMB 3. Indicate one or more target ETW providers by supplying its *ProviderGUID* to the Add operation of EtwLog/Collectors/*CollectorName*/Providers/*ProviderGUID*. 4. (Optional) Set logging and log file parameters using the following options: - - - **TraceLevel** - - **Keywords** - - Each of these are described later in this topic. - -5. Start logging using **TraceControl** EXECUTE command “START” + - TraceLevel + - Keywords +5. Start logging using **TraceControl** EXECUTE command “START”. 6. Perform actions on the target device that will generate activity in the log files. -7. Stop logging using **TraceControl** EXECUTE command “STOP” -8. Collect the log file located in the `%temp%` folder using the method described in [Reading a log file](#reading-a-log-file) +7. Stop logging using **TraceControl** EXECUTE command “STOP”. +8. Collect the log file located in the `%temp%` folder using the method described in [Reading a log file](#reading-a-log-file). **EtwLog** Node to contain the Error Tracing for Windows log. @@ -174,8 +166,6 @@ The following table represents the possible values: | 0 | Stopped | | 1 | Started | - - **EtwLog/Collectors/*CollectorName*/TraceLogFileMode** Specifies the log file logging mode. @@ -185,30 +175,10 @@ Supported operations are Get and Replace. The following table lists the possible values: - ---- - - - - - - - - - - - - - - - - -
ValueDescription

EVENT_TRACE_FILE_MODE_SEQUENTIAL (0x00000001)

Writes events to a log file sequentially; stops when the file reaches its maximum size.

EVENT_TRACE_FILE_MODE_CIRCULAR (0x00000002)

Writes events to a log file. After the file reaches the maximum size, the oldest events are replaced with incoming events.

- - +| Value | Description | +|-------|--------------------| +| EVENT_TRACE_FILE_MODE_SEQUENTIAL (0x00000001) | Writes events to a log file sequentially; stops when the file reaches its maximum size. | +| EVENT_TRACE_FILE_MODE_CIRCULAR (0x00000002) | Writes events to a log file. After the file reaches the maximum size, the oldest events are replaced with incoming events. | **EtwLog/Collectors/*CollectorName*/TraceControl** Specifies the logging and report action state. @@ -222,8 +192,6 @@ The following table lists the possible values: | START | Start log tracing. | | STOP | Stop log tracing | - - The supported operation is Execute. After you have added a logging task, you can start a trace by running an Execute command on this node with the value START. @@ -295,8 +263,6 @@ Dynamic nodes to represent active provider configuration per provider GUID. > **Note**  Microsoft-WindowsPhone-Enterprise-Diagnostics-Provider (GUID - 3da494e4-0fe2-415C-b895-fb5265c5c83b) has the required debug resource files built into Windows OS, which will allow the logs files to be decoded on the remote machine. Any other logs may not have the debug resources required to decode. - - Supported operations are Add, Delete, and Get. Add a provider @@ -347,44 +313,15 @@ The data type is an integer. Supported operations are Get and Replace. -The following table lists the possible values. +The following table lists the possible values: - ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueDescription

1 – TRACE_LEVEL_CRITICAL

Abnormal exit or termination events

2 – TRACE_LEVEL_ERROR

Severe error events

3 – TRACE_LEVEL_WARNING

Warning events such as allocation failures

4 – TRACE_LEVEL_INFORMATION

Non-error events, such as entry or exit events

5 – TRACE_LEVEL_VERBOSE

Detailed information

- - +| Value | Description | +|-------|--------------------| +| 1 – TRACE_LEVEL_CRITICAL | Abnormal exit or termination events | +| 2 – TRACE_LEVEL_ERROR | Severe error events | +| 3 – TRACE_LEVEL_WARNING | Warning events such as allocation failures | +| 4 – TRACE_LEVEL_INFORMATION | Non-error events, such as entry or exit events | +| 5 – TRACE_LEVEL_VERBOSE | Detailed information | Set provider **TraceLevel** @@ -412,7 +349,7 @@ Set provider **TraceLevel** **EtwLog/Collectors/*CollectorName*/Providers/*ProviderGUID*/Keywords** Specifies the provider keywords to be used as MatchAnyKeyword for this provider. -the data type is a string. +The data type is a string. Supported operations are Get and Replace. @@ -420,7 +357,7 @@ Default value is 0 meaning no keyword. Get provider **Keywords** -``` syntax +``` xml @@ -440,7 +377,7 @@ Get provider **Keywords** Set provider **Keywords** -``` syntax +``` xml @@ -470,32 +407,11 @@ The data type is a boolean. Supported operations are Get and Replace. This change will be effective during active trace session. -The following table lists the possible values. Default value is TRUE. - - ---- - - - - - - - - - - - - - - - - -
ValueDescription

TRUE

Provider is enabled in the trace session.

FALSE

Provider is disables in the trace session.

- - +The following table lists the possible values: +| Value | Description | +|-------|--------------------| +| TRUE | Provider is enabled in the trace session. This is the default. | +| FALSE | Provider is disabled in the trace session. | Set provider **State** @@ -630,32 +546,12 @@ The data type is a boolean. Supported operations are Get and Replace. -The following table lists the possible values. +The following table lists the possible values: - ---- - - - - - - - - - - - - - - - - -
ValueDescription

TRUE

Channel is enabled.

FALSE

Channel is disabled.

- - +| Value | Description | +|-------|--------------------| +| TRUE | Channel is enabled. | +| FALSE | Channel is disabled. | Get channel **State** @@ -897,26 +793,526 @@ Node to transfer the selected log file block to the DM server. **FileDownload/DMChannel/*FileContext*/DataBlocks/***BlockNumber* The data type is Base64. -The only supported operation is Get. +The supported operation is Get. + +**Policy** +Added in Windows 10, version 1903. Root node to control settings for channels in Event Log. + +The supported operation is Get. + +**Policy/Channels** +Added in Windows 10, version 1903. Node that contains Event Log channel settings. + +The supported operation is Get. + +**Policy/Channels/_ChannelName_** +Added in Windows 10, version 1903. Dynamic node to represent a registered channel. The node name must be a valid Windows event log channel name, such as ``Microsoft-Client-Licensing-Platform%2FAdmin``. When specifying the name in the LocURI, it must be URL encoded, otherwise it may unexpectedly translate into a different URI. + +Supported operations are Add, Delete, and Get. + +Add **Channel** +``` xml + + ​ + ​ + 2​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName​ + ​ + ​ + ​ + node​ + ​ + ​ + ​ + ​ + ​ + ​ + ​ + +``` +Delete **Channel** +``` xml + + ​ + ​ + 3​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName​ + ​ + ​ + ​ + ​ + ​ + ​ + +``` +Get **Channel** +``` xml + + ​ + ​ + 4​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName​ + ​ + ​ + ​ + ​ + ​ + ​ + +``` +**Policy/Channels/_ChannelName_/MaximumFileSize** +Added in Windows 10, version 1903. This policy setting specifies the maximum size of the log file in megabytes. + +If you enable this policy setting, you can configure the maximum log file size to be between 1 megabyte and 2 terabytes in megabyte increments. + +If you disable or do not configure this policy setting, the maximum size of the log file will be set to the locally configured value. This value can be changed by the local administrator using the Log Properties dialog, and it defaults to 1 megabyte. + +Supported operations are Add, Delete, Get, and Replace. + +The data type is integer. + +Add **MaximumFileSize** +``` xml + + ​ + ​ + 6​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName/MaximumFileSize​ + ​ + ​ + ​ + int​ + text/plain​ + ​ + 3​ + ​ + ​ + ​ + ​ + +``` + +Delete **MaximumFileSize** +``` xml + + ​ + ​ + 7​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName/MaximumFileSize​ + ​ + ​ + ​ + ​ + ​ + ​ + +``` +Get **MaximumFileSize** +``` xml + + ​ + ​ + 5​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName/MaximumFileSize​ + ​ + ​ + ​ + ​ + ​ + ​ + +``` + +Replace **MaximumFileSize** +``` xml + + ​ + ​ + 8​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName/MaximumFileSize​ + ​ + ​ + ​ + int​ + text/plain​ + ​ + 5​ + ​ + ​ + ​ + ​ + +``` + +**Policy/Channels/_ChannelName_/SDDL** +Added in Windows 10, version 1903. This policy setting represents SDDL string controlling access to the channel. + +Supported operations are Add, Delete, Get, and Replace. + +The data type is string. + +Default string is as follows: + +https://docs.microsoft.com/en-us/windows/desktop/WES/eventmanifestschema-channeltype-complextype. + +Add **SDDL** +``` xml + + ​ + ​ + 10​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName/SDDL​ + ​ + ​ + ​ + chr​ + text/plain​ + ​ + YourSDDL​ + ​ + ​ + ​ + ​ + +``` + +Delete **SDDL** +``` xml + + + ​ + ​ + 11​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName/SDDL​ + ​ + ​ + ​ + ​ + ​ + ​ + +``` + +Get **SDDL** +``` xml + + ​ + ​ + 9​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName/SDDL​ + ​ + ​ + ​ + ​ + ​ + ​ + +``` + +Replace **SDDL** +``` xml + + ​ + ​ + 12​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName/SDDL​ + ​ + ​ + ​ + chr​ + text/plain​ + ​ + YourNewSDDL​ + ​ + ​ + ​ + ​ + +``` + +**Policy/Channels/_ChannelName_/ActionWhenFull** +Added in Windows 10, version 1903. This policy setting controls Event Log behavior when the log file reaches its maximum size. + +Supported operations are Add, Delete, Get, and Replace. + +The data type is string. + +The following are the possible values: +- Truncate — When the log file reaches its maximum file size, new events are not written to the log and are lost. +- Overwrite — When the log file reaches its maximum file size, new events overwrite old events. +- Archive — When the log file reaches its maximum size, the log file is saved to the location specified by the "Archive Location" policy setting. If archive location value is not set, the new file is saved in the same directory as current log file. + +If you disable or do not configure this policy setting, the locally configured value will be used as default. Every channel that is installed, whether inbox or by ISVs, is responsible for defining its own local configuration, and that configuration can be changed by any administrator. Values set via this policy override but do not replace local configuration. + + +Add **ActionWhenFull** +``` xml + + ​ + ​ + 14​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName/ActionWhenFull​ + ​ + ​ + ​ + chr​ + text/plain​ + ​ + Archive​ + ​ + ​ + ​ + ​ + +``` + +Delete **ActionWhenFull** +``` xml + + ​ + ​ + 15​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName/ActionWhenFull​ + ​ + ​ + ​ + ​ + ​ + ​ + +``` + +Get **ActionWhenFull** +``` xml + + ​ + ​ + 13​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName/ActionWhenFull​ + ​ + ​ + ​ + ​ + ​ + ​ + +``` + +Replace **ActionWhenFull** +``` xml + + ​ + ​ + 16​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName/ActionWhenFull​ + ​ + ​ + ​ + chr​ + text/plain​ + ​ + Truncate​ + ​ + ​ + ​ + ​ + +``` + +**Policy/Channels/_ChannelName_/Enabled** +Added in Windows 10, version 1903. This policy setting specifies whether the channel should be enabled or disabled. + +Supported operations are Add, Delete, Get, and Replace. + +The data type is boolean. + +The following are the possible values: +- TRUE — Enables the channel. +- FALSE — Disables the channel. + +If you disable or do not configure this policy setting, the locally configured value is used as default. + +Get **Enabled** +``` xml + + ​ + ​ + 17​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName/Enabled​ + ​ + ​ + ​ + ​ + ​ + ​ + +``` + +Add **Enabled** +``` xml + + ​ + ​ + 18​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName/Enabled​ + ​ + ​ + ​ + bool​ + text/plain​ + ​ + TRUE​ + ​ + ​ + ​ + ​ + +``` + +Delete **Enabled** +``` xml + + ​ + ​ + 19​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName/Enabled​ + ​ + ​ + ​ + ​ + ​ + ​ + +``` + +Replace **Enabled** +``` xml + + ​ + ​ + 20​ + ​ + ​ + ​ + ./Vendor/MSFT/DiagnosticLog/Policy/Channels/ChannelName/Enabled​ + ​ + ​ + ​ + bool​ + text/plain​ + ​ + FALSE​ + ​ + ​ + ​ + ​ + +``` + + ## Reading a log file - - -1. Enumerate log file under **./Vendor/MSFT/DiagnosticLog/FileDownload/DMChannel** -2. Select a log file in the Enumeration result -3. Set **BlockSizeKB** per DM server payload limitation -4. Get **BlockCount** to determine total read request -5. Set **BlockIndexToRead** to initialize read start point -6. Get **BlockData** for upload log block -7. Increase **BlockIndexToRead** -8. Repeat step 5 to 7 until **BlockIndexToRead == (BlockIndexToRead – 1)** - - - - - - - - - - +To read a log file: +1. Enumerate log file under **./Vendor/MSFT/DiagnosticLog/FileDownload/DMChannel**. +2. Select a log file in the Enumeration result. +3. Set **BlockSizeKB** per DM server payload limitation. +4. Get **BlockCount** to determine total read request. +5. Set **BlockIndexToRead** to initialize read start point. +6. Get **BlockData** for upload log block. +7. Increase **BlockIndexToRead**. +8. Repeat step 5 to 7 until **BlockIndexToRead == (BlockIndexToRead – 1)**. \ No newline at end of file diff --git a/windows/client-management/mdm/images/provisioning-csp-diagnosticlog.png b/windows/client-management/mdm/images/provisioning-csp-diagnosticlog.png index 44449d7e6f..a703fb2ca7 100644 Binary files a/windows/client-management/mdm/images/provisioning-csp-diagnosticlog.png and b/windows/client-management/mdm/images/provisioning-csp-diagnosticlog.png differ