Ereignisindikatoren in SqlClient

Gilt für: .NET Framework .NET Core .NET Standard

Herunterladen von ADO.NET

Wichtig

Ereignisindikatoren sind verfügbar, wenn .NET Core 3.1 und höher oder .NET Standard 2.1 und höher als Ziel verwendet werden. Dieses Feature ist ab Microsoft.Data.SqlClientVersion 3.0.0 verfügbar.

Mithilfe von Microsoft.Data.SqlClient-Ereignisindikatoren können Sie den Status Ihrer Anwendung und die von ihr verwendeten Verbindungsressourcen überwachen. Ereignisindikatoren können von .NET CLI global tools und perfView überwacht werden. Mithilfe der Klasse EventListener im Namespace System.Diagnostics.Tracing ist auch ein programmgesteuerter Zugriff möglich.

Verfügbare Ereignisindikatoren

Zurzeit sind 16 verschiedene Ereignisindikatoren für Microsoft.Data.SqlClient verfügbar, wie in der folgenden Tabelle beschrieben:

name	`Display name`	BESCHREIBUNG
active-hard-connections	Tatsächliche aktive Verbindungen, die derzeit mit Servern bestehen	Anzahl der Verbindungen, die derzeit für Datenbankserver geöffnet sind.
hard-connects	Tatsächliche Rate der Verbindungen mit Servern	Anzahl der Verbindungen, die pro Sekunde mit Datenbankservern geöffnet wurden.
hard-disconnects	Tatsächliche Rate der Trennungen von Servern	Anzahl der Verbindungen mit Datenbankservern, die pro Sekunde getrennt wurden.
active-soft-connects	Aus dem Verbindungspool abgerufene aktive Verbindungen	Anzahl der bereits geöffneten Verbindungen, die über den Verbindungspool genutzt werden.
soft-connects	Rate der aus dem Verbindungspool abgerufenen Verbindungen	Anzahl der Verbindungen pro Sekunde, die über den Verbindungspool genutzt werden.
soft-disconnects	Anzahl der Verbindungen, die an den Verbindungspool zurückgegeben werden	Anzahl der Verbindungen pro Sekunde, die an den Verbindungspool zurückgegeben werden.
number-of-non-pooled-connections	Anzahl der Verbindungen, für die kein Verbindungspool genutzt wird	Anzahl der aktiven Verbindungen, für die kein Verbindungspool genutzt wird.
number-of-pooled-connections	Anzahl der vom Verbindungspool verwalteten Verbindungen	Anzahl der aktiven Verbindungen, die von der Verbindungspooling-Infrastruktur verwaltet werden
number-of-active-connection-pool-groups	Anzahl der aktiven eindeutigen Verbindungszeichenfolgen	Anzahl der eindeutigen Verbindungspoolgruppen, die aktiv sind. Dieser Indikator wird von der Anzahl der eindeutigen Verbindungszeichenfolgen gesteuert, die in der Anwendungsdomäne (AppDomain) gefunden werden.
number-of-inactive-connection-pool-groups	Anzahl der eindeutigen Verbindungszeichenfolgen, die darauf warten, gelöscht zu werden	Anzahl der eindeutigen Verbindungspoolgruppen, die zum Löschen gekennzeichnet sind. Dieser Indikator wird von der Anzahl der eindeutigen Verbindungszeichenfolgen gesteuert, die in der Anwendungsdomäne (AppDomain) gefunden werden.
number-of-active-connection-pools	Anzahl der aktiven Verbindungspools	Gesamtzahl der Verbindungspools
number-of-inactive-connection-pools	Anzahl der inaktiven Verbindungspools	Anzahl der inaktiven Verbindungspools, die in letzter Zeit keine Aktivitäten zu verzeichnen hatten und darauf warten, gelöscht zu werden
number-of-active-connections	Anzahl der aktiven Verbindungen	Anzahl der aktiven Verbindungen, die gerade genutzt werden
number-of-free-connections	Anzahl der bereiten Verbindungen im Verbindungspool	Anzahl der offenen Verbindungen, die für die Verwendung in den Verbindungspools verfügbar sind.
number-of-stasis-connections	Anzahl der Verbindungen, die derzeit auf den Bereitstatus warten	Anzahl der Verbindungen, die derzeit auf den Abschluss einer Aktion warten und für die Verwendung durch die Anwendung nicht verfügbar sind.
number-of-reclaimed-connections	Anzahl der von der GC freigegebenen Verbindungen	Anzahl der Verbindungen, die durch die Garbage Collection freigegeben wurden, wobei Close oder Dispose nicht von der Anwendung aufgerufen wurde. Hinweis: Das nicht explizite Schließen oder Freigeben von Verbindungen beeinträchtigt die Leistung.

Abrufen von Werten für Ereignisindikatoren

Es gibt zwei Hauptmethoden, um EventCounters in-process oder out-of-process zu nutzen. Weitere Informationen finden Sie unter Consume EventCounters.

Out-of-Process-Nutzung

Unter Windows können Sie PerfView und Xperf verwenden, um Daten zu Ereignisindikatordaten zu erfassen. Weitere Informationen finden Sie unter Aktivieren der Ereignisablaufverfolgung in SqlClient. Sie können die plattformübergreifenden .NET-Tools dotnet-counters und dotnet-trace verwenden, um Daten zu Ereignisindikatoren zu überwachen und zu erfassen.

Out-of-Process-Beispiel

Der folgende Befehl führt SqlClient-Ereignisindikatoren aus und erfasst entsprechende Werte einmal pro Sekunde. Wenn EventCounterIntervalSec=1 durch einen höheren Wert ersetzt wird, ist die Erfassung einer kleineren Ablaufverfolgung mit geringerer Granularität für die Indikatordaten möglich.

PerfView /onlyProviders=*Microsoft.Data.SqlClient.EventSource:EventCounterIntervalSec=1 run "<application-Path>"

Der folgende Befehl erfasst Werte für SqlClient-Ereignisindikatoren einmal pro Sekunde.

dotnet-trace collect --process-id <pid> --providers Microsoft.Data.SqlClient.EventSource:0:1:EventCounterIntervalSec=1

Der folgende Befehl überwacht Werte für SqlClient-Ereignisindikatoren einmal alle drei Sekunden.

dotnet-counters monitor Microsoft.Data.SqlClient.EventSource -p <process-id> --refresh-interval 3

Der folgende Befehl überwacht Werte für SqlClient-Ereignisindikatoren einmal pro Sekunde.

dotnet-counters monitor Microsoft.Data.SqlClient.EventSource[hard-connects,hard-disconnects] -p <process-id>

In-Process-Nutzung

Sie können die Indikatorwerte über die API EventListener verwenden. EventListener ist eine In-Process-Möglichkeit, ein beliebiges Ereignis zu nutzen, das von einer EventSource-Instanz in Ihrer Anwendung geschrieben wurde. Weitere Informationen finden Sie unter EventListener.

In-Process-Beispiel

Der folgende Beispielcode erfasst Microsoft.Data.SqlClient.EventSource-Ereignisse mithilfe von EventCounterIntervalSec=1. Er schreibt den Namen des Indikators und den dazugehörigen Mean-Wert bei jeder Aktualisierung für den Ereignisindikator.

Hinweis

Bei Aktivierung dieses Ereignisses muss der Eigenschaftswert EventCounterIntervalSec angegeben werden.

using System;
using System.Collections.Generic;
using System.Diagnostics.Tracing;
using System.Linq;

// 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 EventCounterListener : EventListener
{
    protected override void OnEventSourceCreated(EventSource eventSource)
    {
        // Only enable events from SqlClientEventSource.
        if (eventSource.Name.Equals("Microsoft.Data.SqlClient.EventSource"))
        {
            var options = new Dictionary<string, string>();
            // define time interval 1 second
            // without defining this parameter event counters will not enabled
            options.Add("EventCounterIntervalSec", "1");
            // enable for the None keyword
            EnableEvents(eventSource, EventLevel.Informational, EventKeywords.None, options);
        }
    }

    // This callback runs whenever an event is written by SqlClientEventSource.
    // Event data is accessed through the EventWrittenEventArgs parameter.
    protected override void OnEventWritten(EventWrittenEventArgs eventData)
    {
        if (eventData.Payload.FirstOrDefault(p => p is IDictionary<string, object> x && x.ContainsKey("Name")) is IDictionary<string, object> counters)
        {
            if (counters.TryGetValue("DisplayName", out object name) && name is string cntName
                && counters.TryGetValue("Mean", out object value) && value is double cntValue)
            {
                // print event counter's name and mean value
                Console.WriteLine($"{cntName}\t\t{cntValue}");
            }
        }
    }
}

class Program
{
    static void Main(string[] args)
    {
        // Create a new event listener
        using (var listener = new EventCounterListener())
        {
            string connectionString = "Data Source=localhost; Integrated Security=true";

            for (int i = 0; i < 50; i++)
            {
                // Open a connection
                SqlConnection cnn = new SqlConnection(connectionString);
                cnn.Open();
                // wait for sampling interval happens
                System.Threading.Thread.Sleep(500);
            }
        }
    }
}

Actual active connections currently made to servers           0
Active connections retrieved from the connection pool         26
Number of connections not using connection pooling            0
Number of connections managed by the connection pool          26
Number of active unique connection strings              1
Number of unique connection strings waiting for pruning       0
Number of active connection pools               1
Number of inactive connection pools             0
Number of active connections            26
Number of ready connections in the connection pool            0
Number of connections currently waiting to be ready           0
...

Siehe auch

• Leistungsindikatoren in SqlClient
• dotnet-counters
• dotnet-trace
• Aktivieren der Ereignisablaufverfolgung in SqlClient
• Microsoft ADO.NET für SQL Server