Ablaufverfolgung für Treibervorgänge

JDBC-Treiber herunterladen

Der Microsoft JDBC-Treiber für SQL Server unterstützt die Verwendung der Ablaufverfolgung (oder Protokollierung), um bei der Lösung von Problemen mit dem JDBC-Treiber in Ihrer Anwendung zu helfen. Für die Ablaufverfolgung verwendet der JDBC-Treiber die Protokollierungs-APIs in „java.util.logging“, die eine Reihe von Klassen zum Erstellen der Objekte „Logger“ und „LogRecord“ bereitstellen.

Wenn Sie Ihre Anwendung entwickeln, können Sie Aufrufe an Logger-Objekte absetzen, die wiederum LogRecord-Objekte erstellen. Diese werden anschließend zur Verarbeitung an Handler-Objekte übergeben. Protokollierungs- und Handlerobjekte verwenden Protokolliergrade sowie optional Protokollierungsfilter, um zu bestimmen, welche LogRecords verarbeitet werden. Nach Abschluss der Protokolliervorgänge können die Handler-Objekte die Protokollinformationen ggf. mit Formatter-Objekten veröffentlichen.

Standardmäßig schreibt das java.util.logging-Framework seine Ausgabe in eine Datei. Diese Ausgabeprotokolldatei muss Schreibberechtigungen für den Kontext aufweisen, unter dem der JDBC-Treiber ausgeführt wird.

Die folgenden Abschnitte beschreiben die Protokolliergrade sowie die protokollierbaren Kategorien und enthalten Informationen darüber, wie die Ablaufverfolgung in der Anwendung aktiviert werden kann.

Protokollierungsebenen

Jeder erstellten Protokollmeldung ist ein Protokolliergrad zugeordnet. Der Protokolliergrad bestimmt die Wichtigkeit der Protokollmeldung, die durch die Level-Klasse in „java.util.logging“ definiert wird. Durch Aktivieren der Protokollierung auf einer bestimmten Ebene wird auch die Protokollierung auf allen höheren Ebenen aktiviert. In diesem Abschnitt werden die Protokolliergrade für öffentliche und interne Protokollierungskategorien beschrieben. Weitere Informationen zu den Protokollierungskategorien finden Sie in diesem Artikel im Abschnitt „Protokollierungskategorien“.

Die einzelnen verfügbaren Protokollierungsstufen für öffentliche Protokollierungskategorien werden in der folgenden Tabelle beschrieben:

Die verfügbaren Protokolliergrade für interne Protokollierungskategorien werden in der folgenden Tabelle beschrieben:

Protokollierungskategorien

Wenn Sie ein Logger-Objekt erstellen, müssen Sie an das Objekt die benannte Entität oder Kategorie übergeben, zu der Protokollinformationen ermittelt werden sollen. Der JDBC-Treiber unterstützt die folgenden öffentlichen Protokollierungskategorien, die alle im com.microsoft.sqlserver.jdbc-Treiberpaket definiert sind.

Ab Version 2.0 des Microsoft JDBC-Treibers stellt der Treiber auch das com.microsoft.sqlserver.jdbc.internals-Paket bereit, das die Protokollierungsunterstützung für die folgenden internen Protokollierungskategorien enthält.

Programmgesteuerte Ablaufverfolgung aktivieren

Die Ablaufverfolgung kann programmgesteuert aktiviert werden, indem ein Logger-Objekt erstellt und die zu protokollierende Kategorie angegeben wird. Der folgende Code veranschaulicht beispielsweise, wie die Protokollierung für SQL-Anweisungen aktiviert wird:

Logger logger = Logger.getLogger("com.microsoft.sqlserver.jdbc.Statement");
logger.setLevel(Level.FINER);

Um die Protokollierung in Ihrem Code zu deaktivieren, verwenden Sie den folgenden Code:

logger.setLevel(Level.OFF);

Mit dem folgenden Code können Sie alle verfügbaren Kategorien protokollieren:

Logger logger = Logger.getLogger("com.microsoft.sqlserver.jdbc");
logger.setLevel(Level.FINE);

Mit dem folgenden Code können Sie die Protokollierung einer bestimmten Kategorie deaktivieren:

Logger logger = Logger.getLogger("com.microsoft.sqlserver.jdbc.Statement");
logger.setLevel(Level.OFF);

Aktivieren der Ablaufverfolgung mit der Datei „logging.properties“

Sie können die Ablaufverfolgung auch mit der Datei logging.properties aktivieren, die sich im Verzeichnis lib der JRE-Installation (Java Runtime Environment), Version 8, oder im conf-Ordner für Java 9 oder höher befindet. In dieser Datei können Sie die Standardwerte für die Protokollierung und Handler festlegen, die verwendet werden sollen, wenn die Ablaufverfolgung aktiviert ist.

Die folgende Beispielkonfiguration veranschaulicht die Einstellungen, die in logging.properties-Dateien vorgenommen werden können:

# Specify the handler, the handlers will be installed during VM startup.
handlers= java.util.logging.FileHandler

# Default global logging level.
.level= OFF

# default file output is in user's home directory.
java.util.logging.FileHandler.pattern = %h/java%u.log
java.util.logging.FileHandler.limit = 5000000
java.util.logging.FileHandler.count = 20
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.FileHandler.level = FINEST

# Facility specific properties.
com.microsoft.sqlserver.jdbc.level=FINEST

Protokollierung von Leistungsmetriken

Ab Version 13.4.0 bietet der Treiber dedizierte Leistungsmetriken-Logger, die die Zeitmessung von Verbindungs- und Anweisungsvorgängen nachverfolgen. Im Gegensatz zu den zuvor beschriebenen Diagnoseablaufverfolgungskategorien wurden diese Logger speziell für die Messung der Ausführungslatenz entwickelt, anstatt das Verhalten auf Protokollebene zu debuggen.

Es stehen zwei Leistungsprotokollierer zur Verfügung:

Legen Sie diese Logger auf Ebene fest FINE , um die Metrikausgabe zu aktivieren. Sie können auch einen programmgesteuerten Rückruf für die Metriksammlung im Prozess anstelle oder zusätzlich zur Protokollausgabe registrieren.

Konfigurationsdetails, nachverfolgte Aktivitäten und Codebeispiele finden Sie unter Performance Logger und Callback.

Siehe auch

Diagnostizieren von Problemen mit dem JDBC-Treiber