Habilitar o rastreamento de eventos no SqlClient
Aplicável a: .NET Framework .NET .NET Standard
O ETW (Rastreamento de Eventos para Windows) é um recurso de rastreamento eficiente no nível de kernel que permite registrar eventos definidos pelo driver para fins de depuração e teste. O SqlClient dá suporte à captura de eventos ETW em diferentes níveis informativos. Para começar a capturar esses rastreamentos de eventos, os aplicativos cliente devem escutar eventos da implementação EventSource do SqlClient:
Microsoft.Data.SqlClient.EventSource
A implementação atual dá suporte às seguintes palavras-chave de evento:
Nome da palavra-chave | Valor | DESCRIÇÃO |
---|---|---|
ExecutionTrace | 1 | Ativa a captura de eventos Iniciar/Parar antes e depois da execução do comando. |
Trace | 2 | Ativa a captura de eventos básicos de rastreamento de fluxo de aplicativo. |
Escopo | 4 | Ativa a captura de eventos de entrada e saída |
NotificationTrace | 8 | Ativa a captura de eventos de rastreamento de SqlNotification |
NotificationScope | 16 | Ativa a captura de eventos de entrada e saída de escopo de SqlNotification |
PoolerTrace | 32 | Ativa a captura de eventos de rastreamento de fluxo do pool de conexões. |
PoolerScope | 64 | Ativa a captura de eventos de rastreamento do escopo do pool de conexões. |
AdvancedTrace | 128 | Ativa a captura de eventos de rastreamento de fluxo avançado. |
AdvancedTraceBin | 256 | Ativa a captura de eventos de rastreamento de fluxo avançado com informações adicionais. |
CorrelationTrace | 512 | Ativa a captura de eventos de rastreamento de fluxo de correlação. |
StateDump | 1024 | Ativa a captura do despejo de estado completo de SqlConnection |
SNITrace | 2.048 | Ativa a captura de eventos de rastreamento de fluxo da implementação de Rede Gerenciada (aplicável somente no .NET Core) |
SNIScope | 4096 | Ativa a captura de eventos de escopo da implementação de Rede Gerenciada (aplicável somente no .NET Core) |
Exemplo
O exemplo a seguir habilita o rastreamento de eventos para uma operação de dados no banco de dados de exemplo AdventureWorks e exibe os eventos na janela do console.
using System;
using System.Diagnostics.Tracing;
using Microsoft.Data.SqlClient;
// This listener class will listen for events from the SqlClientEventSource class.
// SqlClientEventSource is an implementation of the EventSource class which gives
// it the ability to create events.
public class SqlClientListener : EventListener
{
protected override void OnEventSourceCreated(EventSource eventSource)
{
// Only enable events from SqlClientEventSource.
if (eventSource.Name.Equals("Microsoft.Data.SqlClient.EventSource"))
{
// Use EventKeyWord 2 to capture basic application flow events.
// See the above table for all available keywords.
EnableEvents(eventSource, EventLevel.Informational, (EventKeywords)2);
}
}
// This callback runs whenever an event is written by SqlClientEventSource.
// Event data is accessed through the EventWrittenEventArgs parameter.
protected override void OnEventWritten(EventWrittenEventArgs eventData)
{
// Print event data.
Console.WriteLine(eventData.Payload[0]);
}
}
class Program
{
public static void Main()
{
// Create a new event listener.
using (SqlClientListener listener = new SqlClientListener())
{
string connectionString = "Data Source=localhost; " +
"Initial Catalog=AdventureWorks; Integrated Security=true";
// Open a connection to the AdventureWorks database.
using (SqlConnection connection = new SqlConnection(connectionString))
{
connection.Open();
string sql = "SELECT * FROM Sales.Currency";
SqlCommand command = new SqlCommand(sql, connection);
// Perform a data operation on the server.
SqlDataReader reader = command.ExecuteReader();
while (reader.Read())
{
// Read the data.
}
reader.Close();
}
}
}
}
Suporte ao rastreamento de eventos no SNI nativo
Começando no v2.1, o Microsoft.Data.SqlClient dá suporte ao rastreamento de eventos em Microsoft.Data.SqlClient.SNI e Microsoft.Data.SqlClient.SNI.runtime. Os eventos podem ser coletados das DLLs nativas usando as ferramentas Xperf e PerfView.
Começando no Microsoft.Data.SqlClient v3.0, o rastreamento de eventos pode ser habilitado sem modificações no aplicativo cliente usando ferramentas de coleta de eventos.
Com o Microsoft.Data.SqlClient v2.1, o rastreamento de eventos precisa ser habilitado configurando o EventCommand
com um ouvinte de origem do evento. Os valores EventCommand
válidos aplicáveis ao SNI Nativo são:
// Enables trace events:
EventSource.SendCommand(eventSource, (EventCommand)8192, null);
// Enables flow events:
EventSource.SendCommand(eventSource, (EventCommand)16384, null);
// Enables both trace and flow events:
EventSource.SendCommand(eventSource, (EventCommand)(8192 | 16384), null);
O exemplo a seguir habilita o rastreamento de eventos em DLLs do SNI nativo.
// Native SNI tracing example
using System;
using System.Diagnostics.Tracing;
using Microsoft.Data.SqlClient;
public class SqlClientListener : EventListener
{
protected override void OnEventSourceCreated(EventSource eventSource)
{
if (eventSource.Name.Equals("Microsoft.Data.SqlClient.EventSource"))
{
// Enables both trace and flow events
EventSource.SendCommand(eventSource, (EventCommand)(8192 | 16384), null);
}
}
}
class Program
{
static string connectionString = @"Data Source = localhost; Initial Catalog = AdventureWorks;Integrated Security=true;";
static void Main(string[] args)
{
// Event source listener configuration is not required in v3.0 onwards.
using (SqlClientListener listener = new SqlClientListener())
using (SqlConnection connection = new SqlConnection(connectionString))
{
connection.Open();
}
}
}
Usar Xperf para coletar rastreamento
Inicie o rastreamento usando o comando a seguir.
xperf -start trace -f myTrace.etl -on *Microsoft.Data.SqlClient.EventSource
Execute o exemplo de rastreamento do SNI nativo para se conectar ao SQL Server.
Pare o rastreamento usando a linha de comando a seguir.
xperf -stop trace
Use PerfView para abrir o arquivo myTrace.etl especificado na etapa 1. O log de rastreamento do SNI pode ser encontrado com os nomes de evento
Microsoft.Data.SqlClient.EventSource/SNIScope
eMicrosoft.Data.SqlClient.EventSource/SNITrace
.
Usar PerfView para coletar rastreamentos
Inicie o PerfView e execute
Collect > Collect
na barra de menus.Configure o nome do arquivo de rastreamento, o caminho de saída e o nome do provedor.
Inicie a coleta.
Execute o exemplo de rastreamento do SNI nativo para se conectar ao SQL Server.
Interrompa a coleta no PerfView. Leva algum tempo para gerar o arquivo PerfViewData.etl de acordo com a configuração na Etapa 2.
Abra o arquivo
etl
no PerfView. O log de rastreamento do SNI pode ser encontrado com os nomes de eventoMicrosoft.Data.SqlClient.EventSource/SNIScope
eMicrosoft.Data.SqlClient.EventSource/SNITrace
.
Usar PerfCollect para coletar rastreamentos
No Linux, o PerfCollect pode ser usado para capturar rastreamentos. O PerfCollect é um script bash que usa ferramentas .NET para coletar rastreamentos para aplicativos .NET. Para obter mais informações sobre o PerfCollect, consulte Rastreamento de desempenho no Linux. Os rastreamentos criados pelo PerfCollect podem ser exibidos no PerfView.
Se ainda não estiver instalado, instale o curl (os comandos do Ubuntu são fornecidos):
sudo apt-get update sudo apt-get install curl
Instale o PerfCollect:
sudo curl –OL http://aka.ms/perfcollect sudo chmod +x perfcollect sudo ./perfcollect install
Defina variáveis de ambiente para o PerfCollect:
export COMPles_perfMapEnab;ed=1 export COMPlus_EnableEventLog=1
Coletar logs:
sudo ./perfcollect collect <trace file name>
Execute o aplicativo separadamente e deixe-o ser executado pelo tempo necessário para reproduzir o problema. Se for um problema de alta CPU, 5 a 10 segundos geralmente são suficientes. Pressione CTRL+C para interromper o rastreamento.
Copie o arquivo de rastreamento para outro sistema e visualize-o no PerfView.
Recursos externos
Para obter outro conjunto de exemplos sobre como rastrear a plataforma cruzada Microsoft.Data.SqlClient, confira o Wiki Ferramentas de Rede do SQL do CSS.
Para obter mais informações sobre o rastreamento de eventos, confira os recursos a seguir.
Recurso | Descrição |
---|---|
EventSource Class | Usado para criar eventos de ETW. |
Classe EventListener | Fornece métodos para habilitar e desabilitar eventos de origens do evento. |