Notice: This website is an unofficial Microsoft Knowledge Base (hereinafter KB) archive and is intended to provide a reliable access to deleted content from Microsoft KB. All KB articles are owned by Microsoft Corporation. Read full disclaimer for more details.

How to enable Trace Logging in SQL Server 2008 R2 and 2012 Master Data Services


View products that this article applies to.

Summary

Once you have installed Master Data Services (MDS), you may find the trace logging feature useful for error diagnostics and support requests as well as monitoring of application usage and performance. This article covers the steps to turn on and configure trace logging. Specifically, this article covers tracing to a text log file. Other logging mechanisms are supported and will be covered in future posts and SQL Server Books Online

↑ Back to the top


More Information

Background: Master Data Services consists of an ASP.NET web application (Master Data Manager) and a WCF service, both hosted in IIS, plus a SQL Server 2008 R2 or 2012 database. Both Master Data Manager requests and external calls to the web services API end-point are handled by a common service layer. The service layer can log each operation request/response as well as important events and errors.

The web.config file: As an administrator with access to files on the IIS web server, you can enable logging by modifying the MDS Web.config file.

By default the Web.config file is located in one of the following web application folders:
  • SQL Server 2008 R2: program_files\Microsoft SQL Server\Master Data Services\WebApplication
  • SQL Server 2012: program_files\Microsoft SQL Server\110\Master Data Services\WebApplication


Caution: Updating Web.config will cause the MDS application domain in IIS to recycle. Existing user sessions will lose cached information and users may experience session errors or slow page loads. Perform changes at off-peak times if possible.

The file snippet below shows the diagnostics section from the originally installed file. Note that switchValue is set to “Off”. Additionally, the example lines that follow are commented out. These lines are examples for adding trace listeners of various types.
<system.diagnostics> 
<sources>
<!-- Adjust the switch value to control the types of messages that should be logged. -->
<source name="MDS" switchType="System.Diagnostics.SourceSwitch" switchValue="Off">
<listeners>
<!-- Enable and configure listeners as desired to obtain trace messages. -->
<!-- <add name="LogFileListener" type="System.Diagnostics.TextWriterTraceListener" initializeData="MdsTrace.log" traceOutputOptions="DateTime" /> -->
<!-- <add name="EtwListener" type="System.Diagnostics.Eventing.EventProviderTraceListener, System.Core, Version=3.5.0.0, Culture=neutral, PublicKeyToken=B77A5C561934E089"
initializeData="{F2A341B8-CA5F-49ad-B00C-A82D3FCF948B}"/> -->
<!-- <remove name="Default"/> -->
</listeners>
</source>
</sources>
<trace autoflush="true" />
</system.diagnostics>

Turning on log file tracing: To enable logging, change switchValue to All or another valid value as described below in Table 2. To enable the output to a log file, uncomment the LogFileListener line as shown in the file snippet below.

<system.diagnostics> 
<sources>
<!-- Adjust the switch value to control the types of messages that should be logged. -->
<source name="MDS" switchType="System.Diagnostics.SourceSwitch" switchValue="All">
<listeners>
<!-- Enable and configure listeners as desired to obtain trace messages. -->
<add name="LogFileListener" type="System.Diagnostics.TextWriterTraceListener" initializeData="MdsTrace.log" traceOutputOptions="DateTime" />
<!-- <add name="EtwListener" type="System.Diagnostics.Eventing.EventProviderTraceListener, System.Core, Version=3.5.0.0, Culture=neutral, PublicKeyToken=B77A5C561934E089" initializeData="{F2A341B8-CA5F-49ad-B00C-A82D3FCF948B}"/> -->
<!-- <remove name="Default"/> -->
</listeners> </source>
</sources>
<trace autoflush="true" />
</system.diagnostics>


File name and path: The initializeData value is the name of the log file. This may be modified to another name or to include a desired path. If the path is not specified then the file will default to the web application directory path (where web.config resides).

Important Note: The service account for the MDS application pool must have write access to the log file location.

Logging level of detail: Table 1 below describes the categories of trace events that may be logged, sorted with the most important / critical events at the top. Table 2 below lists the valid settings for the logging switchValue; this setting may be adjusted to produce the right amount of logging details to suit the situation.

Table 1 - MDS logging event types
Event TypeDescription
Criticala fatal error or application crash
Errora recoverable error
Warninga noncritical problem
Informationan informational message
Verbosea debugging trace message
Startstarting of a logical operation
Stopstopping of a logical operation


Table 2 - SwitchValue settings for logging
SettingWhat is logged:
Offnothing
Errorerrors only
Warningerrors and warnings
Informationerrors, warnings, informational messages
Verbose“Information” plus additional debugging trace information including API requests and responses in XML format
ActivityTracingstart and stop events only
All“Verbose” plus “ActivityTracing”
Log setting recommendations:
  • For normal operation, use the “Off” setting to avoid logging altogether or use the “Error” or “Warning” settings which will keep the log small while alerting administrators to problems.
  • Use the “All” setting for support / troubleshooting situations. 
  • Use “ActivityTracing” for performance measurement or usage monitoring.
  • Use “Information” only if prepared to periodically check and clean logs. The logs could get lengthy with this setting. This setting is helpful for tracking usage and usage patterns.
  • Do not use “Verbose” or “All” under normal operating conditions as the volume of data logged will negatively affect performance.
Steps for creating a log file for product support: In situations where an unexpected error occurs and further diagnostics are required, it is helpful to create a log file that traces the events leading up to the problem along with the service requests and responses.

To produce a concise and helpful log file, perform the following steps.

Caution: Updating Web.config will cause the MDS application domain in IIS to recycle.

  1. If possible, stop the MDS application pool in IIS Manager (warning: do this only if the application can be taken off line).
  2. If possible, move or delete the current log file (if one already exists).
  3. Open the web.config file with a text editor.

    Note By default the Web.config file is located in one of the following web application folders:
    • SQL Server 2008 R2:program_files\Microsoft SQL Server\Master Data Services\WebApplication
    • SQL Server 2012:program_files\Microsoft SQL Server\110\Master Data Services\WebApplication
  4. Find the system.diagnostics section
  5. Change the switchValue to All or ActivityTracing and uncomment the log file line as shown in Turning on log file tracing section of this article.
    1. Use the “All” switchValue for error diagnostics.
    2. Use the “ActivityTracing” switchValue for performance diagnostics.
    3. The MdsTrace.log file name can be prefixed with a path if desired.

  6. If the application pool was previously stopped:
    1. Then, start the MDS application pool in IISb
    2. Else, wait for the log file to appear after some time and web application activity. The web application will periodically reload configuration settings from the file (should be within minutes).

  7. Reproduce the problem and perform the same actions or requests that led to the error.
  8. If you are able to stop application pool:
    1. Then:
      1. Stop the application pool.
      2. Retrieve the log file (may need to wait for processes to finish; there could be a delay after stopping the app pool)
    2. Else, open the log file with an editor that does not lock the file (like notepad.exe) and copy the relevant tracing messages.
  9. Open the web.config file with a text editor and change the switchValue back to Off or the prior value.
  10. Start the application pool if stopped.

    Error Handling: All service operations return an array or collection of errors within the OperationResult object of a response message. When an error occurs, the error array is also serialized to XML and written to the web application log file for certain switchValue settings as described above.

Example of an API response error that has been written to the log file:
MDS Error: 0 : 
<ArrayOfError xmlns="http://schemas.microsoft.com/sqlserver/masterdataservices/2009/09" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Error>
<Code>110003</Code>
<Context>
<FullyQualifiedName>Model1</FullyQualifiedName>
<Identifier>
<Id>00000000-0000-0000-0000-000000000000</Id>
<Name>Model1</Name> <InternalId>0</InternalId>
</Identifier>
<Type>Model</Type>
</Context>
<Description>The name already exists. Type a different name.</Description>
</Error>
</ArrayOfError>
DateTime=2009-12-10T20:48:05.6949548ZError object contents


Table 3 - As shown in the example above, each error includes the following data properties.
Property Description
CodeThe unique error number identifying the type of error
DescriptionLocalized error message text
Context.FullyQualifiedNameThe fully qualified name of the object involved in the error

Some names are only unique within their context. An entity would be qualified with a Model name prefix such as ModelName : EntityName.
Context.TypeThe type of object involved in the error
Context.IdentifierThe identifier of the object involved in the error
Context.Identifier.IdThe unique GUID of the object, if specified or available
Context.Identifier.NameThe name of the object, if specified or available
Context.Identifier.InternalIdDeprecated – do not use

↑ Back to the top


Keywords: kb

↑ Back to the top

Article Info
Article ID : 2423478
Revision : 1
Created on : 1/7/2017
Published on : 4/8/2013
Exists online : False
Views : 391