Overview

Angara is a ETW message consumer. It is designed for receiving traces messages from your Windows driver or application on local PC and pass them to Baical server over network.


Angara is a console Windows application, it has x32 & x64 bit version and may be used from Windows XP up to Windows 10.

Main screen

Application main screen consist of few elements:

  • Angara. Main statistics:
    • Send - total amount of trace messages were sent
    • Rejected - total amount of rejected trace messages (all reasons)
    • Unknown - total amount of unknown trace messages. Usually this counter grows when Angara can't recognize incoming trace message. There are 3 possible reasons:
      • Corresponding TMF file missing
      • Corresponding TMF file is out of date, you need to regenerate it
      • Corresponding TMF contains unknown format arguments
    • TPS - traces per second
  • P7. Network statistics:
    • Free mem. - percentage of free memory
    • Rej. No connect. - amount of rejected trace messages. Reason - connection with Baical is not established
    • Rej. No Memory - amount of rejected trace messages. Reason - not enough memory
    • Rej. Internal - amount of rejected trace messages. Reason - internal problems
  • ETW statistics:
    • Traces lost - amount of lost trace messages by ETW
    • Buffers lost - amount of lost trace message buffers by ETW
    • RealT. Buf. lost - amount of lost real time trace message buffers by ETW
    • Broken Seq. - amount of skipped traces, usually it is a problem of PC performance

Using Angara

Angara usage is pretty simple and consist of few steps:

  1. Generate TMF file - this is helper file describes all driver's trace messages, you may generate it using tracepdb.exe utility
  2. Modify Angara's configuration file - "Angara.xml":
    1. ETW provider section
    2. P7 section
    3. Levels section
  3. Starting Angara

1. TMF file generation

TMF is a text file which describes all traces of your driver, this file should be generated automatically by post-build procedure of your driver. The command syntax is simple:

tracepdb.exe -o Result.tmf -f MyDriver.pdb

Command consist of next elements:

  • "tracepdb.exe" - tool is part of Windows DDK package, usually it is located in "C:\WinDDK\XXXX.XXXXX.X\tools\tracing\i386\tracepdb.exe"
  • Key "-o" used to generate single TMF file instead unique TMF file for every driver's source code file
  • Key "-f" used to specify your driver's PDB file, this file is generated automatically after every successful build

2. Configuring Angara

The second step is configuring Angara. All configuration parameters are stored inside "Angara.xml" (UTF-16 LE encoding). Configuration file has 3 main sections: ETW provider, P7, levels.


2.1. ETW provider parameters

Inside "Angara.xml" configuration file you can find XML section "Provider". The section is used to specify location of TML files, ETW provider's GUID and some additional parameters.


Section example:

<Provider TMF="" 
	  GUID="{63423ADB-D156-48d5-B0BC-8ACAEDDBD810}"
	  Level="5"
	  Flags="0xFFFFFFFFFFFFFFFF"
	  Filter=""
	  Platform="X32"
/>

Parameters:

  • TMF - directory where are located generated TMF files. If you change some TMF files while Angara is running you should restart it
  • GUID - Event trace session GUID, it is hardcoded for every driver. You can find it inside your driver source code - marco "WPP_DEFINE_CONTROL_GUID"
  • Level - You can specify minimum trace level, here is list of values from Evntrace.h:
    • 0 - NONE : Tracing is OFF
    • 1 - CRITICAL : Abnormal exit or termination
    • 2 - ERROR : Severe errors that need logging
    • 3 - WARNING : Warnings such as allocation failure
    • 4 - INFORMATION: Includes non-error cases (e.g., Entry-Exit)
    • 5 - VERBOSE : Detailed traces from intermediate steps
  • Flags - Hex bitmask of keywords that determine the category of events that you want the provider to write. The provider writes the event if any of the event's keyword bits match any of the bits set in this mask. 64 bits value max, example Flags="0xFFFFFFFFFFFFFFFF" 64 bits flag available only for Vista, Windows 7 and future OS. For old OS will be used only first 32 bits
  • Filter - The provider uses to filter data to prevent events that match the filter criteria from being written to the session. Provider determines the layout of the data and how it applies the filter to the event's data. You should specify you binary filter data in hex mode, for example Filter="0x10BB56CAB2", Angara will deliver this 5 bytes to provider. And your provider should decide how it will use this data for filtering. Angara use custom filter type equal to 0xAB1DE
  • Platform : provider platform (X32 or X64), this flag take effect on pointers printing

2.2. P7 parameters

This section is used to specify P7 parameters.


Section example:

<P7Trace Address="localhost" 
	 Port="9009" 
	 Packet="1472"
	 Name="MyChannel"
	 Sink="Baical"
/>

Parameters:

  • Address: Baical's server address (IPv4/IPv6/NetBIOS Name)
  • Port: Baical's server port (usually 9009)
  • Packet: Minimum transfer unit. We reccomend to use values in range [512..1472] for all network interfaces, except loopback (127.0.0.1, ::1). For loopback you may use up to 65535, it will increase delivery speed.
    N.B.:Wrong value can cause delivery problem. Value 512 will work everytime
  • Name: trace channel name, max length is 64 characters. You will see this name in Baical server
  • Sink: logs direction, there are few options:
    • Baical: over network to Baical server directly
    • File: to local file
    • Auto: to Baical if connection is established, otherwise to file. N.B.: connection timeout is 250 ms.
    • Null: all data will be dropped

2.3. Levels parameters

This section usually stays untouched. But if you have modified "levels" defines for your driver somehow like that:

// Define new debug levels
#define     NONE     0 // Tracing is not on
#define     FATAL    1 // Abnormal exit or termination
#define     ERROR    2 // Severe errors that need logging
#define     WARNING  3 // Warnings such as allocation failure
#define     INFO     4 // Includes non-error cases such as Entry-Exit
#define     TRACE    5 // Detailed traces from intermediate steps
#define     LOUD     6 // Detailed trace from every step

You have to update XML section as follows:

<Levels>                                     
    <Trace>                                  
        <WPP Text="LOUD"/>    
    </Trace>                                 
    <Debug>                                  
        <WPP Text="TRACE"/>    
    </Debug>                                 
    <Info>                                   
        <WPP Text="INFO"/>
    </Info>                                  
    <Warning>                                
        <WPP Text="WARNING"/>    
    </Warning>                               
    <Error>                                  
        <WPP Text="ERROR"/>      
    </Error>                                 
    <Critical>                               
        <WPP Text="FATAL"/>      
    </Critical>                              
</Levels>

3. Starting Angara

To start Angara you should:

  • Generate TMF file
  • Update XML configuration file
  • Make sure that Baical is running, it is not mandatory, you can run it later
  • Make sure that firewall will not block Angara traffic

If all steps are done you can execute command:

Angara_32.exe Angara.xml