Client diagnostic logging overview
There are two ways you can configure Unified Service Desk client diagnostic logging:
By using an Audit & Diagnostics Settings record that is created and managed in the Unified Service Desk area of Dynamics 365 for Customer Engagement apps.
By manually making changes to the UnifiedServiceDesk.exe.config file. This file must then be distributed to every desktop where you want Unified Service Desk client diagnostic logging.
Additionally, you can configure diagnostic logging specifically for exceptions that may occur in the Unified Service Desk client.
Configure Unified Service Desk client diagnostic logging
This section describes how to manually configure diagnostic logging in Unified Service Desk. Rather than use the procedure described here, we recommend you use the Audit & Diagnostics Settings feature that provides centralized administration of diagnostics and the ability to connect a custom listener. More information: Configure auditing and diagnostics in Unified Service Desk
- The manually-configured diagnostics (as described here), will no longer work after you enable an Audit & Diagnostics Settings record that is configured for diagnostics.
- Unified Service Desk also provides an API that lets you configure rich diagnostic logging for custom hosted controls. More information: Configure enhanced diagnostic logging for custom hosted controls
This topic describes how to change client logging characteristics.
You can enable logging with the UnifiedServiceDesk.exe.config file, which is available in the Unified Service Desk client installation directory on your computer. To configure the type of logging and location of the Unified Service Desk log file:
Open the UnifiedServiceDesk.exe.config file for editing. If you installed the Unified Service Desk client at the default location, this file will typically be available at C:\Program Files\Microsoft Dynamics 365 for Customer Engagement USD\USD.
Go to the
<switches>section in the file:
<switches> <!-- Possible values for switches: Off, Error, Warning, Information, Verbose Verbose: includes Error, Warning, Info, Trace levels Information: includes Error, Warning, Info levels Warning: includes Error, Warning levels Error: includes Error level --> <add name="EventTopicSwitch" value="Error"/> <add name="Microsoft.Uii.Common.Logging" value="Error"/> <add name="Microsoft.Xrm.Tooling.CrmConnectControl" value="Error"/> <add name="Microsoft.Xrm.Tooling.Connector.CrmServiceClient" value="Error"/> <add name="Microsoft.Xrm.Tooling.WebResourceUtility" value="Error"/> <add name="Microsoft.Crm.UnifiedServiceDesk" value="Error"/> <add name="Microsoft.Crm.UnifiedServiceDesk.Dynamics" value="Error"/> <add name="Microsoft.Crm.UnifiedServiceDesk.CommonUtility.UserProfileManager" value="Error"/> <add name="UnifiedServiceDesk.KPIControl" value="Error"/> </switches>
<switches>section, specify a logging source (such as
EventTopicSwitch), and then specify a logging level value (such as
<switches>section controls logging levels for various sources. By default, error logging is enabled for all the switches:
To configure the location, maximum file size, and rollover behavior of the log files, go to the
<shareListeners>section in the file.
<sharedListeners> <add name="fileListener" type="Microsoft.Xrm.Tooling.Connector.DynamicsFileLogTraceListener, Microsoft.Xrm.Tooling.Connector" BaseFileName="UnifiedServiceDesk" Location="LocalUserApplicationDirectory" MaxFileSize ="52428800" MaxFileCount="10"/> <add name="USDDebugListener" type="Microsoft.Crm.UnifiedServiceDesk.Dynamics.UsdTraceListener, Microsoft.Crm.UnifiedServiceDesk.Dynamics" /> <add name="ADALListener" type="Microsoft.Xrm.Tooling.Connector.DynamicsFileLogTraceListener, Microsoft.Xrm.Tooling.Connector" BaseFileName="ADAL" Location="LocalUserApplicationDirectory" MaxFileSize ="52428800" MaxFileCount="10"/> </sharedListeners>
<sharelisteners>section controls the location and type of logs that are generated for Unified Service Desk. By default,
fileListenerwill create a file called UnifiedServiceDesk.log in c:\Users\<UserName>\AppData\Roaming\Microsoft\UnifiedServiceDesk\<Version> directory, and
USDDebugListenerwill create events in the Debug output tab of the Debugger hosted control.
If you want to change the location of the UnifiedServiceDesk.log file, change the value of the
By default, a new Unified Service Desk log is created after the file size of the current log file exceeds 52.42 MB. By default, up to 10 log files are maintained at one time before the oldest log file is deleted.
To change the maximum Unified Service Desk log file size, change the value, in bytes, of the MaxFileSize parameter.
To change the number of logs maintained before the oldest log is deleted, change the value of the MaxFileCount parameter. If zero (0) is used rollover logging will be disabled and all Unified Service Desk client logs created will be saved.
By default, file and debugger logging is enabled for all sources. If you want to add or remove a listener from a diagnostic source, locate the required source in the
<sources>section, and then modify the
<listeners>section of the source to include the listener you want.
For example, to add event logging for Unified Service Desk, add the event logging listener to the
<source name="Microsoft.Crm.UnifiedServiceDesk" switchName="Microsoft.Crm.UnifiedServiceDesk" switchType="System.Diagnostics.SourceSwitch"> <listeners> <add name="fileListener"/> <add name="USDDebugListener" /> <add name="eventLogListener" type="System.Diagnostics.EventLogTraceListener" initializeData="USD"/> </listeners> </source>
This will now report events to the Windows event log with the tag “USD”, in addition to the file and Debugger. For more information about diagnostic listeners, see Diagnostic Log Listeners later in this topic.
Diagnostic log sources
Common troubleshooting log sources are listed in the following table.
|EventTopicSwitch||Detailed User Interface Integration (UII) logging source for monitoring messaging traffic inside UII.|
|Microsoft.Uii.Common.Logging||General UII Log source for messages reported by UII.|
|Microsoft.Xrm.Tooling.CrmConnectControl||Log source for the sign-in process to Customer Engagement. This source will report general or detailed diagnostics information about the sign-in procedure.|
|Microsoft.Xrm.Tooling.Connector.CrmServiceClient||Log source for all Customer Engagement data-level interactions. This source will report all interactions with Customer Engagement, exceptions and timings.|
|Microsoft.Xrm.Tooling.WebResourceUtility||Log source for requests for Web Resource data via the Customer Engagement interface link.|
|Microsoft.Crm.UnifiedServiceDesk||Log source for core Unified Service Desk functionality. This log source will report actions and events that are core to Unified Service Desk.|
|Microsoft.Crm.UnifiedServiceDesk.Dynamics||Log source for Unified Service Desk boot strap and loading processor. This source will report actions and events that are part of initializing and starting the UII and Unified Service Desk.|
|Microsoft.Crm.UnifiedServiceDesk.CommonUtility.UserProfileManager||Log source for actions that interact with the UserProfile system; this is part of the caching system. More information: Configure client caching for your agent application|
You can toggle each of these log sources independently to support troubleshooting and isolation of issues or information inside Unified Service Desk.
Diagnostic logging levels
There are several distinct logging levels available for use. However, as you increase the level of logging, more data is generated and stored in the log files.
|Off||Disables all events from this source.|
|Error||Reports only error events.|
|Warning||Reports errors and warning events.|
|Information||Reports errors, warnings, and information events.|
|Verbose||Reports errors, warnings, information, and verbose events.|
|ActivityTracing||Reports errors, warnings, information, and verbose events, and activity tracing (method names). Note: ActivityTracing is available only on some of the sources.|
|All||Reports all events raised by the system.|
Diagnostic log listeners
Diagnostics log listeners are used to target the diagnostic log output to files, the event log, or other sources. By default, all diagnostic sources are wired to both the default (Debugger) and file (text) listeners. You can configure additional log listeners for diagnostic logging for Unified Service Desk. For more information about the .NET default listeners, see:
You can also create custom listeners to send diagnostic logs to a location you pick. Custom listeners are created by deriving a class from the MSDN:TraceListener abstract class. You can find a walkthrough of the process on CodeGuru.com.
Viewing the diagnostic log file
By default, diagnostics logging is enabled for the Unified Service Desk client application. A log file, UnifiedServiceDesk-<date>.log, is available at c:\Users\<UserName>\AppData\Roaming\Microsoft\Microsoft Dynamics 365 for Customer Engagement Unified Service Desk\<Version> on the client computer to record operational errors in the client application. The log file is created the first time you encounter any errors in the client application.
Here is a sample exception detail that is logged.
Microsoft.Crm.UnifiedServiceDesk.Dynamics Error 2 12/27/2016 11:54:15 AM Origin:AppdomianUnhandledException, IsFatal:True Source: DemoControl Target: Void throwExceptionMethod() Exception: Exception in custom control StackTrace: at DemoControl.USDControl.throwExceptionMethod() at System.Threading.ExecutionContext.RunInternal(ExecutionContext executionContext, ContextCallback callback, Object state, Boolean preserveSyncCtx) at System.Threading.ExecutionContext.Run(ExecutionContext executionContext, ContextCallback callback, Object state, Boolean preserveSyncCtx) at System.Threading.ExecutionContext.Run(ExecutionContext executionContext, ContextCallback callback, Object state) at System.Threading.ThreadHelper.ThreadStart()
Unified Service Desk Monitoring Process
The Unified Service Desk Monitoring Process (usdmp.exe) is a service that continuously monitors the health of Unified Service Desk, and terminates, by default after 5 seconds, any browser process instances that are unresponsive and causing Unified Service Desk to become unresponsive. If a browser process instance isn’t responding, but Unified Service Desk is responsive, the browser process instance won’t be terminated. For more information about how to change the duration of the ProcessTerminationThreshold global option for browser process termination, see Manage Options for Unified Service Desk.
Error diagnostics reporting
Having detailed and comprehensive logging and reporting that occurs during a component, application, or system fault can help identify when and how the fault occurred. In addition to standard diagnostics logging, error diagnostics reporting records system and application state information in the event of an exception in the Unified Service Desk client. More information about exceptions can be found in How Unified Service Desk handles application and system errors.
Folders and files created during an exception
In the event of an exception, error diagnostics reporting creates a folder on the local computer named DiagnosticsLogs_date and time, where date and time is in the form year-month-date_time, such as DiagnosticLogs_20170322_173643. Within the DiagnosticsLogs folder the following folder and files are created.
|UnifiedServiceDesk_dateandtime.log||Standard diagnostics log that is created and appended when Unified Service Desk client is running. The file contains logging information for the Unified Service Desk client (UnifiedServiceDesk.exe). The current files are moved into the DiagnosticsLogs folder in the event of an exception.|
|UnifiedServiceDeskMonitoring_date.log||Standard diagnostics log that is created and appended when Unified Service Desk client is running. Contains logging information for the Unified Service Desk monitoring process (usdmp.exe), which is a process that monitors the health of the Unified Service Desk client. The current files are moved into the DiagnosticsLogs folder in the event of an exception. More information: Unified Service Desk Monitoring Process|
|Eventlogs (folder)||Folder created in the event of a fatal or non-fatal exception. Contains Windows system and application event logs and error reporting text files.|
|ExitReport.txt||Exit log created in the event of a fatal or non-fatal exception. Contains process state information such as machine name, Unified Service Desk version, process id, exit code, and time of exit.|
|MachineHealthReport.txt||Exit log created in the event of a fatal or non-fatal exception. Contains system state information such as computer processor, operating system, monitor details, language, and browser version.|
|ProcessReport.csv||Exit log created in the event of a fatal or non-fatal exception. Provides a comprehensive list of all processes that were running on the system at the time of the exception.|
|RegistryLog.txt||Exit log created in the event of a fatal or non-fatal exception. Includes a text-based copy of the Windows Registry subkeys for Internet Explorer.|
|UnifiedServiceDesk_processId_CrashDump_dateandtime.dmp||Created only in the event of an unhandled fatal exception or when invoked manually by using the ManualDumpShortcut global option keyboard combination. Provides a full memory dump file for UnifiedServiceDesk.exe. Notice that, to view the dump file, you need Visual Studio or other Windows dump file viewing tool.|
Configure error diagnostics reporting
In the web application, go to Settings > Unified Service Desk > Auditing and Diagnostics.
Click New, and then select DiagnosticsConfiguration.
Select or enter the values that you want, such as tracking, exit monitoring, and the diagnostics logs folder location. More information: Diagnostics
Click Save & Close.