Logging

FreeTDS has quite extensive logging capabilities. These are often invaluable in setting up new configurations, when it's hard to be sure precisely what configuration information is being used, and what communication is (not) working. Often such questions can be quickly resolved by turning on logging and examining the logs.

Environment Variables that Control Logging

TDSDUMP

Log files can be turned on using the TDSDUMP environment variable. For instance, setting the location of a dumpfile

	$ export TDSDUMP=/tmp/freetds.log

Will generate a log file named freetds.log in the /tmp directory.

[Tip]Tip

The filenames stdout and stderr are also supported. They can be handy if you want to intersperse the log output with your application's output, or if your application opens more than one connection. (The logfile is otherwise normally truncated each time the library connects to the server.)

TDSDUMPCONFIG

Set TDSDUMPCONFIG to a file to write information to on how the configuration information is being obtained, e.g. from environment variables, a freetds.conf file, or interfaces file. Sometimes it's unclear what source of information FreeTDS is using to connect to a given servername. This variable can make that bright and clear.

[Tip]Tip

What if you were running Apache/PHP? Apache has many children. Setting the TDSDUMP (and/or TDSDUMPCONFIG) variable to a null string will cause FreeTDS to open a log under every PID.

	$ export TDSDUMP=""

The log files will be named /tmp/freetds.log.9999, where 9999 is the pid number of the process generating the log.

A couple of important notes about using the logs with FreeTDS. First, the logs tend to grow large, so trim or archive them often. Secondly, FreeTDS will record certain network packets to the log, this includes login packets which can contain clear text or clear text equivalent passwords. So, if this is a concern (most likely is) make sure that the files are not world readable, and avoid posting them to mailing lists.

Once in a while, someone writes to the mailing list, asking why FreeTDS is so slow. It sometimes turns out that logging was left turned on. Don't you be the next victim! FreeTDS logs are meant for development and debugging, not as a system monitoring tool.

freetds.conf variables that Control Logging

See Valid bitmask values for debug flags entry in freetds.conf

The logfile is normally truncated each time FreeTDS connects to the server.

Logging in ODBC land

(Tree-huggers need not worry)

Many ODBC Driver Managers have their own support for logging. How logging is controlled, however, varies widely by implementation. The ODBC log is often very helpful because it provides a log of all calls made directly by the application.

unixODBC

unixODBC supports logging via some entries in odbcinst.ini. For example:

	[ODBC]
	Trace        = Yes
	TraceFile    = /tmp/sql.log
	ForceTrace   = Yes

Will generate a log file named sql.log in the /tmp directory.