Menu
Simba Technologies
Simba Technologies

SimbaEngine X SDK 10.1.3
Developing Drivers for Data Stores Without SQL

Example: Implementing ETW Logging

This example shows one way that you could configure ETW logging for the QuickStart driver. The steps are:

Note:

This examples helps you get started. For more details, see Further Considerations.

Step 1 - Create a Manifest File for the QuickStart Driver

Create a manifest file to define the QuickStart driver as an event provider, then compile the file to generate resources.

To create the manifest file:

  1. Copy the following XML into a text editor:
  2. <?xml version="1.0" encoding="UTF-16"?>
    <instrumentationManifest xsi:schemaLocation="http://schemas.microsoft.com/win/2004/08/events eventman.xsd" xmlns="http://schemas.microsoft.com/win/2004/08/events" xmlns:win="http://manifests.microsoft.com/win/2004/08/windows/events" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:trace="http://schemas.microsoft.com/win/2004/08/events/trace">
      <instrumentation>
        <events>
          <provider name="DriverName" guid="{MYGUID}" symbol="DriverName" resourceFileName="Path to driver dll" messageFileName="Path to driver dll">
            <events>
              <event symbol="DebugInfoTraceEvent" value="0" version="0" channel="Admin" level="win:Informational" template="AllEventsTemplate" message="$(string.DriverName.event.0.message)">
              </event>
              <event symbol="ErrorEvent" value="1" version="0" channel="Admin" level="win:Error" template="AllEventsTemplate" message="$(string.DriverName.event.1.message)">
              </event>
              <event symbol="FatalEvent" value="2" version="0" channel="Admin" level="win:Critical" template="AllEventsTemplate" message="$(string.DriverName.event.2.message)">
              </event>
              <event symbol="WarnEvent" value="3" version="0" channel="Admin" level="win:Warning" template="AllEventsTemplate" message="$(string.DriverName.event.3.message)">
              </event>
            </events>
            <levels>
            </levels>
            <channels>
              <channel name="Admin" chid="Admin" symbol="Admin" type="Admin" enabled="true">
              </channel>
            </channels>
            <templates>
              <template tid="AllEventsTemplate">
                <data name="message" inType="win:UnicodeString" outType="xs:string">
                </data>
              </template>
            </templates>
          </provider>
        </events>
      </instrumentation>
      <localization>
        <resources culture="en-US">
          <stringTable>
            <string id="level.Warning" value="Warning">
            </string>
            <string id="level.Informational" value="Information">
            </string>
            <string id="level.Error" value="Error">
            </string>
            <string id="level.Critical" value="Critical">
            </string>
            <string id="DriverName.event.3.message" value="%1">
            </string>
            <string id="DriverName.event.2.message" value="%1">
            </string>
            <string id="DriverName.event.1.message" value="%1">
            </string>
            <string id="DriverName.event.0.message" value="%1">
            </string>
          </stringTable>
        </resources>
      </localization>
    </instrumentationManifest>
    
  3. Save the file as Quickstart.man.
  4. Replace every instance of DriverName with QuickStart.
  5. Find and replace Path to driver dll with the complete path to your driver. Be sure to use the correct DLL for debug, platform, and bitness.
  6. Generate a new GUID and use it to replace MYGUID:
    1. In Visual Studio, select Tools > Create Guid.
    2. Select option 3 then select Copy.
    3. Screenshot of how to create a GUID

    4. Paste the first line into the manifest file, and save the second line to paste into your source code.
  7. Save and close the Quickstart.man file.

To compile the manifest file:

  1. Open a command prompt and navigate to the directory where your Quickstart.man file is stored.
  2. Run the following command:
  3. "C:\Program Files (x86)\Windows Kits\8.1\bin\x64\MC" Quickstart.man -um -z QuickstartEvents

The manifest file is compiled and the resource files are generated:

Selecting the correct manifest file

Step 2 - Create the Master Resources File

Create a master resources file to consume the resources you generated in the previous step.

To create the master resources file:

  1. In the Source/Resources folder of your Visual Studio project, create a text file called Master.rc.
  2. Add this file to the driver's Visual Studio project:

    1. Right click the Resources folder in the driver project in Visual Studio and select Add > Existing Items
    2. Browse to Resources folder, select the Master.rc file that you created, and click Add.
  3. In a text editor, open the Master.rc file and #include all of the .rc files in the QuickStart project. Also include the files you generated in the previous step. Save and close the file.

    Example: Master.rc file

    #include "Dialogs.rc"

    #include "QuickstartVersion.rc"

    #include "QuickstartEvents.rc"

  4. In a text editor, open the Visual Studio project and remove references to any resource files other than the Master.rc file.

    Example: Remove the lines shown below

    <ItemGroup>

    <ResourceCompile Include="Resources\Dialogs.rc" />

    <ResourceCompile Include="Resources\Master.rc" />

    <ResourceCompile Include="Resources\QuickstartVersion.rc" />

    </ItemGroup>

  5. Update the QuickStart driver project:
    1. In Visual Studio, right-click the QuickStart project and select Properties.
    2. Select Configuration Properties > Resources and select General.
    3. Change the Resource File Name field to $(IntDir)\Master.res .
    4. Click Apply.

    Configuring Visual Studio propertier

 

Step 3 - Update the QuickStart Driver Code

Modify the QuickStart driver code to use the ETWLogger class instead of the default file logger class.

To use the ETW logger class:

  1. In Visual Studio, open the QuickStart solution, then open the file Core > Include > QSDriver.h.
  2. Define the GUID you created earlier. This will be the driver's provider GUID.
  3. Example: In QSDriver.h

    namespace Simba

    {

    namespace Quickstart

    {

    const GUID PROVIDER_GUID = { 0xf77f8f1e, 0xb189, 0x49ed, { 0xa3, 0xd9, 0xab, 0x72, 0x39, 0x19, 0xd2, 0x17 } };

  4. Open the QSDriver.cpp file and add the following line:

    #include "ETWLogger.h"

  5. In the QuickStart driver's constructor, change the existing logger to ETWLogger. Pass in the PROVIDER_GUID.
  6. Example:

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

Step 4 - Configure ETW to Log QuickStart Events

Register the driver with ETW and enable logging.

To configure ETW to log QuickStartEvents:

  1. Register the QuickStart driver as an ETW provider:
    1. Open a command prompt with administrator privileges.
    2. In the directory containing the Quickstart.man file, type the following command:

      wevtutil im Quickstart.man /resourceFilePath:"C:\Simba Technologies\SimbaEngineSDK\10.1\Examples\Source\Quickstart\Bin\Windows_vs2013\debug32md\QuickstartDSIIODBC32.dll" /messageFilePath:"C:\Simba Technologies\SimbaEngineSDK\10.1\Examples\Source\Quickstart\Bin\Windows_vs2013\debug32md\QuickstartDSIIODBC32.dll"

  2. Ensure the driver is configured for logging by setting the following registry key to 6:>
    • Use HKEY_LOCAL_MACHINE\SOFTWARE\Simba\Quickstart\Driver for a 32-bit driver on a 32-bit machine or a 64-bit driver on a 64-bit machine
    • Or, use HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Simba\Quickstart\Driver\LogLevel for a 32-bit driver on a 64-bit machine
  3. Open Event Viewer by typing Event Viewer in the Start Menu.
  4. In Event Viewer, expand Applications and Services Logs > Simba > DSII > Quickstart and select Admin.

    Note:

    If nothing appears under Applications and Services Logs, wait a few minutes for Event Viewer to populate.

  5. Right-click on Admin and select Enable Log.

    Event Viewer screenshot

Step 5 - Generate Loggable Activity in the QuickStart Driver

To see events logged in ETW, you need to configure the driver to start logging, then use it for something such as establishing a connection.

To create activity that will be logged:

  1. Navigate to the folder containing the ODBC Test application, by default:
  2. C:\Program Files (x86)\Microsoft Data Access SDK 2.8\Tools

  3. Navigate to the folder that corresponds to your driver’s architecture: amd64, ia64 or x86.

    Example:

    If you built the 32-bit version of your driver on a 64-bit machine, select the x86 version.

  4. Click one:
    • odbcte32.exe to launch the ANSI version
    • Or, odbct32w.exe to launch the Unicode version.
    Important:

    Make sure that you run the correct version of the ODBC Test tool for ANSI or Unicode and 32-bit or 64-bit.

  5. In the ODBC Test tool, click Conn > Full Connect.
  6. In Event Viewer, navigate to Applicationsand Services Logs > Simba > DSII > Quickstart and select Admin.
  7. The trace logs are recorded as events (you may need to wait a few minutes): Event Viewer Screenshot

 

Related Links

How to Log to Event Trace for Windows (ETW)

For information on rebranding the Simba registry key to your own company name, see Rebranding Your Driver.