Logging

Capturing driver logging can be very helpful when diagnosing error messages or other unexpected behavior.

Basic Logging

To begin capturing driver logging, set these properties:

• Logfile: A filepath that designates the name and location of the log file.
• Verbosity: A numerical value (1-5) that determines the amount of detail in the log. See the page in the Connection Properties section for an explanation of the five levels.
• MaxLogFileSize: When the limit is hit, a new log is created in the same folder with the date and time appended to the end. The default limit is 100 MB. Values lower than 100 kB will use 100 kB as the value instead.
• MaxLogFileCount: A string specifying the maximum file count of log files. When the limit is hit, a new log is created in the same folder with the date and time appended to the end and the oldest log file will be deleted. Minimum supported value is 2. A value of 0 or a negative value indicates no limit on the count.

Once these properties are set, the driver populates the log file as it carries out various tasks, such as when authentication is performed or queries are executed. If the specified file doesn't already exist, it is created.

Log Verbosity

The verbosity level determines the amount of detail that the driver reports to the Logfile. Supported Verbosity levels range from 1 to 5.

The following list describes each level:

1	Setting Verbosity to 1 logs the query, the number of rows returned by it, the start of execution and the time taken, and any errors.
2	Setting Verbosity to 2 logs everything included in Verbosity 1, cache queries, and additional information about the request.
3	Setting Verbosity to 3 also logs HTTP headers, as well as the body of the request and the response.
4	Setting Verbosity to 4 also logs transport-level communication with the data source. This includes SSL negotiation.
5	Setting Verbosity to 5 also logs communication with the data source and additional details that may be helpful in troubleshooting problems. This includes interface commands.

For normal operations, Verbosity should not be set to greater than 1. At higher verbosities you can log substantial amounts of data, which can delay execution times.

To refine the logged content further by showing/hiding specific categories of information, see LogModules.

Sensitive Data

Verbosity levels of 3 and higher may capture information that you do not want shared outside of your organization. The following lists information of concern for each level:

• Verbosity 3: The full body of the request and the response, which includes all the data returned by the driver
• Verbosity 4: SSL certificates
• Verbosity 5: Any extra transfer data not included at Verbosity 3, such as non human-readable binary transfer data

Note: Although we mask sensitive values, such as passwords, in the connection string and any request in the log, it is always best practice to review the logs for any sensitive information before sharing outside your organization.

Advanced Logging

You may want to refine the exact information that is recorded to the log file. This can be accomplished using the LogModules property. This property allows you to filter the logging using a semicolon-separated list of logging modules.

Example property value:

LogModules=INFO;EXEC;SSL;SQL;META;

Note that the logfile filtering triggered by the Verbosity connection property takes precedence over the filtering imposed by this connection property. This means that operations of a higher verbosity level than the level specified in the Verbosity connection property are not printed in the logfile, even if they belong to one of the modules specified in this connection property.

The following table lists the available logging modules and submodules, along with a security classification that indicates the risk that their logs may expose sensitive data. These classifications reflect the driver's intended logging behavior and can help you determine which modules to include when sharing logs. Always review log contents before sharing them outside your organization, as provider-specific code may log additional information under a module:

• Safe: Internal events, lifecycle, protocol status, schema, and metadata. No customer data.
• Caution: SQL with literal values, request filters, or argument values that may indirectly expose customer data.
• Unsafe: Result sets, response bodies, payloads, raw TCP data, bulk uploads, or other customer data.

Module	Submodule	Classification	Notes
INFO	(module-level)	Safe	Connection string is logged. Passwords, secrets, and tokens are redacted; hostnames, usernames, and connection options remain.
INFO	Connec	Safe	Connection lifecycle.
INFO	Messag	Safe	Driver-internal info.
EXEC	Messag	Safe	Driver-internal execution events.
EXEC	Normlz	Caution	Rewritten/normalized queries that retain literal values (i.e., WHERE Email = '[email protected]').
EXEC	Origin	Caution	Verbatim user SQL; literals in query may include PII.
EXEC	Page	Safe	Paging metadata.
EXEC	Parsed	Caution	Parsed SQL with literals.
HTTP	KERB	Caution	Kerberos-related HTTP; auth tokens possible.
HTTP	Messag	Safe	Driver-internal HTTP.
HTTP	Unpack	Unsafe	Unpacked API responses are source data.
HTTP	Res	Unsafe	Response bodies are source data.
HTTP	Req	Caution	Request bodies may include query filters or POST values.
WSDL	—	Safe	WSDL/XSD generation only.
SSL	Certif	Safe	Cert metadata.
AUTH	Messag	Safe	Messages pertaining to authentication.
AUTH	OAuth	Safe	Messages pertaining to OAuth flow.
AUTH	Krbros	Safe	Messages pertaining to Kerberos.
SQL	Bulk	Safe	Status updates on bulk query execution.
SQL	Cache	Safe	Status of cache data being read/written.
SQL	Messag	Safe	Driver-internal SQL transaction events.
SQL	ResSet	Safe	Metadata about result sets.
SQL	Transc	Safe	Transaction metadata.
META	Cache	Safe	Messages about retrieving/writing column and table metadata.
META	Schema	Safe	Messages about schema metadata.
META	MemSto	Safe	In-memory metadata cache events.
META	Storag	Safe	Metadata persistence events.
FUNC	Errmsg	Safe	Error messages from the driver.
TCP	Send	Caution	Raw outbound TCP bytes. Would log data being written by the customer. Safe for reads.
TCP	Receiv	Unsafe	Raw inbound TCP bytes; source payloads.
FTP	Info	Safe	Protocol status.
FTP	Client	Caution	Client actions may include filenames or credentials.
FTP	Server	Unsafe	Server responses may include file contents.
SFTP	Info	Safe	Protocol status.
SFTP	To_Server	Caution	Client actions may include filenames or credentials.
SFTP	From_Server	Unsafe	Server responses may include file contents.
POP	Client	Caution	Client actions; mailbox or credential references.
POP	Server	Unsafe	Server responses may include message bodies.
POP	Status	Safe	Protocol status.
SMTP	Client	Caution	Client actions; message metadata.
SMTP	Server	Caution	Server responses; status-oriented.
SMTP	Status	Safe	Protocol status.
CORE	—	Safe	Internal product operations.
DEMN	—	Safe	SQL remoting internals.
CLJB	Commit	Safe	Only logs status updates for bulk jobs.
SRCE	—	Caution	Usage varies by driver.
TPJE	Trace	Safe	Advanced messages concerning low-level product operations.
ODBC	—	Unsafe	Logs resultset values.
ODBC	Debug	Caution	May log the user's arguments. Includes detailed diagnostic messages for troubleshooting ODBC driver behavior and API interactions.