通过

跟踪 (Master Data Services)

  • 项目

适用于：SQL Server - 仅限 Windows Azure SQL 托管实例

安装好 Master Data Services (MDS) 后，你可能会发现跟踪日志记录功能对于错误诊断、支持请求以及监视应用程序使用情况和性能等任务非常实用。 本文介绍了打开和配置跟踪日志记录的步骤。 本文特别介绍了对文本日志文件的跟踪。 本文还讨论了创建日志文件的过程，日志文件有助于排除创建 MDS 数据库时可能发生的故障。

背景

Master Data Services 由 ASP.NET Web 应用程序（主数据管理器）和 WCF 服务组成；这两者都在 IIS 和 SQL Server 数据库中承载。 主数据管理器请求和对 Web 服务 API 端点的外部调用由通用服务层处理。 服务层可以记录每个操作请求/响应、重要的事件和错误。

作为有权访问 IIS Web 服务器中文件的管理员，你可以通过修改 MDS Web.config 文件来启用日志记录。

默认情况下，Web.config 文件位于以下 Web 应用程序文件夹之一中：

  • SQL Server 2008 R2：program_files\Microsoft SQL Server\Master Data Services\WebApplication

  • SQL Server 2012 及更高版本：program_files\Microsoft SQL Server\<nnn>\Master Data Services\WebApplication

路径中的数字 nnn 对应安装的 SQL Server 版本。 下表列举了路径的版本：

版本 nnn
SQL Server 2019 150
SQL Server 2017 140
SQL Server 2016 130
SQL Server 2014 120
SQL Server 2012 110

注意

更新 Web.config 将导致 IIS 中的 MDS 应用程序域被回收。 现有用户会话将丢失缓存的信息，并且用户可能会遇到会话错误或页面加载缓慢的情况。 应尽可能在非高峰时间执行更改。

MDS Web 应用程序的跟踪日志记录

SQL Server 2016 及更高版本

Web.config 文件包含一个跟踪部分，如下所示。 这一部分是在 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>

以下是默认跟踪行为：

  • 为 Warning 和 ActivityTracing 消息启用了跟踪。

    有关详细信息，请参阅 SourceLevels 枚举。

  • 日志保存在 WebApplication 文件夹下的 Logs 文件夹中。 默认位置为 C:\Program Files\Microsoft SQL Server\nnn\Master Data Services\WebApplication\Logs。

  • 每天或每生成 10 MB 数据都会创建一次文件。

  • 当目录大小达到 200MB 时，删除最早的日志。

  • 日志格式为 CSV。 下表介绍了日志格式：

    元素 说明
    Time 跟踪条目出现的时间
    CorrelationID 每个请求都分配有一个相关 ID。 此请求触发的所有跟踪都使用同一个相关 ID。
    当 UI 中出现错误时，错误消息中会显示相关 ID
    操作 请求操作名称。 如果是 Web UI 请求，则操作名称为 URL。 如果是 API 请求，则操作名称为服务名称
    Level 此跟踪条目的级别
    消息 跟踪的消息正文

SQL Server 2014 及更早版本

最初安装的 Web.config 文件中的“诊断”部分

以下文件片段显示了最初安装的 Web.config 文件的诊断部分。

注意

switchValue 设置为 Off。 此外将会注释禁止示例行。这些行是添加各类跟踪侦听器的示例。

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

打开日志文件跟踪

要启用日志记录，请将 switchValue 更改为 All 或其他有效值，如下表 1 中所述。 要启用输出到日志文件，请取消注释 LogFileListener 行，如以下文件片段所示：

<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>
表 1 - 日志记录的 SwitchValue 设置
设置 记录的内容
关 无
错误 仅错误
警告 错误和警告
信息 错误、警告和说明性消息
详细 “信息”和其他调试跟踪信息（包括 API 请求和响应），以 XML 格式提供
活动跟踪 仅启动和停止事件
全部 “详细信息”和“活动跟踪”
文件名和路径

initializeData 值是日志文件的名称。 该文件名可修改为其他名称或包含所需的路径。 如果未指定路径，该文件将默认为 Web 应用程序目录路径（Web.config 所在的位置）。

重要

MDS 应用程序池的服务帐户必须具有对日志文件位置的写入访问权限。

日志记录的详细级别

下表 2 说明了可能记录或排序的跟踪事件类别，最重要/关键的事件位于顶部。 上表 1 列出了日志记录 switchValue 的有效设置。 可以根据相关情况的要求调整此设置以生成正确的日志记录详细信息量。

表 2 - MDS 日志记录事件类型
事件类型 说明
严重 致命错误或应用程序崩溃
错误 可恢复错误
警告 非严重问题
信息 说明性消息
详细 调试跟踪消息
开始 逻辑运算启动
停止 逻辑运算停止

日志设置建议

  • 对于常规操作，请使用 Off 设置完全关闭日志记录，或者使用 Error 或 Warning 设置保持较小的日志范围，同时提醒管理员出现问题。
  • 使用 All 设置满足支持/排除故障的需要。
  • 使用 ActivityTracing 设置满足性能测量或使用情况监视的需要。
  • 仅在需要定期检查和清理日志时使用 Information 设置。 如果使用此设置，日志可能会非常冗长。 此设置对于跟踪使用情况和使用情况模式非常实用。
  • 请勿在正常操作条件下使用 Verbose 或 All 设置，因为记录的数据量会对性能产生负面影响。

创建产品支持所需日志文件的步骤

发生意外错误并且需要进一步诊断时，创建日志文件来跟踪导致问题的事件以及服务请求和响应将非常实用。

要生成简洁实用的日志文件，请执行以下步骤：

注意

更新 Web.config 将导致 IIS 中的 MDS 应用程序域被回收。

  1. 尽可能在 IIS 管理器中停止 MDS 应用程序池。

    警告

    仅当应用程序可以离线时执行此操作。

  2. 如果可能，应移动或删除当前日志文件（如果已存在）。

  3. 使用文本编辑器打开 Web.config 文件。

    注意

    默认情况下，Web.config 文件位于以下 Web 应用程序文件夹之一中：

    • 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. 找到 system.diagnostics 节。

  5. 将 switchValue 更改为 All 或 ActivityTracing，并取消注释日志文件行，如本文的“启用日志文件跟踪”部分所示。

    1. 使用 switchValue="All" 满足错误诊断的需要。
    2. 使用 switchValue="ActivityTracing" 满足性能诊断的需要。
    3. 可在需要时将路径作为 MdsTrace.log 文件名的前缀。

  6. 如果应用程序池之前已停止，请启动 IIS 中的 MDS 应用程序池。 否则请等待一段时间，日志文件将在 Web 应用程序活动启动后出现。 Web 应用程序将定期从文件中重新加载配置设置（应会在几分钟内完成）。

  7. 再现问题并执行导致错误的相同操作或请求。

  8. 如果能够停止应用程序池：

    1. 停止应用程序池。
    2. 检索日志文件（可能需要等待进程完成；停止应用池后可能会有延迟）。

    否则使用不会锁定文件的编辑器（如 notepad.exe）打开日志文件，并复制相关的跟踪消息。

  9. 使用文本编辑器打开 Web.config 文件，并将 switchValue 更改回 Off 或以前的值。

  10. 启动应用程序池（如果之前已停止）。

    错误处理：所有服务操作都将返回响应消息中 OperationResult 对象的错误数组或集合。 对于某些 switchValue 设置，错误数组也会在发生错误时序列化为 XML，并写入 Web 应用程序日志文件中，如上所述。

已写入日志文件的 API 响应错误示例：

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

如上例所示，每个错误都包含以下数据属性：

properties 说明
代码 标识错误类型的唯一错误号
说明 本地化的错误消息文本
Context.FullyQualifiedName 错误中所涉对象的完全限定名称。 某些名称在其上下文中是唯一的。 使用模型名称前缀来限定实体（如 ModelName : EntityName）
Context.Type 错误中所涉对象的类型
Context.Identifier 错误中所涉对象的标识符
Context.Identifier.Id 对象的唯一 GUID（如果已指定或可用）
Context.Identifier.Name 对象的名称（如果已指定或可用）
Context.Identifier.InternalId 已弃用 - 不使用

跟踪 MDS 数据库创建问题

可以按照以下过程创建日志文件，日志文件有助于排除创建 MDS 数据库时可能发生的故障：

  1. 使用 notepad.exe 打开路径 C:\Program Files\Microsoft SQL Server\Master Data Services\Configuration 中的 MDSConfigTool.exe.config 文件。

  2. 移除文件中以下行上的 后缀字符，从而取消注释该行：

    <add name="LogFileListener" type="System.Diagnostics.TextWriterTraceListener" initializeData="MdsConfigManagerTrace.log" traceOutputOptions="DateTime"/>

  3. 确保 switchValue 设置为 All。

    <source name="MDS" switchType="System.Diagnostics.SourceSwitch" switchValue="All">

  4. 重新尝试创建数据库。 然后打开保存到 C:\Program Files\Microsoft SQL Server\Master Data Services\Configuration 的文件 MdsConfigManagerTrace.log，并查看有关失败的其他信息。

外部资源

日志记录改进疑难解答