# eXtremeDB Tracing Framework C API

> The eXtremeDB tracing framework allows applications to output trace and debugging information to a log file. All C/C++ applications should link with the `mcotrace` library. (Note that xSQL can also be configured to output trace information. Please refer to the xSQL Tracing Framework page for details.)

> ### For an overview see page Tracing Framework

> ## How to use

> Before any database operations occur, a C/C++ application can call `mco_trace_init_simple_handler()` to enable tracing with a simple single-thread handler. For example:

>         ...
>         rc = mco_db_connect( db_name, &db );
>         if ( MCO_S_OK == rc )
>         {
>             char * trace_file = "Trace_Output.dbg";
>             ...
>              mco_trace_init_simple_handler(	trace_file, MCO_TRACE_LEAVE_OPENED,
>             "At %t in module %m, thread %i caused error %e from line %l of file %f");
>             ...
>         }

> Alternatively it is possible to provide a user-defined trace handler (also called an "appender" because it appends messages to an output file) that is called on every message triggered by a traced database operation. The user-defined handler is then registered by calling the `mco_trace_set_handler()` API. (Note that this call supersedes any existing trace handler. )

>         int my_trace_handler( mco_severity severity, mco_trace_module module,
>                     const char *file, int line, const char *fmt, ...)
>         {
>             // Trace handler implementation

>             return MCO_S_OK;
>         }
>         ...
>         rc = mco_db_connect( db_name, &db );
>         if ( MCO_S_OK == rc )
>         {
>             ...
>             mco_trace_set_handler(my_trace_handler);
>             ...
>         }

> Then call `mco_trace_set_modules_mask()` to set the eXtremeDB modules for which trace output is desired and call `mco_trace_set_level()` to determine the granularity of trace messages. For example:

>         ...
>         rc = mco_db_connect( db_name, &db );
>         if ( MCO_S_OK == rc )
>         {
>             ...
>             mco_trace_set_modules_mask(1<<MCO_TRACE_TMGR | 1<<MCO_TRACE_TL);
>             mco_severity mco_trace_set_level(MCO_TRACE_ERROR);
>             ...
>         }

> ## Environment Variables

> There are three environment variables used to determine tracing behavior. These variables will work for any application linked with library `mcotrace`. (All SDK samples comes linked with library `mcotrace`.)

> MCO_TRACE | Trace will be enabled to `stderr`
> MCO_TRACE_FILE | Trace will be set to the specified file. For example:
>         MCO_TRACE_FILE=trace.dbg
> MCO_TRACE_LEVEL | Set the default level for tracing. Possible values are:
>         FATAL
>         ERROR
>         WARNING
>         NOTICE
>         INFO
>         DEBUG
>         VERBOSE
> The default value is `NOTICE`.
> MCO_TRACE_FORMAT | Can be used to specify a custom format for trace messages. For example:
>         MCO_TRACE_FORMAT="my %m trace %t message %x"  xsql
> MCO_TRACE_MODULE | Can specify a list of modules (separated by space, comma or semicolon) to trace. Valid module names are the following (which correspond to the enumerated values): "BSE", "LAYOUT", "ORDER", "DISK", "TMGR", "CONN", "DBINST", "ALLOCATOR", "INDEX", "BTREE", "KDTREE", "PTREE", "RTREE", "TRIGRAM", "HASH", "PATTERN", "CRYPT", "ZIP", "CURSOR", "WRAPPER", "XML", "BLOB", "DDL", "SQL", "RSQL", "TL", "SEQ", "FILE", "SYNC", "BACKUP", "HA", "CLUSTER", "ODBC", "PYTHON", "LUA", "JNI", "SAL", "NETWORK", "SHMEM", "TRACE", "PERF", "UDA", "XSQL", "IOT"