You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -4,7 +4,7 @@ description: The Web.config file contains a tracing section, new in SQL Server 2
4
4
ms.custom: ""
5
5
ms.date: "03/14/2017"
6
6
ms.service: sql
7
-
ms.reviewer: ""
7
+
ms.reviewer: ramakoni
8
8
ms.subservice: master-data-services
9
9
ms.topic: conceptual
10
10
ms.assetid: 45823fc8-723a-49f2-9a11-94d241245cfd
@@ -13,54 +13,274 @@ ms.author: jiwang6
13
13
---
14
14
# Tracing (Master Data Services)
15
15
16
-
[!INCLUDE [SQL Server - Windows only ASDBMI](../includes/applies-to-version/sql-windows-only-asdbmi.md)]
16
+
[!INCLUDE [SQL Server - Windows only ASDBMI](../includes/applies-to-version/sql-windows-only-asdbmi.md)]
17
17
18
-
The Web.config file contains a tracing section, as shown below. This section is new in [!INCLUDE[sssql15-md](../includes/sssql16-md.md)][!INCLUDE[ssMDSshort](../includes/ssmdsshort-md.md)]
18
+
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.
19
+
20
+
## Background
21
+
22
+
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.
23
+
24
+
As an administrator with access to files on the IIS web server, you can enable logging by modifying the MDS *Web.config* file.
25
+
26
+
By default, the *Web.config* file is in one of the following web application folders:
27
+
28
+
-**SQL Server 2008 R2**: *program_files\Microsoft SQL Server\Master Data Services\WebApplication*
29
+
30
+
-**SQL Server 2012 and later versions**: *program_files\Microsoft SQL Server\\\<nnn>\Master Data Services\WebApplication*
31
+
32
+
The numbers *nnn* in the path correspond to the version of SQL Server being installed. The following table identifies versions for the paths:
33
+
34
+
|Version|nnn|
35
+
|-|-|
36
+
|SQL Server 2019 |150|
37
+
|SQL Server 2017 |140|
38
+
|SQL Server 2016 |130|
39
+
|SQL Server 2014 |120|
40
+
|SQL Server 2012 |110|
41
+
42
+
> [!CAUTION]
43
+
> 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.
44
+
45
+
## Tracing logging for MDS web-application
46
+
47
+
### SQL Server 2016 and later versions
48
+
49
+
The *Web.config* file contains a tracing section, as shown below. This section is introduced in [!INCLUDE [sssql15-md](../includes/sssql16-md.md)][!INCLUDE [ssMDSshort](../includes/ssmdsshort-md.md)].
19
50
20
-
```
51
+
```XML
21
52
<sources>
22
-
<!-- Adjust the switch value to control the types of messages that should be logged.
53
+
<!-- Adjust the switch value to control the types of messages that should be logged.
-Tracing is enabled for Warning and ActivityTracing messages.
74
+
- Tracing is enabled for `Warning` and `ActivityTracing` messages.
45
75
46
76
For more information, see [SourceLevels Enumeration](/dotnet/api/system.diagnostics.sourcelevels).
47
77
48
-
-The logs are saved in the Logs folder under the WebApplication folder. The default location is C:\Program Files\Microsoft SQL Server\130\Master Data Services\WebApplication\Logs.
78
+
- 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*.
49
79
50
-
-The file is created for each day or every 10 MB.
80
+
- The file is created for each day or every 10 MB.
51
81
52
-
-When the size of the directly reaches 200MB, the oldest log is deleted.
82
+
- When the size of the directory reaches 200 MB, the oldest log is deleted.
53
83
54
-
-The log format is CSV. The following table describes the log format.
84
+
- The log format is CSV. The following table describes the log format:
55
85
56
86
|Element|Description|
57
87
|-------------|-----------------|
58
-
|Time|When the trace entry occurs.|
59
-
|CorrelationID|One correlation ID is assigned for each request. All the traces trigged by this request will share the same correlation ID.<br /><br /> When an error occurs in the UI, the correlation ID appears in the error message.|
60
-
|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.|
61
-
|Level|Level of this trace entry.|
88
+
|Time|When the trace entry occurs|
89
+
|CorrelationID|One correlation ID is assigned for each request. All the traces triggered by this request will share the same correlation ID.<br/> When an error occurs in the UI, the correlation ID appears in the error message|
90
+
|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|
91
+
|Level|Level of this trace entry|
62
92
|Message|Message body of the trace|
63
-
64
-
## External Resources
65
-
Blog post, [Troubleshooting Logging Improvement](https://techcommunity.microsoft.com/t5/sql-server-integration-services/troubleshooting-logging-improvement/ba-p/388214), on msdn.com.
66
-
93
+
94
+
### SQL Server 2014 and earlier versions
95
+
96
+
#### Diagnostics section from the originally installed Web.config file
97
+
98
+
The following file snippet shows the diagnostics section from the originally installed *Web.config* file.
99
+
100
+
> [!NOTE]
101
+
> The `switchValue` is set to `Off`. Additionally, the example lines are commented out. These lines are examples for adding trace listeners of various types.
102
+
103
+
```XML
104
+
<system.diagnostics>
105
+
<sources>
106
+
<!-- Adjust the switch value to control the types of messages that should be logged. -->
To enable logging, change `switchValue` to `All` or another valid value as described below in [Table 1](#table-1---switchvalue-settings-for-logging). To enable the output to a log file, uncomment the `LogFileListener` line as shown in the following file snippet:
124
+
125
+
```xml
126
+
<system.diagnostics>
127
+
<sources>
128
+
<!-- Adjust the switch value to control the types of messages that should be logged. -->
|Verbose|"Information" and other debugging trace information including API requests and responses in XML format |
151
+
|ActivityTracing |start and stop events only |
152
+
|All|"Verbose" and "ActivityTracing" |
153
+
154
+
##### File name and path
155
+
156
+
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).
157
+
158
+
> [!IMPORTANT]
159
+
> The service account for the MDS application pool must have write access to the log file location.
160
+
161
+
#### Logging level of detail
162
+
163
+
[Table 2](#table-2---mds-logging-event-types) below describes the categories of trace events that may be logged or sorted with the most important/critical events at the top. [Table 1](#table-1---switchvalue-settings-for-logging) 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.
164
+
165
+
##### Table 2 - MDS logging event types
166
+
167
+
|Event Type |Description|
168
+
|-|-|
169
+
|Critical |a fatal error or application crash |
170
+
|Error|a recoverable error |
171
+
|Warning|a noncritical problem |
172
+
|Information|an informational message |
173
+
|Verbose |a debugging trace message |
174
+
|Start|starting of a logical operation |
175
+
|Stop|stopping of a logical operation |
176
+
177
+
#### Log setting recommendations
178
+
179
+
- For normal operation, use the `Off` setting to avoid logging altogether or use the `Error` or `Warning` settings that will keep the log small while alerting administrators to problems.
180
+
- Use the `All` setting for support/troubleshooting situations.
181
+
- Use `ActivityTracing` for performance measurement or usage monitoring.
182
+
- 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.
183
+
- Don't use `Verbose` or `All` under normal operating conditions, as the volume of data logged will negatively affect performance.
184
+
185
+
#### Steps for creating a log file for product support
186
+
187
+
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.
188
+
189
+
To produce a concise and helpful log file, follow these steps:
190
+
191
+
> [!CAUTION]
192
+
> Updating *Web.config* will cause the MDS application domain in IIS to recycle.
193
+
194
+
1. If possible, stop the MDS application pool in IIS Manager.
195
+
196
+
> [!WARNING]
197
+
> Do this only if the application can be taken off line.
198
+
199
+
1. If possible, move or delete the current log file (if one already exists).
200
+
201
+
1. Open the *Web.config* file by using a text editor.
202
+
203
+
> [!NOTE]
204
+
> By default, the *Web.config* file is in one of the following web application folders:
205
+
>
206
+
> -**SQL Server 2008 R2**: *program_files\Microsoft SQL Server\Master Data Services\WebApplication*
207
+
> -**SQL Server 2012**: *program_files\Microsoft SQL Server\110\Master Data Services\WebApplication*
208
+
209
+
1. Find the `system.diagnostics` section.
210
+
211
+
1. Change the `switchValue` to `All` or `ActivityTracing` and uncomment the log file line as shown in the [Turning on log file tracing](#turning-on-log-file-tracing) section of this article.
212
+
213
+
1. Use `switchValue="All"` for error diagnostics.
214
+
1. Use `switchValue="ActivityTracing"` for performance diagnostics.
215
+
1. The *MdsTrace.log* file name can be prefixed with a path if desired.
216
+
217
+
1. 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).
218
+
219
+
1. Reproduce the problem and perform the same actions or requests that led to the error.
220
+
221
+
1. If you're able to stop the application pool:
222
+
223
+
1. Stop the application pool.
224
+
1. Retrieve the log file (you may need to wait for processes to finish; there could be a delay after stopping the app pool).
225
+
226
+
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.
227
+
228
+
1. Open the *Web.config* file by using a text editor and change `switchValue` back to `Off` or the prior value.
229
+
230
+
1. Start the application pool if stopped.
231
+
232
+
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.
233
+
234
+
An example of an API response error that has been written to the log file:
As shown in the example above, each error includes the following data properties:
256
+
257
+
|Property|Description|
258
+
|-|-|
259
+
|Code|The unique error number identifying the type of error|
260
+
|Description|Localized error message text |
261
+
|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|
262
+
|Context.Type |The type of object involved in the error |
263
+
|Context.Identifier |The identifier of the object involved in the error |
264
+
|Context.Identifier.Id |The unique GUID of the object, if specified or available |
265
+
|Context.Identifier.Name |The name of the object, if specified or available |
266
+
|Context.Identifier.InternalId|Deprecated – don't use |
267
+
268
+
## Tracing MDS database creation issues
269
+
270
+
You can use the following procedure to create a log file that can help troubleshoot failures that may occur when creating an MDS database:
271
+
272
+
1. Open the *MDSConfigTool.exe.config* file in the path *C:\Program Files\Microsoft SQL Server\Master Data Services\Configuration* by using *notepad.exe*.
273
+
274
+
1. Uncomment the following line in the file by removing the <!-- prefix characters and --> suffix characters on that line:
1. 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.
0 commit comments