Configuring trace

The following sections describe the different settings in the MimerTrace.config file. Refer to Configuration file examples for the syntax and placement of the settings or use Mimer SQL Data Provider Trace Control tool to manage the trace settings.

TraceCategories

traceCategory specifies the categories that will be traced. The following trace categories exists:

All - enables all categories except Internal
Error - errors and exceptions and outputs stack traces. Only exceptions that originate from the server are traced. Client exceptions are not traced.
SqlStatement - traces SQL statements
SqlParameter - traces SQL parameters
Connect - connection information
ActivityTrace - traces method calls
Info - other information of value
Internal - traces internal calls in the library, calls to private functions etc. Needs to be explicitly listed to enable.
None - disables tracing

Multiple categories can be enabled by using a comma separated list, e.g. traceCategory="SqlStatement, SqlParameter".

Listeners

There are three different types of trace listeners that can be added.

Console: directs the tracing output to the Console.Out stream. For windowed applications it may not be straight forward where the Console.Out output is located. Additional steps, depending on the application and environment, might be needed to access the console in these kinds of applications.
File: directs the tracing output to a file. By default the file used is called Mimer.Data.Client.log and is located next to MimerTrace.config. Another file can be used by specifying a file name or path using the filename attribute.

<add type="file" filename="C:\Users\username\AppData\Local\MimerSQLDataProvider\traceoutput.log"/>

Note: If multiple applications using the Mimer.Data.Client are running on the system, and an absolute path or the default file is used, each application will create their own file for the trace output. The file name will be prefixed with a hexadecimal string.

<add type="file" filename="traceoutput.log"/>

Note that if you only specify a file name, the file will be placed in the current working directory of the application. The trace system tries to create both the specified folder and file if they do not exist. If the trace system does not have write access at the location, nothing will be traced to file.

Database: direct the tracing output to a Mimer SQL database. The traceProviderConnectionString attribute is used to specify the database where the trace output will be stored. The trace output is stored in a table called DataProviderTraces, which uses a sequence called DataProviderTraceSequence. If the table and sequence does not already exist the Data Provider will try and create them. If there is no databank that the user has privilege to use, the provider will also try to create a databank called DataProviderTraceStore. This means that either the table must exists, or the user must either have TABLE or DATABANK privilege so it can be created.

Manually setting up the DataProviderTraces table

This section describes how to manually set up the DataProviderTraces table. This is relevant if a user without privilege to create tables is specified in the traceProviderConnectionString. Otherwise, the Data Provider will set things up for the user automatically. The following SQL statements can be used to manually create the sequence and table:

CREATE DATABANK DataProviderTraceStore;
CREATE SEQUENCE DataProviderTraceSequence as BIGINT NO CYCLE;

CREATE TABLE DataProviderTraces (
              Id BIGINT default next_value of DataProviderTraceSequence,
              OccurredAt TIMESTAMP,
             ProcessId INTEGER,
             ThreadId INTEGER,
              ConnectionId INTEGER,
             ApplicationName NVARCHAR(128),
             TraceCounter INTEGER,
              TraceCategory VARCHAR(32),
              Message NVARCHAR(512),
              ExtendedInfo NCLOB(1M),
             primary key (ID));

The contents of the table is further described in section Interpreting trace output.

When analyzing large amounts of log data it may be useful to have indexes on columns where you want to have conditions on the data. Adding indexes adds to the amount of work done during the logging so it may slow down logging somewhat.

CREATE INDEX TraceIndex1 on DataProviderTraces(TraceCategory);
CREATE INDEX TraceIndex2 on DataProviderTraces(Message);

The creator of the table, such as SYSADM, can grant insert privilege to another user.

GRANT INSERT ON TABLE DataProviderTraces to TraceUser;

If you want the user to be able to analyze the data you can also grant select privilege at the same time.

GRANT INSERT,SELECT ON TABLE DataProviderTraces to TraceUser;

TraceUser will have to create a synonym to the DataProviderTraces table, so that the Data Provider can insert data into the table using the unqualified table name.

CREATE SYNONYM TraceUser.DataProviderTraces for SYSADM.DataProviderTraces ;

TraceOutputOptions

traceOutputOptions can be applied to the console and file trace listener. They give additional output for each trace message. The following options are available: Callstack, DateTime, LogicalOperatorStack, None, ProcessId, ThreadId, Timestamp

Filtering trace output

The trace output can be filtered by using the <filters> tag and adding one or more filters. Trace can be filtered based on application name, user ID, and database. Multiple application names, user IDs, or databases can be specified in the filter by using a comma-separated list. The application name, user ID, and database properties are set using the connection string. For each filter you can specify either include="true" or include="false". Setting include to true would include only the specified application name(s)/user ID(s)/database(s), while setting include to false would exclude the specified application name(s)/user ID(s)/database(s) from the trace output.

autoFlush

The autoFlush setting is an optional setting used to enable auto flush. autoFlush is by default set to false. Setting autoFlush to true will automatically flush the data from the buffer to the underlying stream after every trace call. This will slow down the speed of the tracing considerably. However, if the application crashes in the end you may want to see the last calls that were logged that may otherwise be lost.

Configuration Errors

Any errors occurring during the processing of the MimerTrace.config file, such as invalid XML or connection problems when using the database listener, are logged to the default trace file Mimer.Data.Client.log.

If trace is not working as expected check the Mimer.Data.Client.log for the error message to help you figure out what is wrong.

Turning trace on and off

Trace starts automatically when there is a trace configuration file. The system will detect changes to the MimerTrace.config file even when trace is active and change its behavior. If the file has invalid xml syntax or other errors, these will be logged to the Mimer.Data.Client.log file that is located next to the configuration file.

It is possible to have a file, but disable trace by setting traceCategory to None:

<mimerTrace traceCategory="None">
<listeners>
...

The important thing is to turn trace off after suitable information has been collected either through the method above or by deleting or removing the file MimerTrace.config file. Leaving trace on, will cause any applications using ADO.NET to run slower than would otherwise be the case.