WELCOME

Welcome to the CDFControl 3 help guide!
v3.2.2.1

Next generation CDFControl


Introduction to CDFControl

INTRODUCTION

CDFControl is an event tracing controller/consumer, geared towards capturing Citrix Diagnostic Facility (CDF) trace messages that are output from the various Citrix tracing providers. This version CDFControl offers new capabilities, such as inserting trace, parsing filter support and more.

Various Citrix components contain built in debug trace statements, which leverage the Microsoft Event Tracing for Windows (ETW) technology. This means that these components are registered as ETW providers, and can be configured by ETW controllers to start logging their trace statements to a log file.

CDFControl has been crafted to gather critical troubleshooting data (such as CDF trace and performance data) that should help when troubleshooting complex Citrix related issues. This guide will help you become familiar with all the new features and techniques available to help you maximize your use of this application.

Next generation CDFControl


Features and capabilities

FEATURES/CAPABILITIES

CDFControl operates as a hybrid ETW controller and consumer, and offers the following:

TRACE CAPTURE
  • Capture trace to log file
  • View captured events real-time
  • Startup tracing (see below)
  • Command line capture support
  • New log file modes, such as the ability to create a new file when log max is reached.
TRACE PARSING
  • Parses trace events in real-time (and displays in an integrated viewer)
  • Parses trace events to CSV file
  • Ability to split output CSV files
  • Launches parsed trace in Excel
  • Command line parsing support (to CSV file)
  • Multiple trace file parsing
LIVE TRACE STATISTICS
  • Easy view of trace statistics, such as buffers read, events lost etc.
TMF DOWNLOAD (from Citrix online symbol server)
  • Provides ability to cache public TMF files, available from the online Citrix symbol server
  • Provides ability to dynamically retrieve required TMF file online, while parsing trace
STARTUP TRACING
  • Enables selected providers via the registry, so that the Citrix Diagnostic Facility COM Server service can start the trace upon system startup. This feature requires that the CdfSvc.exe service is installed on the machine (which it normally is for most Citrix products)

CONFIGURABLE FEATURE/COMPONENT MAPPING
  • Enables customized configuration for feature/component name and structure
  • Customized feature/component can be configured by editing the XML configuration file
SESSION INFORMATION SUPPORT
  • Provides easy view of session ID and process information for both real-time and ETL file parsing
ERROR CODE LOOKUP
  • Integrated error lookup utility, accessible from the tools menu, to easily translate windows error codes to meaningful text.
REMOTE TRACING
  • Now with the ability to enumerate machines on the network, as well as the ability to enumerate a remote machine's Citrix providers, CDFControl offers remote CDF tracing on multiple machines, and also supports inserting customizable trace into the tracing. Besides, session and process information will also be collected in remote tracing
RUNNING PROCESS LOG REPORT
  • Now when CDF traces are captured, CDFControl will also collect a running process log report, which contains a list of running processes and their respective session ID. This process log collection is automatically stopped when the CDF trace is stopped. The process log report can then be used in conjunction with the CDF trace file to help map process names and their session ID's to PID's from the CDF trace.
INSERT TRACE
  • Enables sending customizable trace statement into a running trace to mark the occurrence of specific events.
FILTER FUNCTION
  • Column header filter lets user filter the tracing from column header
  • Multiple rules filter allows user to apply multiple filtering rules to current log at the same time
  • Parsing filter supports filtering by regular expression in real-time tracing and ETL parsing
  • Provider filter allows user to search for specific module name by binary name
  • Time filter supports filtering for a specific time peroid
HPC TRACING
  • Supports HPC tracing on Windows machine installed with Citrix Receiver 4.1.100 or above. Internal user can view real-time HPC tracing messages
  • Original HPC tracing pattern will not be changed. User can still enable original HPC tracing via configurations


New in this release

  • Enhanced filtering function which includes column header filter, multiple rules filter and parsing filter, etc. Column header filter lets user filter the tracing from column header; Multiple rules filter allows user to apply multiple filtering rules to current log at the same time; Parsing filter supports filtering by regular expression in real-time tracing and ETL parsing.
  • Enhanced overall performance significantly which mainly reflect in memory consumption reduction and parsing speed improvement.
  • Introduced providers filter to allow user to search for specific module by binary or module name.
  • Supported inserting customizable trace statement into a running trace. User can send their own customized trace statement into a running trace to mark the occurrence of specific events.
  • Added comment column for trace. This feature lets user add their findings to the comments column, then save this to CSV file and pass on to others.
  • Introduced session/process information support for remote tracing.
  • Supported HPC tracing . CDFControl supports collecting HPC tracing logs on Windows machine installed with Citrix Receiver 4.1.100 or above. Internal user can view real-time HPC tracing logs. Besides, original HPC tracing pattern will not be changed. User can still enable original HPC tracing via configurations.
  • Enabled highlight function. User can highlight some rows in the viewer to distinguish from other rows.
  • Supported customizing column display. The feature lets user decide which columns should be displayed or hidden.
  • Support multiple trace file parsing
  • Support Time filter


REQUIREMENTS

  • CDFControl can be run on any Microsoft Windows machine that is Windows 2000 or newerwith .Net 2.0 or above installed
  • It must be run as a user with Administrative privileges for all features to be functional
  • On Microsoft Windows Vista and Longhorn, with UAC enabled, only trace capture requires elevation. For more information
    Running under Vista UAC


INSTALLATION

To install CDFControl, simply copy the CDFControl.exe executable file to the desired location, and then double click it to execute. For windows 8 and above, the CDFControl.exe.config file needs to be copied as well. There is no installer required.

The CDFControl v2 package includes the following files which support both 32-bit & 64-bit versions:
  • CDFControl.exe
    (Can be run standalone)
  • CDFControl.exe.config
    (Only necessary for Windows 8 system and above)

The first time you launch CDFControl.exe, the application will extract the following files to the same folder as CDFControl.exe:
  • CDFControl.xml

REMOVAL

To uninstall CDFControl and undo changes made to the system, all you need to do is to delete the files listed above and all the files generated under the same folder as CDFControl.exe.

UPGRADE

CDFControl checks version for the tool and configuration file when you launch the tool. If there is a new version, a message box will pop out to ask if you want to go to the download link.

If you select Yes, KB article for CDFControl will be opened in browser, where you can download the latest version of CDFControl tool and configuration file:
  • http://support.citrix.com/article/CTX111961


OPTIONS AND SETTINGS

TO ACCESS THE OPTIONS DIALOG

 Click on Tools --> Options

Next generation CDFControl

TRACE CAPTURE SETTINGS
TRACE FILE SETTINGS
  • Circular Log:
    Events are written to the log file, trimming off the oldest events to accommodate for the newer events when log file max is reached.
  • Sequential Log:
    Tracing stops when log file max is reached.
  • Multiple Sequential Logs (newfile):
    Creates a new trace file when the max is reached for the original. This is very useful for capturing an intermittent issue, without fear of capturing an extremely large trace file.
    (This option is not available on Windows 2000)
TRACE DETAIL SETTINGS
  • Flags:
    This range can vary from 0x7 - 0xFFFFFF (0xFFFFFF recommended)
  • Level:
    This range can vary from 1-16 (16 recommended)
TRACE FILE PATH
Set this to where you would like the resulting CDF trace file to be stored, CDFControl will create a folder under the given path to store the CDF trace file (CDFLogFile.etl). If this is not set, CDFControl creates the folder in the same directory from where the CDFControl.exe file is being run.
EVENT BUFFER MANAGEMENT
You have full control over the way CDFControl manages its event buffers. Uncheck Use Default Settings to specify your own settings:

  • Buffer Size:
    Size of each event buffer (buffer used to hold events when capturing a trace), in KB
  • Minimum Buffers:
    Minimum number of buffers to allocate for trace capture
  • Maximum Buffers:
    Maximum number of buffers to allocate for trace capture
  • Flush Buffers Every:
    Interval at which to flush buffers. Set to zero to use the default, which is that buffers will be flushed when they are filled. Setting it to a value greater than zero indicates the interval in seconds, of which to flush the buffers.

    An example of when this might be useful, is if events are taking a longer time than expected to get displayed in a real-time trace. The flush interval can then be increased to see if the buffers needed to be flushed more quickly. For example, try flushing the buffers every second, instead of waiting for them to become full, or try manipulating the size and number of buffers.
REAL TIME VIEWING
Enable the Enable real-time viewing while capturing trace check box for real-time viewing. For this to work correctly, you need to ensure that a valid TMF search path is also set. With this setting enabled, CDFControl will try to parse each trace event being captured, in real-time using the TMF search path provided. Events will still be written to the destination log file, even though they are being viewed real-time.
Note:
A trace file path must also be set for real-time viewing to work correctly, otherwise events/buffers will be lost.
Besides, there is an alternative way: use online trace message format server.
STARTUP TRACE FILE PATH
Stores the location of where the startup CDF trace file will be stored.

TRACE VIEWING SETTINGS
TMF SEARCH PATH
A semi-colon separated path to where the TMF files (to be used to decrypt the trace events) are located. This can inlcude a UNC path to a network share. This is required to be able to parse trace events.
USE ONLINE TRACE FORMAT MESSAGE SERVER
Alternative to setting a TMF search path, you can choose to use online TMF server to obtain TMF's by enabling this option
FLUSH MEMORY CACHE AFTER CONSUMER SESSION
CDFControl can cache TMF format information read from TMF files, so that subsequent parsing operations are faster. This however, has a tradeoff of memory for performance. For example, if this option is unchecked, parsing several small trace files (20MB or less) can be much faster as format information will already be cached in memory.
LOAD TRACE INTO VIEWER AFTER PARSED TO FILE
Enable this option to load a trace back into the viewer, after being parsed to file. Select this option for maximum performance. Especially useful for large trace files.
SEPERATE CSV FILE IN EVERY THOUSAND LINES
If this option is checked, the output will be split to multiple CSV files when parsing trace to files. The default value will make sure the CSV files can be opened in Microsoft Excel.
Note:
All the settings including trace capture settings and trace viewing settings will be stored in the XML configuration file CDFControl.xml. Meanwhile, these settings also apply to remote tracing.


SELECTING TRACE CATEGORIES

CDFControl provides following feature for you to select desired trace providers easily.

1. Click Trace Categories --> Select Your Categories.

2. Select the desired provider(s) from the menu.

Next generation CDFControl

Provider Filter

There are a lot of providers which is not easy for you to find specific module names. You can use provider filter to find specific module name:

Next generation CDFControl

Enter the desired module or binary name to lookup. You can also select a binary file from the file explorer.

Customize Trace Categories

All the mapping information of trace categories and CDF module names are saved in the XML configuration file CDFControl.xml, which is located in the same folder as CDFControl.exe. CDFControl reads category information from CDFControl.xml and displays it in the UI.

CDFControl creates a default configuration file automatically during application start if there is no configuration file available, then you can also customize the feature list by editing CDFControl.xml. One straightforward example is listed below:

Next generation CDFControl

All trace features of CDFControl are organized into two level menus. The first level menus contain frequently used features, and the second level menus contain sub modules of the feature.

The first level menus are mapping to features with level attribute "1". If the first level feature contains sub features with level attribute "2", the second level menus will be created accordingly. All the other levels are ignored by CDFControl.

For example, as the xml in above section shows, the top level feature Printing contains three sub features, and all these sub features'display level is 2, so they will be shown as second level menus. Also a menu named All is created for the convenience to select all sub features.


CAPTURING A TRACE

Once the appropriate trace capture settings are configured, do the following to start a trace:

1. Check the desired provider(s) available in the main application window
2. Click on Start Tracing
3. The resulting trace file will be stored using the path set in the options dialog (or using default path).

Next generation CDFControl

REALTIME TRACING:

If real-time is enabled via the Options menu and a TMF search path is also set, then performing the above steps will also cause the trace events to be displayed real-time, in the viewer window.

HPC TRACING:

HPC tracing is the only tracing mechanism in ICA core engine. To make troubleshooting problems more convenient, CDFControl supports collecting HPC tracing logs on Windows machine installed with Citrix Receiver 4.1.100 or above.

To collect HPC tracing log with CDFControl:
  1. Select the module IcaClient_HPC_Trace_CtlGuid from the provider list.

    Next generation CDFControl

  2. Click on Start tracing.
  3. Launch an ICA session and do some operations.
  4. Click on Stop tracing.

If you want to view real-time tracing, simply enable the Enable real-time viewing while capturing trace check box via the Options menu at first.
All the HPC tracing events will be encrypted before sending to ETW. Meanwhile, CDFControl will check current user¡¯s authorization, only internal user can get the decrypted information.

To parse HPC tracing log with CDFControl:
  1. Click File--> Parse Trace, select the CDFLogFile.etl file collected from above steps.
  2. Internal users can see the detailed tracing messages:

    Next generation CDFControl

  3. External users will find the information encrypted, and the trace messages will be shown as "ENCRYPTED":

    Next generation CDFControl
Note:
CDFControl will not change the original HPC tracing pattern. To enable original HPC tracing and view the tracing file with HPC Console Viewer, do the following configurations:
  1. Copy HPC_Trace.ini to local folder "C:\Program Files\Citrix\ICA Client" or "C:\Program Files (x86)\Citrix\ICA Client" and set "Enabled=1".
  2. Create a c:\tmp folder on the machine.
The HPC_Trace.ini file will enable HPC tracing and put the output files in c:\tmp. Besides, if HPC_Trace.ini is copied to the folder, CDFControl won¡¯t collect HPC tracing any more, unless you remove HPC_Trace.ini.


Trace Viewing

VIEWING A TRACE

Next generation CDFControl

To parse a trace, click the File menu and choose the desired parsing option:

CDFControl also supports shortcuts to launch tracing and other frequently used commands.
PARSE TRACE (F3)
  • Parses selected trace files, and displays events in viewer. TMF search path must be set in options dialog.
PARSE TRACE TO FILE (F4)
  • Parses trace to CSV file. Option can be set to reload trace from CSV file into CDFControl's viewer (see options menu).
SAVE VIEWER OUTPUT (Ctrl+S)
  • Saves viewer display to CSV file.
SAVE + LAUNCH IN EXCEL (Ctrl+E)
  • Saves viewer display to CSV file, and then automatically opens the file in Excel
LOAD CSV (CDF) File (F6)
  • Loads CSV file to CDFControl¡¯s viewer
START/STOP TRACING (F5)
  • Start/Stop tracing


Context Menu

OPENING TRACE VIA THE CONTEXT MENU

Simply right-click the desired etl trace file, and choose to open with CDFControl. You can choose to select Always use this program to open these types of files.

Note:
It is best to have the TMF search path set before attempting to open a trace this way, otherwise the trace events will not be displayed correctly due to missing format information from the TMF files.


VIEWING OPTIONS

Next generation CDFControl

Click on the View menu to set viewing options:

FIND
  • Launches Find dialog, for searching the event output
SHOW GRIDLINES
  • Click to toggle gridline view
AUTO SCROLL
  • Click to show/hide the most recent log in the display for real-time tracing
CLEAR VIEWER
  • Click to clear viewer contents
TOGGLE VIEWER
  • Click to show/hide viewer pane
TOGGLE PROVIDERS
  • Click to show/hide providers pane
TOGGLE SESSION
  • Click to show/hide session tree and property windows
SELECT COLUMNS
  • Click to select desired columns to display on viewer


VIEWING SESSION INFORMATION

Next generation CDFControl

After the trace has been captured, you can do the following to see details about session information:

1. Click on View --> Toggle Session
2. The session/processes information will be shown by tree view
3. Click on one process item, the right side "Properties" view displays details for the specific process
4. Click on View --> Toggle Session again to hide/show session tree and properties panel

Next generation CDFControl

Note:
CDFControl can only pick up session/process information from one source(sysinfo.csv or the trace file name(s) including session/process ID) and show it in the panel.
So if the trace files are collected from different machines, the session/process information may not be accurate for each trace message.

SESSION/PROCESS FILTER

To find target process more easily, CDFControl also provides the sort function. The process related to current tracing file will be highlighted as yellow. Besides, you can sort process by process ID or name.

Next generation CDFControl


SAVING VIEWER OUTPUT

To save viewer output:

Click on Save Viewer Output from the File menu (see viewing a trace for menu image).

Note:
If you has defined any filtering rules, the Save Viewer Output action will save the filtered result to CSV file.


DOWNLOAD TMF FILES

TMF files are required to view CDF Traces. A CDF trace contains unformatted event data (like any .etl trace file), which requires format information to construct the trace data into useful messages for viewing. Without valid TMF files that represent the message format of the captured trace, CDFControl (amongst other applications) will not be able to display any trace messages, because it would not know how to format the message data. In the past, Citrix has offered public TMF files via manual FTP download. For convenience, CDFControl offers the ability to download public TMF files so they can be saved locally - or used dynamically while parsing!

1. Choose Download TMF files from the Tools menu
2. Select from the available product versions, using the dropdown under Select Product
3. This will prompt to specify a download directory, where the downloaded TMF files will be stored
4. Click OK to begin downloading
(If an error is encountered, a message box indicating the status will be displayed)

Next generation CDFControl

DYNAMIC TMF DOWNLOAD

CDFControl offers the ability to download TMF's dynamically as needed, during trace parsing. This feature works for real-time and when parsing from file (even when parsing the trace to a file).

To enable this feature:

1. Click on Tools --> Options (see options menu).
2. Click to enable the checkbox for Use online trace message format server
3. Click Save

Then for any subsequent parsing, it will try to download the required TMF file if needed.

The TMF file is stored in the %Temp% location, and is deleted as soon as it is downloaded. This way, you don't have to worry about these TMF files remaining on the machine.

Note: You need a working internet connection for this feature to work. Data is read over HTTP.

Click for more information about how to use the Citrix Symbol Server to obtain debug symbols.


Error Lookup

ERROR CODE LOOKUP

After being annoyed with copying/pasting CDF error message text into a text editor, to then copy it into the cmd prompt to run net helpmsg or using a 3rd party utility, it was decided that it would be convenient to be able to easily copy the error codes and do a lookup right in CDFControl itself.

To launch the error lookup utility, use one of the methods outlined below:
  • Click --> Tools --> Error Code Lookup
  • Right-click the viewer window, and click on the Error Code Lookup context menu

Next generation CDFControl

To use the error lookup utility:
  1. Simply paste in the desired error code to lookup.
    Hex numbers must be prefixed with 0x otherwise it will be treated as a decimal number.
  2. Click Lookup


REMOTE TRACING

CDFControl now has the ability to start and stop CDF traces on remote machines. These remote machines do not have to be running XenApp, but can be running other Citrix products such as the Application Streaming Client, or XenDesktop etc. CDF tracing is only available on Microsoft Windows machines, and therefore the remote tracing feature will not work if targeted against a non-Windows machine, such as Linux.

    Next generation CDFControl

  1. Click on Remote Tracing from the Tools menu to launch the Remote Tracing dialog
  2. Enter the hostname or IP address of remote machine from which you want to extract its available Citrix providers, and click on Next to continue
  3. If prompted to authenticate to remote machine, enter appropriate credentials to connect
  4. This will connect to the remote machine, and then display its providers in the main provider/module window
  5. Select the desired Citrix trace providers manually or using trace categories, and click on Next to continue.
    (The selected providers/modules will attempt to get traced on the target machine; however if a specific provider/module does not exist on the target machine, then it will not get traced - but the ones that do exist, will get traced)

    Next generation CDFControl

  6. Enter the hostname or IP address of remote machines, and click on Add to add that machine to the Selected Target(s) list. (You can also click the Enumerate button, which will enumerate machines on the network and display them on the list box to the left. You can then use the >> button, to move enumerated machines to the Selected Target(s) list).

    Next generation CDFControl

  7. Once all the desired machines are added to the Selected Target(s) list, clicking on either Start or Stop, will perform that operation against all selected targets (i.e. Start tracing on all selected machines, or stop tracing on all selected machines).
  8. Trace status will be displayed in the Status view window
  9. If Collect trace file after trace is stopped is checked, then the resulting trace file from each selected target is copied to the local machine when stopping the trace. There will be a directory created where CDFControl is being run from, called CDFControl_Remote_Traces, which will store the trace files. Each file will be uniquely named so that they will not overwrite each other. Keep in mind that large trace files will take time to copy over the network
Notes:
Once Start or Stop has been pressed, it cannot be cancelled until the start/stop operation either completes or encounters a failure. This is to avoid corrupting any data that is in progress. You can check the Event Viewer's Application Log on the remote machine as well, for notification of the trace status, such as to see if the trace has been started or stopped successfully. A CDFRemoteSvcMsg.dll will be copied to the remote system's temp directory, so that the Event Viewer will be able to display CDFControl events normally. This file (CDFRemoteSvcMsg.dll) only contains messages for the Event Log, and may be deleted at any time.
  • This feature communicates with the Windows Service Control Manager (SCM) on the target machine(s). The SCM may utilize the ports used by Remote Procedure Call (RPC), although when viewing under a network sniffer it only utilized the NetBIOS Session Service (TCP 139). See this article for more information.
  • It utilizes 2 temp files which are automatically deleted upon each use of this feature. One of the temp files is used for communication with the service control manager of the remote machine, and the other is used to store the trace configuration settings.
  • It utilizes a resource DLL CDFRemoteSvcMsg.dll (see note above)
  • Administrative privileges on the remote machine(s) are required.
  • The resulting trace file (*.etl file) is stored on the remote machine in the system directory (%SystemRoot%), unless the option to collect trace file after trace is stopped is selected - in which case the trace file is deleted from the remote machine.
After trace stopped, CDFControl will collect all ETL file and sysinfo.csv file to local path under target machine folder name. And to avoid file overwrite, a folder with timestamp will be created to store all trace files:

Next generation CDFControl

IMPORTING/EXPORTING REMOTE SERVER LIST

After configuring all the desired remote targets, you can export that list so that it can be imported for future use. This way you don't have to manually enter server names each time when doing remote tracing.

To import a server list, do the following:
  1. Follow the steps above until Step 6 when the Select target machine(s) and enable remote tracing page is opened
  2. Click Import to browse to a previously saved Server List (*.sl) file, which will import the server list into the Selected Target(s) list

To export a server list, do the following:
  1. Follow the steps above until Step 6 when the Select target machine(s) and enable remote tracing page is opened
  2. Click on Export to save the servers from the Selected Target(s) list to a Server List (*.sl) file


STARTUP TRACING

CDFControl has the ability to configure the modules selected in the main window, for startup tracing. It leverages the Citrix Diagnostic Facility COM Server (CdfSvc.exe) service, which can automatically start a CDF trace upon system (or service) startup, if the modules are enabled via the registry. It makes configuring startup tracing alot easier, as manually enabling each module in the registry can be a time consuming task. Follow these steps to enable/disable startup tracing:

Next generation CDFControl

REQUIREMENTS:
To use the Local System account for the CDF COM server service, complete the following steps:
  1. Click Run from the Start menu.
  2. Type services.msc in the dialog box. Click OK.
  3. Select the Citrix Diagnostics Facility COM Server service, right-click and choose Properties.
  4. Click the Log On tab and enable Local System account. Click Apply and OK.
TO ENABLE STARTUP TRACING:
  1. Configure path to the CDF_PersistSession.etl, which will get created as a result of the startup tracing. This is done via the options menu
  2. Place a checkmark next to the desired Citrix trace modules on the main CDFControl window
  3. Click Startup Tracing from the Tools menu
  4. Click Enable
TO DISABLE STARTUP TRACING:
  1. Click Startup Tracing from the Tools menu
  2. Click Disable

See CTX107025 for information on manually configuring startup tracing this way, and also about changing the service load order to ensure that the component being traced, is captured correctly at startup.

CDFControl originally supported the ETW GlobalLogger trace session; however, since no current Citrix products utilize this, it was decided to instead leverage the CdfSvc.exe's capability to capture a startup trace.

For more information on the Global Logger Session, in addition to associated registry keys/values, see:
Global Logger Trace Session


INSERTING TRACE

CDFControl has integrated CDFMarker as a plugin, which provides following feature for you to send a customizable CDF trace statement into a running CDF trace.

After the tracing has been started, you can do the following to insert customizable trace statements into the running CDF trace:
  1. Click on Tools --> Insert Trace--> Set marker text

    Next generation CDFControl

  2. Enter the desired marker text that you want to insert to the running CDF trace

    Next generation CDFControl

  3. Click on Tools --> Insert Trace--> Send trace or tap Ctrl+M from keyboard

    Next generation CDFControl

There are also two other ways to send CDF trace statement:
  • The Command Line, by passing a string to be used in the CDF Trace Statement, such as C:\cdfcontrol.exe -cdfmarker Hello!
  • The Command Line, by piping the output of one process to CDFMarker as input; i.e. at a Command Prompt type:
    C:\echo "Up the Dubs!" | C:\ cdfcontrol.exe -cdfmarker
Note:
For more information on CDFMarker, see CTX124577.


COLUMN HEADER FILTER

CDFControl provides Header selection filters like below, similar to Excel.

Next generation CDFControl

After the trace has been captured, you can do the following to filter desired messages:
  1. Click the down arrow besides column header like "Src".
  2. Select the desired filter item from the dropdown list.

After user did one column selection, users can select other columns based on current filter result. But for one column, only one selection is supported.

The filter content and result will be displayed in status bar to indicate which filter was adopted and how many results were filtered.

Besides, you can also customize trace columns display by showing/hiding some columns as you like.

Next generation CDFControl

To display the desired columns:

  1. Right click the column header.
  2. Click Select Columns.
  3. Select the desired columns you want to display
  4. Click OK.
To hide column:

  1. Right click the header of the column you want to hide.
  2. Click Hide Column.

SELECTION FILTER

When viewing the tracings and if you are interested in some particular tracing such as the same process/Thread/Module/Function/Message, CDFControl adopts the easy filtering as below.

Right Click on the line you want to compare to, and select Filter similar to selected to filter similar rows with the selected line's Process ID/Thread ID/Session ID/Module/Src/Function/Message.

You can also hide some particular tracings by Process/Thread/Session/Module/Src/Function/Message.

Next generation CDFControl

HIGHLIGHT

Sometimes, when analyzing CDF tracing, you may want to highlight some rows which can distinguish from other rows.

Next generation CDFControl

Simply select one row or more rows, and click on Filter--> Highlight or right click to pop up Menu to select the highlight colors.

Next generation CDFControl


Multiple Rules Filter

MULTIPLE RULE FILTER

Basic column filter can only support some basic filtering operations. And if you wants to do some complex filtering work, CDFControl provides rule based filtering and you can customize your own rules and save to CSV format by "File->Save Viewer Output".

After the trace has been parsed, you can do the following to filter desired message:
  1. Click on Filter--> Filter...

    Next generation CDFControl

  2. Select the desired filter, and click Add

    Next generation CDFControl

  3. Select the desired filter, and click Add (multiple rules can be added)
  4. The default logic between the rules is AND. If you want to change the logic, you can click on Apply Logic Filter to edit the logic

    Next generation CDFControl

  5. Click on Apply
  6. The desired message will be filtered out and displayed on UI

RESET FILTER

  • Click Filter--> Reset Filter to reset filtering to default settings

LOAD FILTER

  • Click Filter--> Load Filter to load a former saved configuration file

SAVE FILTER

  • Click Filter--> Save Filter to save current setting to a configuration file


PARSING FILTER

CDFControl also supports filtering by Regular Expression in Real-Time Tracing and ETL parsing. It will listen to specified CDF module trace messages and triggers an event based on a provided Regular Expression pattern match.

When parsing a trace, you can do the following to filter desired message:
  1. Click on Filter--> Parsing Filter

    Next generation CDFControl

  2. Click to enable the checkbox for Enable filtering for parsing trace

    Next generation CDFControl

  3. Type in regular expression in Message filter string in regex expression field, and click Verify
  4. Type in test string in Test string for regular expression field, and click Test
  5. Click OK, and then start parsing/tracing
  6. Only eligible message will be shown on the viewer

TIME FILTER

  1. Click to enable the check box for Enable time filter when parsing trace files and click OK

    Next generation CDFControl

  2. Choose trace file(s) to parse
  3. Change the start time and end time

    Next generation CDFControl

  4. Only the trace messages between the time period will be showed in the panel.

PARSING FILTER SETTINGS

STOP TRACING UPON THE FOLLOWING NUMBER OF OCCURENCES
Enable this option to stop the parsing/tracing after the eligible events occur for specified number of times.
ONLY DISPLAYED FILTERED EVENTS
If this option is checked, only eligible events will be shown on the viewer.
HIDE FILTERED EVENTS
If this option is checked, all the other events except for the eligible events will be shown on the viewer.
Enable time filter when parsing trace filters
If this options is checked, trace messages can be filtered by start time and stop time.


COMMAND LINE SUPPORT

Next generation CDFControl

CDFControl can be scripted, and configured to run via command line. Use the syntax provided in the screenshot above for command line usage. This information can be displayed by running CDFControl /? via command line.If user does not specify parameters, CDFControl will use the configurations from UI by default.

Examples:

Starting a trace:
 CDFControl -start -guids c:\guids.ctl

The guids.ctl file is simply a text file, containing the GUID of each provider to trace. Place each GUID in its own line like below:

Next generation CDFControl

Parsing a trace:
 CDFControl -decode -tmf c:\LocalTmfCache\ -o c:\ParsedTrace.csv

The output file must be a .csv file.

Stopping a trace:
 CDFControl -stop


Vista UAC

CDFControl with Vista UAC

CDFControl requires full administrative privileges for all functionality to work correctly. When run on Microsoft Windows Vista with UAC enabled as a user with Administrative privileges, CDFControl will display a shield icon to notify the user that the task requires privilege elevation. Currently, the only task that requires this is trace capturing.

Next generation CDFControl

If the user chooses to perform other tasks, such as trace viewing, importing/exporting trace settings etc. Then elevating privileges is not necessary. However, if the user chooses to start a trace, then the Windows UAC elevation prompt will appear and the user has to click Allow to proceed?

Next generation CDFControl

In order to achieve elevated privileges with user consent, CDFControl will spawn a new instance of itself with full (unfiltered) Administrative rights, and it will terminate the original instance. The Start Tracing button will now appear without the shield icon, and the Administrator will be able to start a trace.

Next generation CDFControl

Why does it say "An unidentified program wants access to your computer" ?

This is because CDFControl was not signed with a code signing certificate. CDFControl will still run and function as designed on Microsoft Windows Vista, despite this notice.


Report Feedback

REPORTING FEEDBACK

CDFControl Feedback

Thank you for using CDFControl. We appreciate your feedback!


EVENT FILTERING

To access the Event Filter dialog:
Click Tools --> Event Filter

Use this option to specify an event filter string, that can be used to easily find an event during parsing. For example, if you specify a string in the Event Filter and then choose to Parse Trace - the trace will stop parsing when the Event Filter criteria is met.

Next generation CDFControl

You can configure a program or script to run when the event filter criteria is met. Simply specify the path to the desired program or script (with necessary command line parameters), and it will be executed upon filter match.

This can be useful to obtain a userdump or trigger an automated BSOD upon a certain CDF trace event.
To enable event filtering:
  1. Check Enable event filtering
  2. Enter a filter string under Filter string:
  3. Enter the number of filter match occurrences that must happen before parsing stops, under
    stop parsing upon the following number of occurrences:
  4. If you would like to limit the number of events preceding the filtered event, check Show only [] events preceding last occurrence
  5. If you would like to execute a custom program or script, when the filter match occurs, then check Execute the following program or script when filter criteria met: and enter a command line to execute
  6. Click Save to save the settings.
The next trace viewed will have the filter applied. Clear the checkbox from step 1 to disable Event Filtering.


Importing and Exporting Settings

IMPORTING AND EXPORTING TRACE SETTINGS

IMPORT FROM XML
Use this option to specify an XML trace setting file, whose settings will be imported into CDFControl.

EXPORT TO XML
Use this option to capture the currently configured settings of CDFControl, to an XML template file. These settings contain the selected trace providers along with the associated trace capture settings, such as max log size, flags, level, and log file mode. This file can be imported into the Citrix Access Management Console (AMC), although there would be 2 unsupported log file modes:

  • Multiple Sequential (newfile)
  • Append

These 2 modes are not present in the current AMC, so if either of these settings are exported from CDFControl, they will need to be reset if imported into the AMC.


Performance Collection

PERFORMANCE DATA COLLECTION

When troubleshooting a critical server issue, such as a problem on the XenApp Farm's Zone Data Collector (ZDC), performance data is often extremely useful to help identify the problem. Performance data can also help identify an underlying system problem such as excessive Terminal Services Session Paged Pool usage.

CDFControl provides the ability to capture a performance data log in comma separated values format (CSV), along with the capture of a CDF trace. The peformance log capture begins when the CDF trace is started, and stopped when the CDF trace is stopped. The resulting file is stored in the same location as the CDF trace file.

Click on Collect Perf Data from the Tools menu in CDFControl, to bring up the performance data dialog

Next generation CDFControl

To enable performance data collection, which causes a performance data log to be generated along with each CDF trace captured:
  1. First select the desired performance counters to collect. Click on Browse Counters to browse for available performance counters on the system.
  2. Added counters will be displayed in the Selected counters list box (like in the screenshot above).
  3. To tell CDFControl to start collecting perf data with every CDF trace, ensure that Collect selected performance counter data with each trace is checked.
  4. Likewise, ensure it is unchecked to stop collecting perf data when capturing CDF traces.
NOTE:
With this enabled, each time a CDF trace capture is started, a performance log file (CSV format) will also get generated along with the CDF trace. Ensure that this is disabled if this is not desired.