Compartir vía


Seguimiento del funcionamiento del controlador

Descargar controlador JDBC

El Microsoft JDBC Driver para SQL Server admite el uso del seguimiento (o registro) para facilitar la resolución de problemas con el controlador JDBC durante su uso en la aplicación. Para habilitar el uso de la función de seguimiento, el controlador JDBC usa las API de registro de java.util.logging, que proporcionan un conjunto de clases para crear objetos Logger y LogRecord.

Nota

En el caso del componente nativo (sqljdbc_xa.dll) que se incluye con el controlador JDBC, el marco de diagnósticos integrados (BID) habilita el seguimiento. Para obtener información sobre BID, vea la página sobre seguimiento de acceso de datos de SQL Server 2005 (puede estar en inglés).

Al desarrollar la aplicación, puede realizar llamadas a objetos Logger, que a su vez crean objetos LogRecord que, después, se pasan a los objetos Handler para su procesamiento. Ambos objetos registrador y controlador usan niveles de registro y, además, filtros de registro, para regular qué LogRecords se procesan. Una vez completadas las operaciones de registro, los objetos Handler pueden usar de forma opcional objetos Formatter para publicar la información de registro.

De forma predeterminada, el marco java.util.logging escribe los resultados en un archivo. Este archivo de registro de salida debe tener permisos de escritura para el contexto en que se ejecuta el controlador JDBC.

Nota

Para obtener más información acerca del uso de varios objetos de registro para programar el seguimiento, consulte la sección sobre API de registro de Java en el sitio web de Sun Microsystems.

En la siguiente sección se describen los niveles y las categorías de registro de los que se puede hacer un seguimiento y se proporciona información sobre cómo habilitar el seguimiento en la aplicación.

Niveles de registro

Cada mensaje de registro creado tiene un nivel de registro asociado. El nivel de registro determina la importancia del mensaje de registro, que es definido por la clase Level de java.util.logging. Al habilitar el registro en un nivel, se habilita también en todos los niveles superiores. En esta sección se describen los niveles de registro para las categorías de registro públicas y también para las internas. Para más información acerca de las categorías de registro, vea en este artículo la sección Categorías de registro.

La tabla siguiente describe cada uno de los niveles de registro para categorías de registro públicas.

Nombre Descripción
SEVERE Indica un error grave y es el nivel de registro máximo. En el controlador JDBC, este nivel se utiliza para informar de errores y excepciones.
WARNING Indica un posible problema.
INFO Proporciona mensajes informativos.
CONFIG Proporciona mensajes de configuración. El controlador JDBC no proporciona actualmente mensajes de configuración.
FINE Proporciona información de seguimiento básica, que incluye todas las excepciones producidas por los métodos públicos.
FINER Proporciona información de seguimiento detallada, que incluye todos los puntos de entrada y salida de los métodos públicos junto con los tipos de datos de parámetro asociados y todas las propiedades públicas de la clase pública. Además, los parámetros de entrada, los parámetros de salida y el método devuelven valores salvo los tipos de valores de devolución CLOB, BLOB, NCLOB, Reader y <stream>.
FINEST Proporciona información de seguimiento muy detallada. Esta configuración es el nivel de registro mínimo.
Apagado Desactiva el registro.
ALL Habilita el registro de todos los mensajes.

La tabla siguiente describe cada uno de los niveles de registro para categorías de registro internas.

Nombre Descripción
SEVERE Indica un error grave y es el nivel de registro máximo. En el controlador JDBC, este nivel se utiliza para informar de errores y excepciones.
WARNING Indica un posible problema.
INFO Proporciona mensajes informativos.
FINE Proporciona información de seguimiento que incluye la creación y destrucción de objetos básicos. Además, incluye todas las excepciones producidas por los métodos públicos.
FINER Proporciona información de seguimiento detallada, que incluye todos los puntos de entrada y salida de los métodos públicos junto con los tipos de datos de parámetro asociados y todas las propiedades públicas de la clase pública. Además, los parámetros de entrada, los parámetros de salida y el método devuelven valores salvo los tipos de valores de devolución CLOB, BLOB, NCLOB, Reader y <stream>.

En la versión 1.2 del controlador JDBC existían las siguientes categorías de registro y tenían el nivel de registro FINE: SQLServerConnection, SQLServerStatement, XA y SQLServerDataSource. Desde la versión 2.0, estas categorías se han actualizado al nivel FINER.
FINEST Proporciona información de seguimiento muy detallada. Esta configuración es el nivel de registro mínimo.

En la versión 1.2 del controlador JDBC existían las siguientes categorías de registro y tenían el nivel de registro FINEST: TDS.DATA y TDS.TOKEN. Desde la versión 2.0, conservan el nivel de registro FINEST.
Apagado Desactiva el registro.
ALL Habilita el registro de todos los mensajes.

Categorías de registro

Al crear un objeto Logger, debe indicar al objeto de qué entidad con nombre o categoría le interesa obtener información de registro. El controlador JDBC admite las siguientes categorías de registro público, que son definidas en el paquete del controlador com.microsoft.sqlserver.jdbc.

Nombre Descripción
Conexión Registra mensajes en la clase SQLServerConnection. La aplicación puede configurar el nivel de registro como FINER.
. Registra mensajes en la clase SQLServerStatement. La aplicación puede configurar el nivel de registro como FINER.
DataSource Registra mensajes en la clase SQLServerDataSource. La aplicación puede configurar el nivel de registro como FINE.
ResultSet Registra mensajes en la clase SQLServerResultSet. La aplicación puede configurar el nivel de registro como FINER.
Controlador Registra mensajes en la clase SQLServerDriver. La aplicación puede configurar el nivel de registro como FINER.
Resistencia Registra los mensajes de la clase SQLServerConnection en relación solo con las reconexión de resistencia de conexión inactiva. La aplicación puede configurar el nivel de registro como FINE y FINER.
Redireccionamiento Registra los mensajes de la clase SQLServerConnection en relación solo con los reintentos abiertos de conexión. La aplicación puede configurar el nivel de registro como FINE.

Desde la versión 2.0 del controlador JDBC de Microsoft, el controlador también proporciona el paquete com.microsoft.sqlserver.jdbc.internals, que incluye la compatibilidad de registro con las siguientes categorías de registro interno.

Nombre Descripción
AuthenticationJNI Registra mensajes relativos a los problemas de autenticación integrada de Windows (cuando la propiedad de conexión authenticationScheme se establece de forma implícita o explícita en NativeAuthentication).

La aplicación puede configurar el nivel de registro como FINEST y FINE.
SQLServerConnection Registra mensajes en la clase SQLServerConnection. La aplicación puede configurar el nivel de registro como FINE y FINER.
SQLServerDataSource Registra mensajes en las clases SQLServerDataSource, SQLServerConnectionPoolDataSource y SQLServerPooledConnection.

La aplicación puede configurar el nivel de registro como FINER.
InputStream Registra mensajes relativos a los siguientes tipos de datos: java.io.InputStream, java.io.Reader y a los tipos de datos que tienen un especificador máximo, como varchar, nvarchar y los tipos de datos varbinary.

La aplicación puede configurar el nivel de registro como FINER.
SQLServerException Registra mensajes en la clase SQLServerException. La aplicación puede configurar el nivel de registro como FINE.
SQLServerResultSet Registra mensajes en la clase SQLServerResultSet. La aplicación puede configurar el nivel de registro como FINE, FINER y FINEST.
SQLServerStatement Registra mensajes en la clase SQLServerStatement. La aplicación puede configurar el nivel de registro como FINE, FINER y FINEST.
XA Registra mensajes para todas las transacciones XA de la clase SQLServerXADataSource. La aplicación puede configurar el nivel de registro como FINE y FINER.
KerbAuthentication Registra mensajes relativos a la autenticación Kerberos de tipo 4 (cuando la propiedad de conexión authenticationScheme se establece en JavaKerberos). La aplicación puede configurar el nivel de registro como FINE o FINER.
TDS.DATA Registra mensajes que contienen la conversación de nivel de protocolo TDS entre el controlador y SQL Server. Los contenidos detallados de cada paquete TDS enviado y recibido se registran en ASCII y como hexadecimales. No se registran las credenciales de inicio de sesión (nombres y contraseñas de usuarios). Todos los demás datos se registran.

Esta categoría crea mensajes muy detallados y solo se puede habilitar si se establece el nivel de registro en FINEST.
TDS.Channel Esta categoría realiza un seguimiento del canal de comunicaciones TDS con SQL Server. El mensaje registrado incluye la apertura y cierre de sockets, así como lecturas y escrituras. También realiza seguimientos de mensajes relacionados con el establecimiento de una conexión de Seguridad de la capa de transporte (TLS), antes conocida como Capa de sockets seguros (SSL), con SQL Server.

Esta categoría solo puede ser habilitada configurando el nivel de registro en FINE, FINER o FINEST.
TDS.Writer Esta categoría realiza un seguimiento de las escrituras en el canal TDS. Solo se hace un seguimiento de la longitud de las escrituras, no de los contenidos. Esta categoría también hace un seguimiento de los problemas que se producen cuando una señal de atención es enviada al servidor para cancelar la ejecución de una instrucción.

Esta categoría solo puede ser habilitada configurando el nivel de registro en FINEST.
TDS.Reader Esta categoría realiza un seguimiento de determinadas operaciones de lectura desde el canal TDS en el nivel FINEST. En el nivel FINEST, el seguimiento puede ser detallado. En los niveles WARNING y SEVERE, esta categoría realiza un seguimiento cuando el controlador recibe un protocolo TDS no válido antes de que el controlador cierre la conexión.

Esta categoría solo puede ser habilitada configurando el nivel de registro en FINER y FINEST.
TDS.Command Esta categoría hace un seguimiento de las transiciones de estado de bajo nivel y de otras informaciones asociadas a la ejecución de comandos TDS, como ejecuciones de instrucciones Transact-SQL, recuperaciones de cursores ResultSet, confirmaciones, etc.

Esta categoría solo puede ser habilitada configurando el nivel de registro en FINEST.
TDS.TOKEN Esta categoría registra solo los tokens de los paquetes TDS y es menos detallado que la categoría TDS.DATA. Solo se puede habilitar configurando el nivel de registro en FINEST.

En el nivel FINEST, esta categoría hace un seguimiento de los tokens TDS conforme son procesados en la respuesta. En el nivel SEVERE, esta categoría hace un seguimiento cuando encuentra un token TDS no válido.
SQLServerDatabaseMetaData Registra mensajes en la clase SQLServerDatabaseMetaData. La aplicación puede configurar el nivel de registro como FINE.
SQLServerResultSetMetaData Registra mensajes en la clase SQLServerResultSetMetaData. La aplicación puede configurar el nivel de registro como FINE.
SQLServerParameterMetaData Registra mensajes en la clase SQLServerParameterMetaData. La aplicación puede configurar el nivel de registro como FINE.
SQLServerBlob Registra mensajes en la clase SQLServerBlob. La aplicación puede configurar el nivel de registro como FINE.
SQLServerClob Registra mensajes en la clase SQLServerClob. La aplicación puede configurar el nivel de registro como FINE.
SQLServerSQLXML Registra mensajes en la clase interna SQLServerSQLXML. La aplicación puede configurar el nivel de registro como FINE.
SQLServerDriver Registra mensajes en la clase SQLServerDriver. La aplicación puede configurar el nivel de registro como FINE.
SQLServerNClob Registra mensajes en la clase SQLServerNClob. La aplicación puede configurar el nivel de registro como FINE.

Habilitar el seguimiento mediante programación

El seguimiento se puede habilitar mediante programación si se crea un objeto Logger y se indica la categoría que se va a registrar. Por ejemplo, el siguiente código muestra cómo habilitar el registro para las instrucciones SQL:

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

Para desactivar el registro en el código, use lo siguiente:

logger.setLevel(Level.OFF);

Para registrar todas las categorías disponibles, use lo siguiente:

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

Para deshabilitar el registro de una categoría específica, use lo siguiente:

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

Habilitar el seguimiento mediante el archivo logging.properties

Además, puede habilitar el seguimiento con el archivo logging.properties, que se encuentra en el directorio lib de la instalación de Java Runtime Environment (JRE) 8 o en la carpeta conf para Java 9 y superior. Este archivo se puede usar para establecer los valores predeterminados para los registradores y controladores que se usan al habilitar el seguimiento.

El siguiente ejemplo de configuración se puede usar en los archivos logging.properties:

# 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

Nota

Puede establecer las propiedades del archivo logging.properties con el objeto LogManager que forma parte de java.util.logging.

Consulte también

Diagnóstico de problemas del controlador JDBC