Creazione di tracce
Il driver JDBC per Microsoft SQL Server supporta l'utilizzo di tracce (ovvero la registrazione) per consentire la risoluzione dei problemi relativi all'utilizzo del driver JDBC nelle applicazioni. Per abilitare l'utilizzo delle tracce, nel driver JDBC vengono utilizzate le API di registrazione in java.util.logging, da cui è disponibile un set di classi per la creazione degli oggetti Logger e LogRecord.
Nota
Per il componente nativo (sqljdbc_xa.dll) incluso nel driver JDBC, la creazione di tracce è abilitata grazie al framework Built-In Diagnostics (BID). Per informazioni sul BID, vedere Data Access Tracing in SQL Server 2005 (informazioni in lingua inglese).
Quando si sviluppa l'applicazione, è possibile eseguire chiamate a oggetti Logger che consentono di creare oggetti LogRecord i quali vengono quindi passati a oggetti Handler per l'elaborazione. Sia per gli oggetti Logger che per gli oggetti Handler vengono utilizzati i livelli di registrazione e, facoltativamente, i filtri di registrazione per definire quali LogRecords elaborare. Al termine delle operazioni di registrazione, con gli oggetti Handler possono facoltativamente essere utilizzati gli oggetti Formatter per pubblicare le informazioni sul log.
Per impostazione predefinita, l'output del framework java.util.logging viene scritto su un file. Tale file deve disporre di autorizzazioni di scrittura per il contesto su cui è in esecuzione il driver JDBC.
Nota
Per ulteriori informazioni sull'utilizzo dei vari oggetti di registrazione per la creazione di tracce dei programmi, vedere la documentazione Java Logging APIs (informazioni in lingua inglese) sul sito Web di Sun Microsystems.
Nelle sezioni seguenti sono descritti i livelli di registrazione e le categorie che è possibile registrare. Vengono inoltre fornite informazioni sull'abilitazione della creazione di tracce nell'applicazione.
Livelli di registrazione
A ciascun messaggio di log creato è associato un livello di registrazione. Tale livello determina l'importanza del messaggio. Il livello è definito dalla classe Level in java.util.logging. Se abilitata per un livello, la registrazione verrà abilitata per tutti i livelli superiori. In questa sezione vengono descritti i livelli di registrazione per le categorie di registrazione pubbliche e interne. Per ulteriori informazioni sulle categorie di registrazione, vedere la sezione Categorie di registrazione in questo argomento.
Nella tabella seguente sono descritti i vari livelli di registrazione disponibili per le categorie di registrazione pubbliche.
| Nome | Descrizione |
|---|---|
SEVERE |
Indica un problema grave. Si tratta del livello più elevato. Nel driver JDBC viene utilizzato per segnalare errori ed eccezioni. |
WARNING |
Indica un potenziale problema. |
INFO |
Fornisce messaggi informativi. |
CONFIG |
Fornisce messaggi sulla configurazione. Si noti che il driver JDBC non fornisce attualmente alcun messaggio sulla configurazione. |
FINE |
Fornisce informazioni di base sulle tracce, incluse tutte le eccezioni generate dai metodi pubblici. |
FINER |
Fornisce informazioni dettagliate sulle tracce, inclusi tutti i punti di ingresso e di uscita dei metodi pubblici con i tipi di dati dei parametri associati, nonché le proprietà pubbliche per le classi pubbliche. Fornisce inoltre parametri di input, parametri di output e valori restituiti del metodo ad eccezione dei tipi di valori restituiti CLOB, BLOB, NCLOB, Reader, <stream>. |
FINEST |
Fornisce le informazioni più dettagliate disponibili sulle tracce. È il livello più basso. |
OFF |
Disabilita la registrazione. |
ALL |
Abilita la registrazione di tutti i messaggi. |
Nella tabella seguente sono descritti i vari livelli di registrazione disponibili per le categorie di registrazione interne.
| Nome | Descrizione |
|---|---|
SEVERE |
Indica un problema grave. Si tratta del livello più elevato. Nel driver JDBC viene utilizzato per segnalare errori ed eccezioni. |
WARNING |
Indica un potenziale problema. |
INFO |
Fornisce messaggi informativi. |
FINE |
Fornisce informazioni di base sulle tracce, incluse la creazione e l'eliminazione di oggetti di base. Fornisce inoltre tutte le eccezioni generate dai metodi pubblici. |
FINER |
Fornisce informazioni dettagliate sulle tracce, inclusi tutti i punti di ingresso e di uscita dei metodi pubblici con i tipi di dati dei parametri associati, nonché le proprietà pubbliche per le classi pubbliche. Fornisce inoltre parametri di input, parametri di output e valori restituiti del metodo ad eccezione dei tipi di valori restituiti CLOB, BLOB, NCLOB, Reader, <stream>. Le seguenti categorie di registrazione erano incluse nella versione 1.2 del driver JDBC con il livello di registrazione FINE: SQLServerConnection, SQLServerStatement, XA e SQLServerDataSource. A partire dalla versione 2.0 sono state aggiornate al livello FINER. |
FINEST |
Fornisce le informazioni più dettagliate disponibili sulle tracce. È il livello più basso. Le seguenti categorie di registrazione erano incluse nella versione 1.2 del driver JDBC con il livello di registrazione FINEST: TDS.DATA e TDS.TOKEN. A partire dalla versione 2.0 hanno mantenuto lo stesso livello di registrazione. |
OFF |
Disabilita la registrazione. |
ALL |
Abilita la registrazione di tutti i messaggi. |
Categorie di registrazione
Quando si crea un oggetto Logger, è necessario indicare la categoria o l'entità denominata da cui si desidera ricevere le informazioni sul log. Il driver JDBC supporta le seguenti categorie di registrazione pubbliche, definite tutte nel pacchetto di driver com.microsoft.sqlserver.jdbc.
| Nome | Descrizione |
|---|---|
Connection |
Consente di registrare i messaggi nella classe SQLServerConnection. Le applicazioni possono impostare il livello di registrazione su FINER. |
Statement |
Consente di registrare i messaggi nella classe SQLServerStatement. Le applicazioni possono impostare il livello di registrazione su FINER. |
DataSource |
Consente di registrare i messaggi nella classe SQLServerDataSource. Le applicazioni possono impostare il livello di registrazione su FINE. |
ResultSet |
Consente di registrare i messaggi nella classe SQLServerResultSet. Le applicazioni possono impostare il livello di registrazione su FINER. |
Driver |
Consente di registrare i messaggi nella classe SQLServerDriver. Le applicazioni possono impostare il livello di registrazione su FINER. |
A partire dalla versione 2.0, il driver Microsoft JDBC fornisce anche il pacchetto com.microsoft.sqlserver.jdbc.internals, che include il supporto per la registrazione per le seguenti categorie di registrazione interne.
| Nome | Descrizione |
|---|---|
AuthenticationJNI |
Consente di registrare i messaggi relativi ai problemi di autenticazione integrata di Windows. Le applicazioni possono impostare il livello di registrazione su FINEST e FINE. |
SQLServerConnection |
Consente di registrare i messaggi nella classe SQLServerConnection. Le applicazioni possono impostare il livello di registrazione su FINE e FINER. |
SQLServerDataSource |
Consente di registrare i messaggi nelle classi SQLServerDataSource, SQLServerConnectionPoolDataSource e SQLServerPooledConnection. Le applicazioni possono impostare il livello di registrazione su FINER. |
InputStream |
Consente di registrare i messaggi relativi ai tipi di dati java.io.InputStream e java.io.Reader, nonché ai tipi di dati per i quali è disponibile un identificatore max, ad esempio varchar, nvarchar e varbinary. Le applicazioni possono impostare il livello di registrazione su FINER. |
SQLServerException |
Consente di registrare i messaggi nella classe SQLServerException. Le applicazioni possono impostare il livello di registrazione su FINE. |
SQLServerResultSet |
Consente di registrare i messaggi nella classe SQLServerResultSet. Le applicazioni possono impostare il livello di registrazione su FINE, FINER e FINEST. |
SQLServerStatement |
Consente di registrare i messaggi nella classe SQLServerStatement. Le applicazioni possono impostare il livello di registrazione su FINE, FINER e FINEST. |
XA |
Consente di registrare i messaggi per tutte le transazioni XA nella classe SQLServerXADataSource. Le applicazioni possono impostare il livello di registrazione su FINE e FINER. |
TDS.DATA |
Consente di registrare i messaggi contenenti la conversazione a livello di protocollo TDS tra il driver e SQL Server. Il contenuto dettagliato di ogni pacchetto TDS inviato e ricevuto viene registrato in formato ASCII ed esadecimale. Le credenziali di accesso (nomi utente e password) non vengono registrati. Tutti gli altri dati vengono registrati. Questa categoria consente di creare messaggi molto dettagliati ed esaustivi e può essere abilitata solo impostando il livello di registrazione su FINEST. |
TDS.Channel |
Questa categoria consente di creare le tracce delle azioni del canale di comunicazione TCP con SQL Server. I messaggi registrati includono l'apertura e la chiusura di socket, nonché le operazioni di lettura e scrittura. Vengono inoltre create le tracce dei messaggi correlati alla definizione di una connessione SSL (Secure Socket Layer) con SQL Server. Può essere abilitata solo impostando il livello di registrazione su FINE, FINER o FINEST. |
TDS.Writer |
Questa categoria consente di creare le tracce delle operazioni di scrittura nel canale TDS. Si noti che vengono create le tracce solo della lunghezza delle operazioni di scrittura e non del contenuto. Vengono inoltre create le tracce dei problemi quando al server viene inviato un segnale di attenzione per annullare l'esecuzione di un'istruzione. Può essere abilitata solo impostando il livello di registrazione su FINEST. |
TDS.Reader |
Questa categoria consente di creare le tracce di alcune operazioni di lettura dal canale TDS con livello FINEST. Con tale livello le tracce possono risultare particolarmente dettagliate. Con i livelli WARNING e SEVERE questa categoria consente di creare le tracce quando il driver riceve un protocollo TDS non valido da SQL Server prima della chiusura della connessione. Può essere abilitata solo impostando il livello di registrazione su FINER e FINEST. |
TDS.Command |
Questa categoria consente di creare le tracce delle transizioni di stato a basso livello e di altre informazioni associate all'esecuzione di comandi TDS, ad esempio le esecuzioni di istruzioni T-SQL, recuperi di cursori ResultSet, commit e così via. Può essere abilitata solo impostando il livello di registrazione su FINEST. |
TDS.TOKEN |
Questa categoria consente di registrare solo i token dei pacchetti di flussi TDS e risulta meno dettagliata della categoria TDS.DATA. Può essere abilitata solo impostando il livello di registrazione su FINEST. Con il livello FINEST questa categoria consente di creare le tracce dei token TDS quando vengono elaborati nella risposta. Con il livello SEVERE crea le tracce quando viene rilevato un token TDS non valido. |
SQLServerDatabaseMetaData |
Consente di registrare i messaggi nella classe SQLServerDatabaseMetaData. Le applicazioni possono impostare il livello di registrazione su FINE. |
SQLServerResultSetMetaData |
Consente di registrare i messaggi nella classe SQLServerResultSetMetaData. Le applicazioni possono impostare il livello di registrazione su FINE. |
SQLServerParameterMetaData |
Consente di registrare i messaggi nella classe SQLServerParameterMetaData. Le applicazioni possono impostare il livello di registrazione su FINE. |
SQLServerBlob |
Consente di registrare i messaggi nella classe SQLServerBlob. Le applicazioni possono impostare il livello di registrazione su FINE. |
SQLServerClob |
Consente di registrare i messaggi nella classe SQLServerClob. Le applicazioni possono impostare il livello di registrazione su FINE. |
SQLServerSQLXML |
Consente di registrare i messaggi nella classe SQLServerSQLXML interna. Le applicazioni possono impostare il livello di registrazione su FINE. |
SQLServerDriver |
Consente di registrare i messaggi nella classe SQLServerDriver. Le applicazioni possono impostare il livello di registrazione su FINE. |
SQLServerNClob |
Consente di registrare i messaggi nella classe SQLServerNClob. Le applicazioni possono impostare il livello di registrazione su FINE. |
Abilitazione delle tracce a livello di programmazione
La creazione di tracce può essere abilitata a livello di programmazione creando un oggetto Logger e indicando la categoria da registrare. Il codice seguente, ad esempio, consente di abilitare la registrazione per le istruzioni SQL:
Logger logger = Logger.getLogger("com.microsoft.sqlserver.jdbc.Statement");
logger.setLevel(Level.FINER);
Per disabilitare la registrazione dal codice, utilizzare:
logger.setLevel(Level.OFF);
Per registrare tutte le categorie disponibili, utilizzare:
Logger logger = Logger.getLogger("com.microsoft.sqlserver.jdbc");
logger.setLevel(Level.FINE);
Per disabilitare una categoria specifica, utilizzare:
Logger logger = Logger.getLogger("com.microsoft.sqlserver.jdbc.Statement");
logger.setLevel(Level.OFF);
Abilitazione delle tracce utilizzando il file Logging.Properties
La creazione di tracce può inoltre essere abilitata utilizzando il file logging.properties, disponibile nella directory lib dell'installazione Java Runtime Environment (JRE). Il file può essere utilizzato per impostare i valori predefiniti degli oggetti logger e handler utilizzati una volta abilitate le tracce.
Di seguito è riportato un esempio delle impostazioni disponibili nei file logging.properties:
# Specify the handlers to create in the root logger
# (all loggers are children of the root logger).
# The following creates two handlers.
handlers = java.util.logging.ConsoleHandler, java.util.logging.FileHandler
# Set the default logging level for the root logger.
.level = OFF
# Set the default logging level for new ConsoleHandler instances.
java.util.logging.ConsoleHandler.level = FINE
# Set the default logging level for new FileHandler instances.
java.util.logging.FileHandler.level = OFF
# Set the default formatter for new ConsoleHandler instances.
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
# Set the default logging level for the logger named ConnectionPool.
ConnectionPool.level = OFF
Nota
Per impostare le proprietà nel file logging.properties è possibile utilizzare l'oggetto LogManager, parte di java.util.logging.