Ablaufverfolgung für Treibervorgänge
Microsoft JDBC-Treiber für SQL Server unterstützt die Verwendung der Ablaufverfolgung (oder Protokollierung), um die Lösung von Problemen mit dem JDBC-Treiber in der Anwendung zu ermöglichen. 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.
Hinweis
Für die im JDBC-Treiber enthaltene systemeigene Komponente ("sqljdbc_xa.dll") wird die Ablaufverfolgung durch das BID-Framework (Built-In Diagnostics) ermöglicht. Informationen zu BID finden Sie unter Verfolgung des Datenzugriffs in SQL Server.
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 erfolgt die Ausgabe des java.util.logging-Frameworks in eine Datei. Diese Ausgabeprotokolldatei muss Schreibberechtigungen für den Kontext aufweisen, unter dem der JDBC-Treiber ausgeführt wird.
Hinweis
Weitere Informationen zur Verwendung der verschiedenen Protokollierungsobjekte für die Programmablaufverfolgung finden Sie unter Java Logging APIs auf der Sun Microsystems-Website.
Die folgenden Abschnitte beschreiben die Protokolliergrade sowie die protokollierbaren Kategorien und enthalten Informationen darüber, wie die Ablaufverfolgung in der Anwendung aktiviert werden kann.
Protokolliergrade
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 für einen bestimmten Grad wird auch das Protokollieren für alle höheren Grade 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 verfügbaren Protokolliergrade für öffentliche Protokollierungskategorien werden in der folgenden Tabelle beschrieben:
| Name | BESCHREIBUNG |
|---|---|
| SEVERE | Der höchste Protokolliergrad, der schwerwiegende Fehler kennzeichnet. Im JDBC-Treiber wird dieser Grad für Fehler und Ausnahmen verwendet. |
| WARNING | Kennzeichnet ein mögliches Problem. |
| INFO | Stellt informative Meldungen bereit. |
| CONFIG | Stellt Konfigurationsmeldungen bereit. Der JDBC-Treiber stellt derzeit keine Konfigurationsmeldungen bereit. |
| FINE | Stellt grundlegende Ablaufverfolgungsinformationen einschließlich aller von den öffentlichen Methoden ausgelösten Ausnahmen bereit. |
| FINER | Stellt ausführliche Ablaufverfolgungsinformationen einschließlich aller Ein- und Ausstiegspunkte von öffentlichen Methoden mit den zugeordneten Parameterdatentypen und allen öffentlichen Eigenschaften für öffentliche Klassen bereit. Auch Eingabeparameter, Ausgabeparameter und Methodenrückgabewerte mit Ausnahme der Rückgabewerttypen CLOB, BLOB, NCLOB, Reader und <stream>. |
| FINEST | Stellt sehr ausführliche Ablaufverfolgungsinformationen bereit. Diese Einstellung ist der niedrigste Protokolliergrad. |
| OFF | Schaltet die Protokollierung aus. |
| ALL | Aktiviert die Protokollierung aller Meldungen. |
Die verfügbaren Protokolliergrade für interne Protokollierungskategorien werden in der folgenden Tabelle beschrieben:
| Name | BESCHREIBUNG |
|---|---|
| SEVERE | Der höchste Protokolliergrad, der schwerwiegende Fehler kennzeichnet. Im JDBC-Treiber wird dieser Grad für Fehler und Ausnahmen verwendet. |
| WARNING | Kennzeichnet ein mögliches Problem. |
| INFO | Stellt informative Meldungen bereit. |
| FINE | Stellt Ablaufverfolgungsinformationen einschließlich grundlegender Informationen zum Erstellen und Löschen von Objekten. Außerdem alle von den öffentlichen Methoden ausgelösten Ausnahmen. |
| FINER | Stellt ausführliche Ablaufverfolgungsinformationen einschließlich aller Ein- und Ausstiegspunkte von öffentlichen Methoden mit den zugeordneten Parameterdatentypen und allen öffentlichen Eigenschaften für öffentliche Klassen bereit. Auch Eingabeparameter, Ausgabeparameter und Methodenrückgabewerte mit Ausnahme der Rückgabewerttypen CLOB, BLOB, NCLOB, Reader und <stream>. In Version 1.2 des JDBC-Treibers waren die folgenden Protokollierungskategorien vorhanden, die auch den Protokolliergrad FINE aufweisen: SQLServerConnection, SQLServerStatement, XA und SQLServerDataSource. Diese Kategorien wurden ab Version 2.0 auf den Grad FINER hochgestuft. |
| FINEST | Stellt sehr ausführliche Ablaufverfolgungsinformationen bereit. Diese Einstellung ist der niedrigste Protokolliergrad. In Version 1.2 des JDBC-Treibers waren die folgenden Protokollierungskategorien vorhanden, die auch den Protokolliergrad FINEST aufweisen: TDS.DATA und TDS.TOKEN. Diese behalten ab Version 2.0 den Protokolliergrad FINEST bei. |
| OFF | Schaltet die Protokollierung aus. |
| ALL | Aktiviert die Protokollierung aller Meldungen. |
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.
| Name | BESCHREIBUNG |
|---|---|
| Verbindung | Protokolliert Meldungen in der Klasse SQLServerConnection. Die Anwendungen können den Protokolliergrad auf FINER festlegen. |
| -Anweisung. | Protokolliert Meldungen in der Klasse SQLServerStatement. Die Anwendungen können den Protokolliergrad auf FINER festlegen. |
| DataSource | Protokolliert Meldungen in der Klasse SQLServerDataSource. Die Anwendungen können den Protokolliergrad auf FINE festlegen. |
| ResultSet | Protokolliert Meldungen in der Klasse SQLServerResultSet. Die Anwendungen können den Protokolliergrad auf FINER festlegen. |
| Treiber | Protokolliert Meldungen in der Klasse SQLServerDriver. Die Anwendungen können den Protokolliergrad auf FINER festlegen. |
| Resilienz | Protokolliert Meldungen in der Klasse SQLServerConnection, die nur die Wiederherstellung der Verbindungsresilienz im Leerlauf betreffen. Die Anwendungen können den Protokolliergrad auf FINE und FINER festlegen. |
| Umleitung | Protokolliert Meldungen in der Klasse SQLServerConnection, die nur Wiederholungsversuche mit offener Verbindung betreffen. Die Anwendungen können den Protokolliergrad auf FINE festlegen. |
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.
| Name | BESCHREIBUNG |
|---|---|
| AuthenticationJNI | Mit dieser Kategorie werden Meldungen zu Problemen bei der integrierten Windows-Authentifizierung protokolliert (wenn die Verbindungseigenschaft authenticationScheme implizit oder explizit auf NativeAuthentication festgelegt ist). Die Anwendungen können den Protokolliergrad auf FINER und FINE festlegen. |
| SQLServerConnection | Protokolliert Meldungen in der Klasse SQLServerConnection. Die Anwendungen können den Protokolliergrad auf FINE und FINER festlegen. |
| SQLServerDataSource | Protokolliert Meldungen in den Klassen SQLServerDataSource, SQLServerConnectionPoolDataSource und SQLServerPooledConnection. Die Anwendungen können den Protokolliergrad auf FINER festlegen. |
| InputStream | Protokolliert Meldungen zu den folgenden Datentypen: java.io.InputStream, java.io.Reader und Datentypen mit einem max-Spezifizierer wie die Datentypen varchar, nvarchar und varbinary. Die Anwendungen können den Protokolliergrad auf FINER festlegen. |
| SQLServerException | Protokolliert Meldungen in der Klasse SQLServerException. Die Anwendungen können den Protokolliergrad auf FINE festlegen. |
| SQLServerResultSet | Protokolliert Meldungen in der Klasse SQLServerResultSet. Die Anwendungen können den Protokolliergrad auf FINE, FINER und FINEST festlegen. |
| SQLServerStatement | Protokolliert Meldungen in der Klasse SQLServerStatement. Die Anwendungen können den Protokolliergrad auf FINE, FINER und FINEST festlegen. |
| XA | Protokolliert Meldungen für alle XA-Transaktionen in der Klasse SQLServerXADataSource. Die Anwendungen können den Protokolliergrad auf FINE und FINER festlegen. |
| KerbAuthentication | Mit dieser Kategorie werden Meldungen zur Kerberos-Authentifizierung Typ 4 protokolliert (wenn die Verbindungseigenschaft authenticationScheme auf JavaKerberos festgelegt ist). Für die Anwendung kann der Protokolliergrad auf FINE oder FINER festgelegt werden. |
| TDS.DATA | Protokolliert Meldungen, die Konversationen auf TDS-Protokollebene zwischen Treiber und SQL Server enthalten. Die ausführlichen Inhalte jedes gesendeten und empfangenen TDS-Pakets werden in ASCII und hexadezimal protokolliert. Die Anmeldeinformationen (Benutzernamen und Kennwörter) werden nicht protokolliert. Alle sonstigen Daten werden protokolliert. Diese Kategorie erstellt sehr ausführliche Meldungen. Sie kann nur aktiviert werden, indem der Protokolliergrad auf FINEST festgelegt wird. |
| TDS.Channel | Diese Kategorie verfolgt Aktionen der TCP-Kommunikationskanäle mit SQL Server. Die protokollierten Meldungen umfassen das Öffnen und Schließen von Sockets sowie Lese- und Schreibvorgänge. Außerdem werden Meldungen für das Herstellen einer Transport Layer Security-Verbindung (TLS) mit SQL Server, zuvor als Secure Sockets Layer (SSL) bezeichnet, verfolgt. Diese Kategorie kann nur aktiviert werden, indem der Protokolliergrad auf FINE, FINER oder FINEST festgelegt wird. |
| TDS.Writer | Diese Kategorie verfolgt Schreibvorgänge für den TDS-Kanal. Es wird nur die Länge der Schreibvorgänge verfolgt, nicht deren Inhalt. Diese Kategorie verfolgt außerdem Probleme, wenn zum Abbrechen der Ausführung einer Anweisung ein Achtungssignal gesendet wird. Diese Kategorie kann nur aktiviert werden, indem der Protokolliergrad auf FINEST festgelegt wird. |
| TDS.Reader | Diese Kategorie verfolgt bestimmte Lesevorgänge für den TDS-Kanal mit dem Grad FINEST. Die Nachverfolgung mit dem Grad FINEST kann ausführlich ausfallen. Mit den Graden WARNING und SEVERE wird in dieser Kategorie verfolgt, wenn der Treiber ein ungültiges TDS-Protokoll von SQL Server empfängt, bevor der Treiber die Verbindung trennt. Diese Kategorie kann nur aktiviert werden, indem der Protokolliergrad auf FINER und FINEST festgelegt wird. |
| TDS.Command | Diese Kategorie verfolgt Zustandsübergänge auf niedriger Ebene und sonstige Informationen zur Ausführung von TDS-Befehlen wie der Ausführung von Transact-SQL-Anweisungen, Abrufvorgängen von ResultSet-Cursorn, Commits usw. Diese Kategorie kann nur aktiviert werden, indem der Protokolliergrad auf FINEST festgelegt wird. |
| TDS.TOKEN | Diese Kategorie protokolliert nur die Token im TDS-Paket und ist weniger ausführlich als die TDS.DATA-Kategorie. Sie kann nur aktiviert werden, indem der Protokolliergrad auf FINEST festgelegt wird. Mit dem Grad FINEST verfolgt diese Kategorie TDS-Token bei der Verarbeitung in der Antwort. Mit dem Grad SEVERE verfolgt diese Kategorie das Auftreten ungültiger TDS-Token. |
| SQLServerDatabaseMetaData | Protokolliert Meldungen in der Klasse SQLServerDatabaseMetaData. Die Anwendungen können den Protokolliergrad auf FINE festlegen. |
| SQLServerResultSetMetaData | Protokolliert Meldungen in der Klasse SQLServerResultSetMetaData. Die Anwendungen können den Protokolliergrad auf FINE festlegen. |
| SQLServerParameterMetaData | Protokolliert Meldungen in der Klasse SQLServerParameterMetaData. Die Anwendungen können den Protokolliergrad auf FINE festlegen. |
| SQLServerBlob | Protokolliert Meldungen in der Klasse SQLServerBlob. Die Anwendungen können den Protokolliergrad auf FINE festlegen. |
| SQLServerClob | Protokolliert Meldungen in der Klasse SQLServerClob. Die Anwendungen können den Protokolliergrad auf FINE festlegen. |
| SQLServerSQLXML | Mit dieser Kategorie werden Meldungen in der internen SQLServerSQLXML-Klasse protokolliert. Die Anwendungen können den Protokolliergrad auf FINE festlegen. |
| SQLServerDriver | Protokolliert Meldungen in der Klasse SQLServerDriver. Die Anwendungen können den Protokolliergrad auf FINE festlegen. |
| SQLServerNClob | Protokolliert Meldungen in der Klasse SQLServerNClob. Die Anwendungen können den Protokolliergrad auf FINE festlegen. |
Programmgesteuerte Aktivierung der Ablaufverfolgung
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);
Die Protokollierung können Sie im Code folgendermaßen deaktivieren:
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 Protokollierungund Handler festlegen, die bei Aktivierung der Ablaufverfolgung verwendet werden sollen.
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
Hinweis
Mit dem Objekt „LogManager“, das Bestandteil von „java.util.logging“ ist, können Sie die Eigenschaften in der Datei logging.properties festlegen.