Configure client diagnostic logging in Unified Service Desk

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2013, Dynamics CRM 2015, Dynamics CRM 2016

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 Microsoft Dynamics 365.

• 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.

In This Topic

Configure Unified Service Desk client diagnostic logging

Diagnostic log sources

Diagnostic logging levels

Diagnostic log listeners

Viewing the diagnostic log file

Unified Service Desk Monitoring Process

Error diagnostics reporting

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

Important

• 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: MSDN: 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:

1. 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 USD\USD.

2. 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>
   

3. In the <switches> section, specify a logging source (such as EventTopicSwitch), and then specify a logging level value (such as Error). The <switches> section controls logging levels for various sources. By default, error logging is enabled for all the switches:

   • For information about the available logging sources, see Diagnostic log sources later in this topic.

   • For information about the values you can specify for each logging source, see Diagnostic logging levels later in this topic.

4. 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>
   

   The <sharelisteners> section controls the location and type of logs that are generated for Unified Service Desk. By default, fileListener will create a file called UnifiedServiceDesk.log in c:\Users\<UserName>\AppData\Roaming\Microsoft\UnifiedServiceDesk\<Version> directory, and USDDebugListener will create events in the MSDN: Debug output tab of the Debugger hosted control.

5. If you want to change the location of the UnifiedServiceDesk.log file, change the value of the Location parameter.

6. 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.

7. 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 Microsoft.Crm.UnifiedServiceDesk source.

   <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.

Source Name	Description
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 Dynamics 365. This source will report general or detailed diagnostics information about the sign-in procedure.
Microsoft.Xrm.Tooling.Connector.CrmServiceClient	Log source for all Dynamics 365 data-level interactions. This source will report all interactions with Dynamics 365, exceptions and timings.
Microsoft.Xrm.Tooling.WebResourceUtility	Log source for requests for Web Resource data via the Dynamics 365 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 in Unified Service Desk

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.

Log Level	Description
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:

• DefaultTraceListener

• EventLogTraceListener

• TextWriterTraceListener

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 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 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.

When an error occurs in a hosted control, the information logged in the log files provide detailed information about the exception such as the originating hosted control that caused the exception along with the exception details. Notice that the entire JavaScript code that caused the exception isn't logged. Only the faulty code along with exception description are logged.

Note

The error handling and logging described here was first introduced in Unified Service Desk 2.2.1.

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.

Note

The error diagnostics reporting features described here were first introduced in Unified Service Desk 2.2.2.

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.

Diagnostics file	Description
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. More information:Configure client diagnostic logging in Unified Service Desk
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 Microsoft Visual Studio or other Windows dump file viewing tool.

Configure error diagnostics reporting

1. In the web application, go to Settings > Unified Service Desk > Options.

2. Click New, and then select DiagnosticsConfiguration.

3. Enter one or more values that are listed in the following table separated by a semicolon (;). More information: Error diagnostics reporting option values

   For example, this configuration changes the log files directory, reduces the maximum diagnostics log folder size to 2 GB, and changes the shortcut key combination to invoke an on-demand crash dump to CRTL+ALT+D.

   

4. Click Save & Close.

Error diagnostics reporting option values

Error diagnostics reporting settings are configured by using the DiagnosticsConfiguration global option. The available DiagnosticsConfiguration values are described here.

Value Name	Value type	Description
EnableExitMonitoring	true / false	The default is true and both diagnostics logs and exit logs are collected in the event of an exception. If set to false, both diagnostic logs and exit logs will not be collected during an exception of the Unified Service Desk client.
EnableCrashMonitoring	true / false	The default is true and dump files are collected during a fatal exception of the Unified Service Desk client. If set to false, dump files will not be collected during a Unified Service Desk client exception. If EnableCrashMonitoring is set to false and EnableExitMonitoring is set to true, both diagnostics logs and exit logs are collected, but dump files aren’t.
LogsDirectory	string	Specifies the full path to the folder where diagnostics files for exceptions are kept. If the path is invalid or inaccessible, Unified Service Desk will use the default folder. By default, the folder is %APPDATA%\Roaming\Microsoft\Microsoft Dynamics® 365 Unified Service Desk\<version>\Diagnostics\.
MaxDiagnosticLogsSize	integer	Specifies the maximum size of the folder in megabytes where diagnostics files are kept. The default size is 5 GB (5000 MB). When MaxDiagnosticLogsSize is exceeded, the oldest log folders will be deleted until MaxDiagnosticLogsSize is no longer exceeded. Notice that, the most recent log folder is not deleted even if it exceeds MaxDiagnosticLogsSize.
ManualDumpShortcut	string	Specifies the shortcut key used to invoke the manual creation of a dump file. The default key combination is CTRL+ALT+a. To change the default, use the form key1+key2+key3.

See Also

Configure auditing and diagnostics in Unified Service Desk
Troubleshoot Unified Service Desk
MSDN: Debug issues in Unified Service Desk

Unified Service Desk 2.0

© 2016 Microsoft. All rights reserved. Copyright