Training
Module
Capture Web Application Logs with App Service Diagnostics Logging - Training
Learn about how to capture trace output from your Azure web apps. View a live log stream and download logs files for offline analysis.
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Applies to: SQL Server - Windows only Azure SQL Managed Instance
Once you have installed Master Data Services (MDS), you may find the trace logging feature useful for error diagnostics, support requests, and 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. This article also discusses the procedure to create a log file that can help troubleshoot failures that may occur when creating an MDS database.
Master Data Services consists of an ASP.NET web application (Master Data Manager) and a WCF service; both are hosted in IIS and a SQL Server database. 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, important events, and errors.
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 in one of the following web application folders:
SQL Server 2008 R2: program_files\Microsoft SQL Server\Master Data Services\WebApplication
SQL Server 2012 and later versions: program_files\Microsoft SQL Server\<nnn>\Master Data Services\WebApplication
The numbers nnn in the path correspond to the version of SQL Server being installed. The following table identifies versions for the paths:
Version | nnn |
---|---|
SQL Server 2019 | 150 |
SQL Server 2017 | 140 |
SQL Server 2016 | 130 |
SQL Server 2014 | 120 |
SQL Server 2012 | 110 |
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 Web.config file contains a tracing section, as shown below. This section is introduced in SQL Server 2016 (13.x) Master Data Services.
<sources>
<!-- Adjust the switch value to control the types of messages that should be logged.
https://msdn.microsoft.com/library/system.diagnostics.sourcelevels
Use a switchValue of Verbose to generate a full log. Please be aware that
the trace file can get quite large very quickly. -->
<source name="MDS" switchType="System.Diagnostics.SourceSwitch" switchValue="Warning, ActivityTracing">
<listeners>
<!-- Set a directory path where the service account you chose while setting up Master Data Services has read and write privileges.
Default path is Logs in WebApplication folder, for example C:\Program Files\Microsoft SQL Server\130\Master Data Services\WebApplication
New log file will be created every day or every 10 mb.
When directory size hits the 200 mb limitation, the oldest file will be deleted. -->
<add name="FileTraceListener"
type="Microsoft.MasterDataServices.Core.Logging.FileTraceListener, Microsoft.MasterDataServices.Core"
initializeData="DirectoryPath = Logs; FileSizeInMb = 10; MaxDirectorySizeInMb = 200"/>
<remove name="Default"/>
</listeners>
</source>
</sources>
The following is the default tracing behavior:
Tracing is enabled for Warning
and ActivityTracing
messages.
For more information, see SourceLevels Enumeration.
The logs are saved in the Logs folder under the WebApplication folder. The default location is C:\Program Files\Microsoft SQL Server\nnn\Master Data Services\WebApplication\Logs.
The file is created for each day or every 10 MB.
When the size of the directory reaches 200 MB, the oldest log is deleted.
The log format is CSV. The following table describes the log format:
Element | Description |
---|---|
Time | When the trace entry occurs |
CorrelationID | One correlation ID is assigned for each request. All the traces triggered by this request will share the same correlation ID. When an error occurs in the UI, the correlation ID appears in the error message |
Operation | Request operation name. If the request is a web UI request, the operation name is the url. If the request is an API request, the operation name is the service name |
Level | Level of this trace entry |
Message | Message body of the trace |
The following file snippet shows the diagnostics section from the originally installed Web.config file.
Note
The switchValue
is set to Off
. Additionally, the example lines 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>
To enable logging, change switchValue
to All
or another valid value as described below in Table 1. To enable the output to a log file, uncomment the LogFileListener
line as shown in the following file snippet:
<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>
Setting | What is logged |
---|---|
Off | nothing |
Error | errors only |
Warning | errors and warnings |
Information | errors, warnings, informational messages |
Verbose | "Information" and other debugging trace information including API requests and responses in XML format |
ActivityTracing | start and stop events only |
All | "Verbose" and "ActivityTracing" |
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 isn't specified, the file will default to the web application directory path (where Web.config resides).
Important
The service account for the MDS application pool must have write access to the log file location.
Table 2 below describes the categories of trace events that may be logged or sorted with the most important/critical events at the top. Table 1 above 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.
Event Type | Description |
---|---|
Critical | a fatal error or application crash |
Error | a recoverable error |
Warning | a noncritical problem |
Information | an informational message |
Verbose | a debugging trace message |
Start | starting of a logical operation |
Stop | stopping of a logical operation |
Off
setting to avoid logging altogether or use the Error
or Warning
settings that will keep the log small while alerting administrators to problems.All
setting for support/troubleshooting situations.ActivityTracing
for performance measurement or usage monitoring.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.Verbose
or All
under normal operating conditions, as the volume of data logged will negatively affect performance.In situations where an unexpected error occurs and further diagnostics are required, it's 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, follow these steps:
Caution
Updating Web.config will cause the MDS application domain in IIS to recycle.
If possible, stop the MDS application pool in IIS Manager.
Warning
Do this only if the application can be taken off line.
If possible, move or delete the current log file (if one already exists).
Open the Web.config file by using a text editor.
Note
By default, the Web.config file is in one of the following web application folders:
Find the system.diagnostics
section.
Change the switchValue
to All
or ActivityTracing
and uncomment the log file line as shown in the Turning on log file tracing section of this article.
switchValue="All"
for error diagnostics.switchValue="ActivityTracing"
for performance diagnostics.If the application pool was previously stopped, start the MDS application pool in IIS. Or 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).
Reproduce the problem and perform the same actions or requests that led to the error.
If you're able to stop the application pool:
Or else, open the log file by using an editor that doesn't lock the file (like notepad.exe) and copy the relevant tracing messages.
Open the Web.config file by using a text editor and change switchValue
back to Off
or the prior value.
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.
An 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.6949548Z error object contents
As shown in the example above, each error includes the following data properties:
Property | Description |
---|---|
Code | The unique error number identifying the type of error |
Description | Localized error message text |
Context.FullyQualifiedName | The 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.Type | The type of object involved in the error |
Context.Identifier | The identifier of the object involved in the error |
Context.Identifier.Id | The unique GUID of the object, if specified or available |
Context.Identifier.Name | The name of the object, if specified or available |
Context.Identifier.InternalId | Deprecated – don't use |
You can use the following procedure to create a log file that can help troubleshoot failures that may occur when creating an MDS database:
Open the MDSConfigTool.exe.config file in the path C:\Program Files\Microsoft SQL Server\Master Data Services\Configuration by using notepad.exe.
Uncomment the following line in the file by removing the suffix characters on that line:
<add name="LogFileListener" type="System.Diagnostics.TextWriterTraceListener" initializeData="MdsConfigManagerTrace.log" traceOutputOptions="DateTime"/>
Make sure switchValue
is set to All
.
<source name="MDS" switchType="System.Diagnostics.SourceSwitch" switchValue="All">
Try again to create the database. Then, open the file MdsConfigManagerTrace.log that is saved to C:\Program Files\Microsoft SQL Server\Master Data Services\Configuration and review the same for other information regarding the failure.
Training
Module
Capture Web Application Logs with App Service Diagnostics Logging - Training
Learn about how to capture trace output from your Azure web apps. View a live log stream and download logs files for offline analysis.