Rastreamento (Master Data Services)

Aplica-se a: SQL Server - somente Windows Instância Gerenciada de SQL do Azure

Depois de instalar o Master Data Services (MDS), o recurso de registro de rastreamento poderá ser útil para diagnósticos de erros, solicitações de suporte e monitoramento do uso e do desempenho do aplicativo. Este artigo aborda as etapas para ativar e configurar o registro de rastreamento. Especificamente, este artigo aborda o rastreamento para um arquivo de log de texto. Este artigo também aborda o procedimento para criar um arquivo de log que pode ajudar a solucionar falhas que possam ocorrer durante a criação de um banco de dados MDS.

Tela de fundo

O Master Data Services consiste em um aplicativo Web ASP.NET (Master Data Manager) e um serviço WCF; ambos são hospedados no IIS e em um banco de dados do SQL Server. As solicitações do Master Data Manager e as chamadas externas para o ponto de extremidade da API de serviços Web são tratadas por uma camada de serviço comum. A camada de serviço pode registrar cada solicitação/resposta de operação, eventos importantes e erros.

Como administrador com acesso a arquivos no servidor Web do IIS, você pode ativar o registro em log modificando o arquivo Web.config do MDS.

Por padrão, o arquivo Web.config está em uma das seguintes pastas de aplicativos Web:

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

• SQL Server 2012 e versões posteriores: program_files\Microsoft SQL Server\<nnn>\Master Data Services\WebApplication

Os números no caminho nnn correspondem à versão do SQL que está sendo instalado. A tabela a seguir identifica as versões dos caminhos:

Registro de rastreamento para o aplicativo Web MDS

SQL Server 2016 e versões posteriores

O arquivo Web.config contém uma seção de rastreamento, conforme mostrado abaixo. Esta seção foi introduzida no 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>

Este é o comportamento de rastreamento padrão:

• O rastreamento está habilitado para as mensagens Warning e ActivityTracing.

  Para saber mais, veja Enumeração SourceLevels.

• Os logs são salvos na pasta Logs na pasta WebApplication. O local padrão é C:\Program Files\Microsoft SQL Server\nnn\Master Data Services\WebApplication\Logs.

• O arquivo é criado para cada dia ou a cada 10 MB.

• Quando o tamanho atingir 200 MB, o log mais antigo será excluído.

• O formato de log é CSV. A tabela a seguir descreve o formato de log

  Element	Descrição
  Hora	Quando ocorre a entrada de rastreamento
  CorrelationID	Uma ID de correlação é atribuída a cada solicitação. Todos os rastreamentos disparados por esta solicitação compartilharão a mesma ID de correlação. Quando ocorre um erro na interface do usuário, a ID de correlação aparece na mensagem de erro
  Operação	Nome da operação de solicitação. Se a solicitação for uma solicitação de interface do usuário da Web, o nome da operação será a url. Se a solicitação for uma solicitação de API, o nome da operação será o nome do serviço
  Nível	Nível desta entrada de rastreamento
  Mensagem	O corpo da mensagem do rastreamento

SQL Server 2014 e versões anteriores

Seção de diagnósticos do arquivo Web.config originalmente instalado

O trecho de arquivo a seguir mostra a seção de diagnóstico do arquivo Web.config originalmente instalado.

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

Ativação do rastreamento de arquivos de log

Para ativar o registro em log, altere switchValue para All ou outro valor válido, conforme descrito abaixo na Tabela 1. Para habilitar a saída para um arquivo de log, remova a marca de comentário da linha LogFileListener, conforme mostrado no seguinte trecho de arquivo:

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

Tabela 1 - Configurações de SwitchValue para registro em log

Caminho e nome do arquivo

O valor initializeData é o nome do arquivo de log. Isso pode ser modificado para outro nome ou para incluir um caminho desejado. Se o caminho não for especificado, o arquivo terá como padrão o caminho do diretório do aplicativo Web (onde reside o Web.config).

Nível de detalhe do registro em log

A Tabela 2 abaixo descreve as categorias de eventos de rastreamento que podem ser registrados ou classificados com os eventos mais importantes/críticos na parte superior. A Tabela 1 acima lista as configurações válidas para o registro em log de switchValue. Essa configuração pode ser ajustada para produzir a quantidade certa de detalhes de registro de acordo com a situação.

Tabela 2 - Tipos de eventos de registro em log do MDS

Recomendações de configuração de log

• Para a operação normal, use a configuração Off para evitar totalmente o registro ou use as configurações Error ou Warning que manterão o log pequeno e alertarão os administradores sobre problemas.
• Use a configuração All para situações de suporte/solução de problemas.
• Use o site ActivityTracing para medida de desempenho ou monitoramento do uso.
• Use Information somente se estiver preparado para verificar e limpar os logs periodicamente. Os logs podem ficar extensos com essa configuração. Essa configuração é útil para rastrear o uso e os padrões de uso.
• Não use Verbose ou All em condições normais de operação, pois o volume de dados registrados afetará negativamente o desempenho.

Etapas para criar um arquivo de log para suporte ao produto

Em situações em que ocorre um erro inesperado e são necessários mais diagnósticos, é útil criar um arquivo de registro que rastreie os eventos que levaram ao problema, juntamente com as solicitações de serviço e as respostas.

Para produzir um arquivo de log conciso e útil, siga estas etapas:

1. Se possível, interrompa o pool de aplicativos MDS no Gerenciador do IIS.

   Aviso

   Faça isso somente se o aplicativo puder ser retirado do ar.

2. Se possível, mova ou exclua o arquivo de log atual (se já existir um).

3. Abra o arquivo Web.config em um editor de texto.

   Observação

   Por padrão, o arquivo Web.config está em uma das seguintes pastas de aplicativos 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. Localize a seção system.diagnostics.

5. Altere o endereço switchValue para All ou ActivityTracing e descomente a linha do arquivo de log, conforme mostrado na seção Ativação do rastreamento de arquivos de log deste artigo.

   1. Use switchValue="All" para diagnóstico de erros.
   2. Use switchValue="ActivityTracing" para diagnóstico de desempenho.
   3. O nome do arquivo MdsTrace.log pode ser prefixado com um caminho, se desejado.

6. Se o pool de aplicativos tiver sido interrompido anteriormente, inicie o pool de aplicativos MDS no IIS. Ou então aguarde o arquivo de log aparecer após algum tempo e a atividade do aplicativo Web. O aplicativo Web recarregará periodicamente as definições de configuração do arquivo (o que deve ocorrer em alguns minutos).

7. Reproduza o problema e execute as mesmas ações ou solicitações que levaram ao erro.

8. Se você conseguir interromper o pool de aplicativos:

   1. Interrompa o pool de aplicativos.
   2. Recupere o arquivo de log (talvez seja necessário aguardar a conclusão dos processos; pode haver um atraso após a interrupção do pool de aplicativos).

   Ou então, abra o arquivo de registro usando um editor que não bloqueie o arquivo (como notepad.exe) e copie as mensagens de rastreamento relevantes.

9. Abra o arquivo Web.config usando um editor de texto e altere switchValue de volta para Off ou o valor anterior.

10. Inicie o pool de aplicativos se estiver parado.

    Tratamento de erros: todas as operações de serviço retornam uma matriz ou coleção de erros no objeto OperationResult de uma mensagem de resposta. Quando ocorre um erro, a matriz de erros também é serializada em XML e gravada no arquivo de log do aplicativo Web para determinadas configurações do switchValue, conforme descrito acima.

Um exemplo de erro de resposta da API que foi gravado no arquivo de log:

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 

Conforme mostrado no exemplo acima, cada erro inclui as seguintes propriedades de dados:

Rastreamento de problemas de criação de banco de dados MDS

É possível usar o procedimento a seguir para criar um arquivo de log que pode ajudar a solucionar falhas que possam ocorrer ao criar um banco de dados MDS:

1. Abra o arquivo MDSConfigTool.exe.config no caminho C:\Program Files\Microsoft SQL Server\Master Data Services\Configuration usando o notepad.exe.

2. Remova a marca de comentário da seguinte linha do arquivo, removendo os caracteres de sufixo nessa linha:

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

3. Verifique se a switchValue está definido como All.

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

4. Tente criar o banco de dados novamente. Em seguida, abra o arquivo MdsConfigManagerTrace.log salvo em C:\Program Files\Microsoft SQL Server\Master Data Services\Configuration e examine-o para obter outras informações sobre a falha.

Recursos externos

Melhoria do registro em log de solução de problemas