Citrix Diagnostic Toolkit x64 – (C.D.T)

Description

The Citrix Diagnostics Toolkit is a rapid deployment platform that delivers a suite of tools and automation options in an easy to use structured format that closely resembles the look and feel of any standard Windows application, even though each tool is an independent standalone application. 

The easy to use built in menus and shortcuts allow you to quickly and effectively configure multi-vector data collection and integrate third party tools for more robust and comprehensive debugging sessions.

Important Notes about This Release

• Added Support for XenApp & XenDesktop 7.x products. Upgraded trace providers, performance counters and control files for multi-vector tracing.

• Upgraded Receiver & VDA trace providers, performance counters and control files for multi-vector tracing.

• Default Trace file sizes have been reduced from 1 GB to 500MB for faster parsing at time of analysis.

• Several tools have been updated, added and/or removed. Please see the: Citrix Tools included list below for more info.

• Internet access check relabeled to TCP download test.

• All C.D.T. shortcuts are advertised. Use run line and type shortcut name for faster access.

• Enhanced intelligent shortcuts for 3^rd party tools. TCP downloads are now faster and more user friendly with no more failed downloads.

 

Citrix Tools Included

Based on options you select during the C.D.T. installation wizard. The tools most commonly used for that product will be deployed.

Redistributable & Downloadable Tools:

Prerequisites

No software prerequisites are needed to install this toolkit. No reboot is required. Some tools included in this toolkit may have prerequisites. Please reference each tools readme for more information.

Why does C.D.T. use an Installer

C.D.T. leverages an installer for the purpose of creating a file and folder structure and extracting common Citrix Support tools into this structure. This removes the burden from our customers of deciding where to download and extract tools. Trace data will always be saved in the \CitrixDiagnostics\DATA directory and completed trace packages will always be located in the \CitrixDiagnostics\Upload directory. This allows C.D.T. to perform clean up sequences at the end of each capture session, preventing file sprawl during data collection. All 3^rd party tools downloaded and integrated using C.D.T.’s intelligent shortcuts will always be located in \CitrixDiagnostics\Tools. Leveraging an installer, gives our customers the ability to cleanly remove C.D.T. and everything contained within the C.D.T. file structure at the end of a support engagement. For more information, see the Data Modified by C.D.T. section.

Installing (C.D.T.)

• Download the MSI using link provided at top of this document.
• Remote installation from a centralized network share is supported.
• Right click the CitrixDiagnosticsToolkit(x64).msi and Run as Administrator

You must accept EULA to begin installation.

 

 

• Next screen will display trace options selector for various products.  Chose the appropriate check box so the correct tools and files are deployed.

• NOTE – For PVS tracing option SKIP to next screen.

 

Next is the install folder. The installer is configured to detect %SystemDrive% and will install in the root of the System Drive. The system drive should appear by default and is the drive where windows\system32 lives.

Folder nesting is NOT SUPPORTED by design. DO NOT nest the install location. Nesting will cause some or all of the Toolkit automation modules to fail.

 

If your system drive letter is not detected correctly, change the drive letter only. For example, if your system drive is “H” then you may enter H:\ as the install destination. (See screenshots below)

 

Select NEXT two more times to confirm installation. Install should be quick with NO Reboot Required.

Start Menu Integration

Tracing Options and Setup

Trace file sizes and settings are as follows by default and cannot be changed if started using the C.D.T. default shortcuts located in the Start menu.

CDF trace will be a 500Mb .etl file max configured for circular trace.

Performance counter log file will be 500MB .blg file max Configured for circular trace. Wireshark trace will be (5) 100mb files configured in a ring buffer where when the fifth file is full the first file is overwritten with new data.

XenApp Tracing Options and Setup

By default, when the “Tracing for XenApp” option is selected during install. The trace categories below will be captured. See the Customizing your CDF tracing section below for instructions on how to select difrent modules for XenApp CDF tracing.

XenDesktop Tracing Options and Setup

By default, when the “XenDesktop Tracing” option is selected during install. A .ctl file with all default and optional trace modules for XenDesktop DDC’s is created in \CitrixDiagnostics\XenDesktop Tools\ folder. See the Customizing your CDF tracing section below for instructions on how to select difrent modules for XenDesktop CDF tracing.

Receiver Tracing Options and Setup

By default, when the “Citrix Receiver Tracing” option is selected during install. A .ctl file with all default and optional trace modules for all reciever versions 12.x through 4.1 is created in \CitrixDiagnostics\Receiver\ folder. The steps outlined in CTX124934 are not needed when tracing with this toolkit. See the Customizing your CDF tracing section for instructions on how to select difrent modules for Receiver CDF tracing.

The Packager

The packager process will run automatically after all traces are stopped and performs the following operations:

• Exports Windows Application & System Event logs

• Captures a Qwinsta command output to a .txt file. (XenApp only)

• Captures a Routeprint command output to a .txt file

• Captures a SystemInfo command output to a .txt file

• Captures a Cpatch command output to a .txt file (XenApp only)

• Creates an .nfo file leveraging MSinfo32.exe (useful in PVS related cases)

• The packager then compresses the contents of the Data folder and clears the contents of the Data folder to prevent bloating and disk space over usage.

• The Upload folder will open once packaging is complete and display a zip file with all your data inside giving you’re the opportunity to remove any files or scrub the contents prior to sending to Citrix Support for analysis.

• Lastly a browser window pointing to the Auto Support (TaaS) site will be launched for your convenience and speedy upload of the data to Citrix Support.

The TaaS site auto launch feature can be disabled by using the following command:

Disabling this feature is useful for Advanced Tracing scenarios such as using Scheduled Tasks or triggering the traces by using Windows Events.

To re-enable TAAS site auto-launch simply use the following comand:

NOTE: Customers running Symantec Endpoint Protection or other antivirus with real-time scanning enabled may experience a delay during the “Packaging” sequence (manual or automatic). Packaging will NOT fail but may take 7-10min versus 2-3 min while building .NFO file.

Resolution – Stop SEP or real-time scan service temporarily during packaging sequence. Once packing is complete re-start SEP or real-time scanning service.

Customizing your CDF tracing

To modify CDF trace providers used by default in C.D.T. automated tracing. Use CDFControl, which is installed by default, and located under in START > All Programs > Citrix Diagnostics > Tools > CDFControl. Follow the numbered steps below to configure the desired trace parameters.

1. In CDF control, select the desired trace category or combination of categories. Example: to trace Printing related issues, we would want to select the Printing Category.

2. Go to the Tools menu in CDF Control and select “Create CTL File”.

3. When the “Save As” dialog box appears. Browse to folder that represents the product you selected during install and you will find a .ctl file in one of the paths below.

3.1. \CitrixDiagnostics\Citrix_Tracing_XenApp\XenApp.ctl

3.2. \CitrixDiagnostics\Receiver\Rec_VDA.ctl

3.3. \CitrixDiagnostics\XenDesktop Tools\XenDesktop.ctl

4. Save your new .ctl file that contains the modules you specified by overwriting the existing .ctl – (DO NOT change the name of the .ctl file. If you name the file anyother name the tracing will not initialize.)

5. Exit CDF Control.

6. Return to the windows START menu and use the C.D.T. “Start Tracing” shortcut to beging tracing with your new CTL file and get the benefit of C.D.T. functionality.

Security Permissions required by C.D.T.

Local Administrator rights are recommended for all trace options and tools to be executed correctly. On systems with UAC enabled. Leverage the “RUN AS” option in windows to elevate the privileges on any of the C.D.T. shortcuts.

Data Modified by C.D.T.

This toolkit creates a file structure environment where all programs, automation scripts, and control files are installed. Additionally, if the included download menu is used to retrieve Sysinternals tools they will be placed in this file structure for ease of use. Shortcuts are created in the “START” menu just like a standard Windows application. For more details please see key points below.

• Parent directory = %SystemDrive%\CitrixDiagnostics contains all program files and Sub-directories.

• Data files will be temporarily stored in \CitrixDiagnostics\data until the built-in packager runs, at which point the data will be compressed and moved to \CitrixDiagnostics\upload for sending to Citrix Support via TaaS.

• For XenApp 6.0 and 6.5 only the C.D.T. installer will detect the version of XenApp and deploy the corresponding version of lbdiag.exe (XenApp load balancing diagnostic tool). Lbdiag.exe will be copied to \system32 directory to allow execution from a command window opened in the \CitrixDiagnostics\data path. Use the Lbdiag shortcut provided in START menu or type Lbdiag in the RUN line after install C.D.T.

• No system registry values are added or modified by C.D.T.

• A CLSID registry entry for C.D.T. and a window installer cache entry are created to ensure a clean uninstall.

• A Windows installer database entry is added for clean removal of C.D.T. using “Add Remove Programs”

• When using the “Intelligent shortcuts” from the START menu the selected tools will be fetched directly from the Technet or Codeplex website and unpacked in the \CitrixDiagnostics\tools directory for use by thecustomer or a support engineer.

 

3rd Party Tool Integration and Download

C.D.T. uses shortcuts in the START menu to launch or downloaded 3^rd party apps or tools. The intelligent shortcuts are designed to find the downloaded files and execute specific routines that optimize it for use with C.D.T.

On a first launch attempt of most 3^rd party tools. C.D.T. may have to perform a TCP Download of the tool before launching. Some 3^rd party tools are included with C.D.T. and will be installed on launched when you click on the provided shortcut.

If a 3^rd party tool must be downloaded. C.D.T. performs a TCP Download test prior to retrieving the requested tool.

DO NOT EXTRACT THE DOWNLOADED FILE OR MODIFY IT IN ANY WAY.

Fig. 16-2

To install the latest version of Wire Shark simply click the shortcut in the tools sub menu.

NOTE: The version of wireshark included with the Citrix Diagnostic Toolkit contains two important fixes that are required for seamless data collection.

If Wire Shark is already installed C.D.T. will detect and prompt the user to remove.  Please install the version provided by the toolkit.

To create Data Collector sets in Performance Monitor, simply click on the provided shortcut in the tools sub menu. Depending on the option selected during install the shortcut will appear different in the START menu.

NOTE: Perfmon counters captured will be specific to the product type you selected at time of install.

NOTE: Wireshark and Perfmon are NOT required in all scenarios. These options have been included for your convenience. If you choose not to configure these options, the default trace operation will be CDF only.

NOTE: Procdump ONLY:

• Once downloaded a help file is created for an easy to use command reference.

• As part of the download of Procdump. Ready to use .cmd file templates are created and placed in \CitrixDiagnostics\Tools\Procdump directory. These templates save you scripting time that you would need for combining or automating usage of Procdump with other tools or advanced dump captures of an offending process.

• Editing instructions are included inside the files for your convenience.

 

A copy of Procdump is placed in the \System32 directory to allow execution without the need for specifying the full path to executable.

It is recommended that you use the provided START menu shortcut that will open a command window in the \CitrixDiagnostics\DATA directory for your convenience. (see figure below)

How to Use (C.D.T.)

Check out the C.D.T. How to series on Citrix TV and watch Frank Marzullo walk through the following key points:

• Installing the toolkit

• 3^rd party tool integration

• Tools overview

• Multi vector tracing and data collection

• Customizing CDF traces

• Uninstalling the toolkit

To better serve our customers, we recommend using this toolkit with guidance or assistance from Citrix Support Teams. The diagnostic data collected will be used to determine the root cause of the problem report or symptom.

Begin by navigating Start > All Programs > Citrix Diagnostics > and click the Start <Product> Tracing shortcut.

Note: A command window will appear that will display packet captures being executed by Wire Shark. Do Not Close This Window, or it will interupt the WireShark capture. (Scheduled Tracing or triggered tracing using windows events will work as expected because they are executed in a different context.)

To confirm data collection, use the Desktop shortcut and browse to the “data” folder using windows explorer.

If you chose to configure Perfmon counters and installed the provided version of Wireshark. Then you will see 3 files in the \CitrixDiagnostics\Data folder appear when you click on Start <Product> Tracing from the Start menu.

To stop tracing, navigate to Start > All Programs > Citrix Diagnostics > and click on Stop <Product> Tracing shortcut.

This will stop all running traces triggered by C.D.T. and call a routine known as the Packager.

How to Undo the Changes Made by C.D.T.

No intrusive changes are made by this toolkit. To remove or uninstall see the next section below.

Uninstalling C.D.T.

NOTE – if you installed Wireshark. The C.D.T. Uninstall will not remove Wireshark because it was a separate install you selected. Use add remove programs applet for Wireshark to remove.

Citrix Diagnostic Toolkit has 2 uninstall methods. No reboot is required. Both methods will perform a “complete” uninstall that will remove all files and directories including data files and 3^rd party tools downloaded using C.D.T. built in menus.

1. Add Remove Programs applet in windows control panel.

 

2. There is a convenient Citrix Diagnostics Uninstaller shortcut included in the Start menu

NOTE - On Windows 2003 systems that do not have the WMI Windows Installer Provider feature installed, using the “Citrix Diagnostics Uninstaller” SHORTCUT from the START menu may not remove all toolkit components and/or menu shortcuts. This shortcut executes a WMIC script that removes ALL files, folders, and toolkit components including START menu items.

ONLY Windows 2003 systems are affected by this issue. To overcome this issue, add the WMI Windows Installer Provider feature via Add Windows Components wizard (no reboot required).

This problem does not affect Windows 2008 / Windows 2008R2 systems as the required feature is installed by default.

Optional Workaround

Use Add/Remove Programs applet instead of using START menu Shortcut and select uninstall by right clicking Citrix Diagnostics Toolkit from the program list.

Contact Information

Contact supporttools@citrix.com to report any bugs or provide feedback for this tool.

Disclaimer

These software applications are provided to you as is with no representations, warranties or conditions of any kind. You may use and distribute it at your own risk. CITRIX DISCLAIMS ALL WARRANTIES WHATSOEVER, EXPRESS, IMPLIED, WRITTEN, ORAL OR STATUTORY, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NONINFRINGEMENT. Without limiting the generality of the foregoing, you acknowledge and agree that (a) the software application may exhibit errors, design flaws or other problems, possibly resulting in loss of data or damage to property; (b) it may not be possible to make the software application fully functional; and (c) Citrix may, without notice or liability to you, cease to make available the current version and/or any future versions of the software application. In no event should the code be used to support of ultra-hazardous activities, including but not limited to life support or blasting activities. NEITHER CITRIX NOR ITS AFFILIATES OR AGENTS WILL BE LIABLE, UNDER BREACH OF CONTRACT OR ANY OTHER THEORY OF LIABILITY, FOR ANY DAMAGES WHATSOEVER ARISING FROM USE OF THE SOFTWARE APPLICATION, INCLUDING WITHOUT LIMITATION DIRECT, SPECIAL, INCIDENTAL, PUNITIVE, CONSEQUENTIAL OR OTHER DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. You agree to indemnify and defend Citrix against any and all claims arising from your use, modification or distribution of the code.