Share via

Configure client diagnostic logging in Unified Service Desk

  • Article

 

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:

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.

    Exception diagnostics options

  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