Traccia (Master Data Services)

Si applica a: SQL Server - Solo Windows Istanza gestita di SQL di Azure

Dopo aver installato Master Data Services (MDS), è possibile trovare la funzionalità di registrazione di traccia utile per la diagnostica degli errori, le richieste di supporto e il monitoraggio dell'utilizzo e delle prestazioni dell'applicazione. Questo articolo illustra i passaggi per attivare e configurare la registrazione di traccia. In particolare, questo articolo illustra la traccia in un file di log di testo. Questo articolo illustra anche la procedura per creare un file di log che consente di risolvere gli errori che possono verificarsi durante la creazione di un database MDS.

Background

Master Data Services è costituito da un'applicazione web ASP.NET (Gestione dati master) e da un servizio WCF; entrambi sono ospitati in IIS e in un database di SQL Server. Le richieste di Gestione dati master e le chiamate esterne all'endpoint dell'API dei servizi web vengono gestite da un livello di servizio comune. Il livello del servizio può registrare ogni richiesta/risposta dell'operazione, eventi importanti ed errori.

In qualità di amministratore con accesso ai file nel server web IIS, è possibile abilitare la registrazione modificando il file WEB.config MDS.

Per impostazione predefinita, il file Web.config si trova in una delle seguenti cartelle dell'applicazione web:

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

• SQL Server 2012 e versioni successive: program_files\Microsoft SQL Server\<nnn>\Master Data Services\WebApplication

I numeri nnn nel percorso corrispondono alla versione di SQL Server di cui è in corso l'installazione. La tabella seguente indica le versioni per i percorsi:

Registrazione traccia per l'applicazione web MDS

SQL Server 2016 e versioni successive

Il file Web.config contiene una sezione di traccia, come illustrato di seguito. Questa sezione è stata introdotta 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>

Di seguito viene illustrato il comportamento di traccia predefinito:

• La traccia è abilitata per i messaggi Warning e ActivityTracing.

  Per maggiori informazioni, vedere Enumerazione SourceLevels.

• I log vengono salvati nella cartella Log nella cartella WebApplication. Il percorso predefinito è C:\Programmi\Microsoft SQL Server\nnn\Master Data Services\WebApplication\Logs.

• Il file viene creato per ogni giorno o per ogni 10 MB.

• Quando le dimensioni della directory raggiungono i 200 MB, il log meno recente viene eliminato.

• Il formato del log è CSV. La tabella seguente descrive il formato del log:

  Elemento	Descrizione
  Data e ora	La data e l'ora della voce di traccia
  CorrelationID	Per ogni richiesta viene assegnato un ID di correlazione. Tutte le tracce attivate dalla richiesta condividono lo stesso ID di correlazione. Quando si verifica un errore nell'interfaccia utente, l'ID di correlazione viene visualizzato nel messaggio di errore
  Operazione	Nome dell'operazione di richiesta. Se la richiesta è una richiesta dell'interfaccia utente Web, il nome dell'operazione è l'URL. Se la richiesta è una richiesta API, il nome dell'operazione è il nome del servizio
  Livello	Livello di questa voce di traccia
  Message	Corpo del messaggio della traccia

SQL Server 2014 e versioni precedenti

Sezione diagnostica del file Web.config installato originariamente

Il seguente frammento di file mostra la sezione diagnostica del file Web.config installato originariamente.

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

Abilitazione della traccia dei file di log

Per abilitare la registrazione, passare da switchValue a All o a un altro valore valido, come descritto di seguito nella Tabella 1. Per abilitare l'output in un file di log, rimuovere il commento dalla riga LogFileListenercome illustrato nel frammento di file seguente:

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

Tabella 1 - Impostazioni SwitchValue per la registrazione

Percorso e nome file

Il valore initializeData è il nome del file di log. Può essere modificato in un altro nome o per includere un percorso desiderato. Se il percorso non viene specificato, il file verrà impostato come predefinito sul percorso della directory dell'applicazione web (dove risiede Web.config).

Livello di registrazione di dettaglio

La Tabella 2 seguente descrive le categorie di eventi di traccia che possono essere registrati o ordinati con gli eventi più importanti/critici nella parte superiore. La Tabella 1 sopra riporta le impostazioni valide per la registrazione switchValue. Questa impostazione può essere modificata per produrre la giusta quantità di dettagli di registrazione in base alla situazione.

Tabella 2 - Tipi di eventi di registrazione MDS

Raccomandazioni per l'impostazione del log

• Per il normale funzionamento, usare l'impostazione Off per evitare del tutto la registrazione o usare le impostazioni Error o Warning che manterranno il log ridotto avvisando gli amministratori dei problemi.
• Usare l'impostazione All per situazioni di supporto/risoluzione dei problemi.
• Usare ActivityTracing per la misurazione delle prestazioni o il monitoraggio dell'utilizzo.
• Usare Information solo se preparato per controllare e pulire periodicamente i log. I log potrebbero essere lunghi con questa impostazione. Questa impostazione è utile per tenere traccia dell'utilizzo e i criteri di utilizzo.
• Non usare Verbose o All in condizioni operative normali, poiché il volume dei dati registrati influirà negativamente sulle prestazioni.

Procedura per la creazione di un file di log per il supporto del prodotto

In situazioni in cui si verifica un errore imprevisto e sono necessarie ulteriori operazioni di diagnostica, è utile creare un file di log che tracci gli eventi che portano al problema insieme alle richieste e alle risposte del servizio.

Per produrre un file di log conciso e utile, seguire questi passaggi:

1. Se possibile, arrestare il pool di applicazioni MDS in Gestione IIS.

   Avviso

   Eseguire questa operazione solo se l'applicazione può essere disattivata.

2. Se possibile, spostare o eliminare il file di log corrente (se ne esiste già uno).

3. Aprire il file Web.config utilizzando un editor di testo.

   Nota

   Per impostazione predefinita, il file Web.config si trova in una delle seguenti cartelle dell'applicazione 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. Trovare la sezione system.diagnostics.

5. Modificare switchValue in All o ActivityTracing e rimuovere il commento dalla riga del file di log, come illustrato nella sezione Attivazione della traccia dei file di log di questo articolo.

   1. Usare switchValue="All" per la diagnostica degli errori.
   2. Usare switchValue="ActivityTracing" per la diagnostica delle prestazioni.
   3. Il nome del file MdsTrace.log può essere preceduto da un percorso, se necessario.

6. Se il pool di applicazioni è stato arrestato in precedenza, avviare il pool di applicazioni MDS in IIS. In alternativa, attendere che il file di log venga visualizzato dopo un certo periodo di tempo e dopo l'attività dell'applicazione web. L'applicazione web ricarica periodicamente le impostazioni di configurazione dal file (nel giro di pochi minuti).

7. Riprodurre il problema ed eseguire le stesse azioni o richieste che hanno causato l'errore.

8. Se è possibile arrestare il pool di applicazioni:

   1. Arrestare il pool di applicazioni.
   2. Recuperare il file di log (potrebbe essere necessario attendere il completamento dei processi; potrebbe verificarsi un ritardo dopo l'arresto del pool di app).

   In alternativa, aprire il file di log usando un editor che non blocca il file (ad esempio notepad.exe) e copiare i messaggi di traccia pertinenti.

9. Aprire il file Web.config usando un editor di testo e riportare switchValue a Off o al valore precedente.

10. Avviare il pool di applicazioni se interrotto.

    Gestione degli errori: tutte le operazioni del servizio restituiscono una matrice o una raccolta di errori all'interno dell'oggetto OperationResult di un messaggio di risposta. Quando si verifica un errore, la matrice di errori viene serializzata anche in XML e scritta nel file di log applicazioni web per determinate impostazioni switchValue , come descritto in precedenza.

Esempio di errore di risposta API scritto nel file di 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 

Come illustrato nell'esempio precedente, ogni errore include le proprietà dei seguenti dati:

Tracciare i problemi di creazione del database MDS

È possibile usare la seguente procedura per creare un file di log che consente di risolvere gli errori che possono verificarsi durante la creazione di un database MDS:

1. Aprire il file MDSConfigTool.exe.config nel percorso C:\Programmi\Microsoft SQL Server\Master Data Services\Configuration usando notepad.exe.

2. Rimuovere il commento dalla riga seguente nel file rimuovendo i caratteri del suffisso in tale riga:

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

3. Assicurarsi che switchValue sia impostato su All.

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

4. Riprovare a creare il database. Aprire quindi il file MdsConfigManagerTrace.log salvato in C:\Programmi\Microsoft SQL Server\Master Data Services\Configuration ed esaminare lo stesso file per altre informazioni relative all'errore.

Risorse esterne

Miglioramento della risoluzione dei problemi di registrazione