Menu
Simba Technologies
Simba Technologies

SimbaEngine X SDK 10.1.3
Developing Drivers for Data Stores Without SQL

How to Log to Event Trace for Windows (ETW)

By default, the SimbaEngine X SDK logging functionality writes events and messages to text files. You can develop your custom ODBC or JDBC driver log events and messages to Event Tracing for Windows (ETW) instead. You can also enable it to switch between file and ETW logging at runtime.

The basic steps are as follows:

  1. Define the provider GUID in your driver code
  2. Use the ETWLogger Class in your driver code

For an example of how to implement ETW logging in the QuickStart sample OBBC driver, see Example: Implementing ETW Logging.

Step 1 - Define the Provider GUID in your Driver Code

When creating a manifest file to define your provider, you created a provider GUID. Add this GUID to the driver's main header file. If you have both 32 and 64-bit drivers, you need to include both GUIDs. If your driver code is used on multiple platforms, ensure the GUID is defined just for Windows platforms. For example:

#if defined(_WIN64)

/// The 64-bit driver specific ETW provider GUID.

const GUID PROVIDER_GUID = {0x69bacf08, 0x09d0, 0x400a, {0xab, 0xd8, 0x52, 0x06, 0xd4, 0xbd, 0x79, 0x39}};

#elif defined(WIN32)

/// The 32-bit driver specific ETW provider GUID.

const GUID PROVIDER_GUID = {0x9bbc191d, 0x1d80, 0x40d1, {0xad, 0xab, 0xe1, 0x1b, 0x97, 0x3a, 0x1e, 0x90}};

#endif

Step 2 - Use the ETWLogger Class in your Driver Code

Change your custom driver code to use the ETWLogger class instead of the DSIFileLogger class.

For example, in the Quickstart sample driver you would have the following QSDriver constructor

QSDriver::QSDriver() : DSIDriver(), m_driverLog(new ETWLogger(PROVIDER_GUID))

{

ENTRANCE_LOG(m_driverLog, "Simba::Quickstart", "QSDriver", "QSDriver");

SetDriverPropertyValues();

...

}

Further Considerations

You may want to refine the example shown in Example: Implementing ETW Logging with the additional functionality described in this section.

Understanding Log Levels in Windows ETW Logging

The SimbaEngine X SDK supports six different log levels for file-based logging, and four different log levels for ETW-based logging. The following table shows the mapping between ETW log level and the LogLevel setting in the Windows registry or .ini file.

LogLevel setting ETW Log Level
1 1 (Fatal)
2 2 (Error)
3 3 (Warning)
4,5,6 4 (Debug, Information, Trace)

For example, if you configure LogLevel to 6, then Debug, Information, and Trace logs are all logged as level 4 in the ETW logger.

Increasing the File Size

By default, the maximum size of the log files for ETW logging is 1028 KB. Subsequent events are overwritten in the file. In order to see more events in the log file, you may want to increase the maximum file size by selecting properties in the Event Viewer.

Set an Activity ID

By default, the activity ID for the events is set to 0. To change this activity ID to the string of your choice, use ETWLogger::SetActivityId().

Enable logging for both 32-bit and 64-bit drivers

If you plan to ship a 32-bit and a 64-bit version of your driver, you need to create a manifest file for each version. For example, create a QuickStart32.man and a QuickStart64.man.

Important:

Be sure you create a different GUID for the 32-bit and the 64-bit manifest files. Each manifest file must have its own, unique GUID.

In the source code, define each provider GUID for the correct platform.

Example:

#if defined(_WIN64)

/// The 64-bit driver specific ETW provider GUID.

const GUID PROVIDER_GUID = {0x69bccf01, 0x08d0, 0x400a, {0xbb, 0xc8, 0x52, 0x06, 0xb4, 0xbd, 0x72, 0x39}};

#elif defined(WIN32)

/// The 32-bit driver specific ETW provider GUID.

const GUID PROVIDER_GUID = {0x9bbc737c, 0x1d70, 0x40d9, {0xad, 0xab, 0xe1, 0x8b, 0x17, 0x3a, 0x4e, 0x20}};

#endif

Allowing the user to switch between ETW and File logging

If you want allow your customers to switch between ETW logging and file logging, you can create a registry key that defines the type of logging. Then in your code, instantiate the correct logging class depending on the registry setting.

 

Related Links

Example: Implementing ETW Logging