Connection Quality Indicator

Created: Feb 15, 2017

Updated: April 08, 2020

Please provide feedback or enhancement requests at https://podio.com/webforms/17047561/1146185. 

Description

The Connection Quality Indicator (CQI) is a tool that notifies users of changes to user experience. It serves the following purposes:

• Assist users by pointing out issues that degrade the user experience. 
• Provide real-time data for sophisticated users to find causes for lags in screen refreshes.  
• Reduce the number of calls to help desks related to user experience issues.

What's New in 20.3.0.38

• Added support for Microsoft Windows Server 2019. 
  

Changes in Earlier Versions

• Reduced the tool’s CPU usage.
  
• Combined all Citrix.CQI.csv files generated per session into one single Citrix.CQI.Data.csv file. 
  
• Moved the combined Citrix.CQI.Data.csv file from user temp folders to the LocalService temp folder.
• Reduced the tool’s memory usage.
  
• Refactored notification UI elements.
  
• Added the writing of busy state events to Windows Events. 
  
• Addressed the blurry icon issue on some high-DPI Mac displays.
• Fixed an issue that GPO settings could not control notifications.
• Added support for uploading CEIP data (application insights) to Google Analytics.
• Added support for the tool's running on TLS/SSL-enabled VDAs.
• Added support for configuring the duration of notifications.
• Added support for uploading CEIP data over TLS 1.2. 
• Added a string to show the protocol type in the options panel that appears when you click the field, upward triangle symbol in the upper right corner of a CQI notification.
• Provided logging data output as a CSV file. 
• Decreased logging frequency to log only when the connection status changes.
• Added logging of busy connections and the causes: playing rich content; high CPU load; printing; file redirection.
• Updated content of idle state message.
• Limited popup notifications to appear only when connection status is poor.
• Introduced indication for VDA idle state.
• Introduced indication for weak performance and for poor performance due to playing rich content.
• Introduced indication for weak performance and for poor performance due to high CPU load.
• Introduced indication for weak performance and for poor performance due to printing.
• Introduced indication for weak performance and for poor performance due to file redirection.
• Renamed ICA Rdtrp to ICA RTT.
• Changed default ICA Round Trip collection frequency to 15 seconds.
• Added more language support:
  • Added support for zh-TW, ko-KR, ru-RU
  • Added support for de-DE, es-ES, fr-FR, ja-JP, zh-CN installer UI and GPO settings
• Improved Event Logs by using separate EventIDs for different levels of network connections.
• Introduced a warning message if disk space is less than 100 MB.
• Added the Customer Experience Improvement Program (CEIP) feature. For more information, see About the Citrix Customer Experience Improvement Program (CEIP)
• Added GPO settings.
• Allowed you to customize the default notification position by using the CQI GPO.
• Allowed you to disable audible notifications by using the CQI GPO.
• Addressed an issue that might cause the CQI not to work when Seamless Flag is set to 0x20.
• Allowed you to disable notifications by using the CQI GPO.
• Allowed you to customize notification messages by using the CQI GPO.
• Removed the word "Servers" from Weak and Poor notification messages.
• Retained the user preference for notification window position.
• Provided the bandwidth threshold setting in the CQI GPO.
• Renamed the Bandwidth counter to Available Bandwidth in the Real time data section of the option panel.
• Improved logging.
• Addressed an issue that at times, might cause the tool to exit unexpectedly on session startup.
• Addressed an issue that prevented audible alerts from working on a Server VDA.
• Addressed an issue that might cause the tool to display an incorrect notification after reconnecting to a session.

Supported Operating Systems

• Microsoft Windows 10
• Microsoft Windows 8.1
• Microsoft Windows 7 with Service Pack 1
• Microsoft Windows Server 2016
• Microsoft Windows Server 2012 R2
• Microsoft Windows Server 2008 R2 with Service Pack 1
• Microsoft Windows Server 2019
  

Supported Virtual Delivery Agents

• Server OS Virtual Delivery Agent 7.6.300 and later
• Desktop OS Virtual Delivery Agent 7.6.300 and later

Prerequisites

• Microsoft .NET Framework 4.5.1
• Citrix Virtual Delivery Agent 7.6.300 or later must be installed.
• To install or uninstall the tool, the user account must be a member of the local Administrators group on target machines.
• Installing the tool over an ICA session is not supported but you can install the tool through a remote desktop session by using an administrator account.
• The installer program complies with Microsoft User Account Control (UAC). If UAC is enabled, you must run the installer program in elevated mode. That is, with administrative privileges enabled. For more information about UAC, see Microsoft TechNet or visit the Microsoft website and search on keyword UAC.

Installing the Connection Quality Indicator

Install the Connection Quality Indicator on a Virtual Delivery Agent (VDA). You can install it by using the MSI package or by using the MSIEXEC command.

Installation by using the MSI package

1. Locate the local copy of the MSI package.

2. Double-click the MSI package to launch the CQI setup wizard.

3. The setup wizard window appears. Review and accept the License Agreement.

4. Click Install.

The setup wizard displays the installation progress.

5. After the wizard completes, click Finish.

The Citrix Customer Experience Improvement Program (CEIP) is enabled by default. To disable the program, clear the Participate in the Customer Experience Improvement Program check box.

The CQI has now been installed on the Virtual Delivery Agent and is ready for use.

Installation by using the MSIEXEC command 

1. Open the Windows Command Prompt and navigate to the local copy of the MSI package.

2. Enter the MSIEXEC /i “CitrixCQI.msi” command  to launch CQI setup wizard.

3. The setup wizard window appears. Review and accept the License Agreement.

4. Click Install.

 The setup wizard displays the installation progress.

5. After the wizard completes, click Finish.

To disable the Citrix Customer Experience Improvement Program(CEIP), Use the “DISABLE_CEIP=1” option with MSIEXEC.

The CQI has now been installed on the Virtual Delivery Agent and is ready for use.

Uninstalling the Connection Quality Indicator

You can uninstall the tool by using Control Panel or by using the MSIEXEC command.

Uninstall by using Control Panel

1. Open the windows Start menu and select Control Panel.

2. Under Programs, click uninstall a program.

3. Locate the Connection Quality Indicator

2. Right-click the program and select Uninstall. Follow the prompts to complete the uninstall.

   To repair a Connection Quality Indicator installation, select the program and click Repair at the top of the program list.

Uninstall by using the MSIEXEC command

1.  Open the Windows Command Prompt and navigate to the local copy of the MSI package.

2.  Enter the MSIEXEC /x “CitrixCQI.msi” command to launch the CQI setup wizard.

3.  The setup wizard appears. Click Next to continue.

4.   Click Remove to begin uninstalling the CQI.

5.  The wizard prompts for confirmation. Click Remove to continue.

The setup wizard displays the uninstall progress.

6.  After the wizard completes, click Finish.

For more information on available parameters, see Command-Line Options.

Group Policy Configuration

Citrix recommends that you use the Windows Group Policy editor to configure the CQI. The CQI includes administrative template files (CitrixCQI.admx and CitrixCQI.adml) in its installation folder. 

For the location of each group policy template file, see the following table.

Note: You can use the .admx and .adml template files to configure the local GPO and domain-based GPOs. For information about managing the .admx files, see Microsoft MSDN article https://msdn.microsoft.com/en-us/library/bb530196.aspx#manageadmxfiles_topic2.

Adding Policy Template Files to the Local GPO

1. After installing the Connection Quality Indicator, copy the .admx and .adml group policy template files.

Copy the .admx files: 

From: <Installation folder>\Configuration\CitrixCQI.admx

To: %systemroot%\policyDefinitions

From: <Installation folder>\Configuration\CitrixBase.admx

To: %systemroot%\policyDefinitions

Copy the .adml files: 

From: <Installation folder>\Configuration\[MUIculture]CitrixCQI.adml

To: %systemroot%\policyDefinitions\[MUIculture]

From : <Installation folder>\Configuration\[MUIculture]\CitrixBase.adml

To: %systemroot%\policyDefinitions\[MUIculture]

 Note: The CQI template files are available on the local GPO in the Administrative Templates > Citrix Components > Virtual Desktop Agent > CQI folder only when you have added the CitrixBase.admx and CitrixBase.adml files to the policyDefinitions folder.

2.  Use the CQI group policy template files to enable or disable the CQI, to do notification display settings (for example, customize notification messages or disable notifications), and to conduct threshold settings.

Note:

• You can also perform user-level policy settings for the CQI. Computer configuration, if present, always takes precedence.
• Starting  with Version 19.9.0.33, the connection threshold settings are available only in the Computer Configuration section.

Launching CQI on Session Startup

The CQI installer modifies the system to launch the tool automatically on session startup. Depending on the type of VDA, the method of automatically launching the tool can vary:

For Server OS VDAs, append the path to the CQI’s  launcher.cmd script to the AppSetup registry value. The registry entry is located at:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon

For Desktop OS VDAs, append the path to the CQI’s executable to the Run key. The Run key is located at:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run

To ensure that sessions are logged off properly, append the CQI’s executable name to the LogoffCheckSysModules registry value. The LogoffCheckSysModules registry entry is located at:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Citrix\wfshell\TWI

If the CQI cannot be launched for published apps hosted on Desktop OS VDAs, find a solution in

https://support.citrix.com/article/CTX127874

Using the Connection Quality Indicator

The CQI launches on session startup and continues to run for the life of the session. It notifies the user of changes to network performance and status.

There are several types of notifications that a user can see while the tool is running:

Collecting Data state:

Poor and Weak states:

Busy states:

Excellent state:

Idle state:

User interaction with CQI for published desktops and apps are similar, with the following exceptions:

When using a published desktop, CQI notifications are displayed in the notification area and as standard notifications.

For published apps, CQI notifications appear in the lower right corner of the apps. If more than one published app is in use within the same session, only the foreground app displays notifications.

The option panel, which you can access by clicking the filled, upward triangle symbol in the upper right corner of a CQI notification, can be used to snooze notifications for a predetermined amount of time. When you snooze a notification, the time you choose appears in green. You can also access the latest notification by using the hotkey combination Ctrl+Alt+H for published apps. Notifications you access this way remain visible until you dismiss them explicitly.

Option panel

Notification area

Notifications remain visible for a predefined interval when a degraded user experience is present for a prolonged period of time. Short-lived degraded user experiences, though detected by the tool, do not trigger notifications. This behavior is by design and prevents the tool from overnotifying users.

How CQI Uses Counters

The CQI uses counters to monitor the connection quality between an endpoint and the VDA. Each counter contains a low and a high threshold that the tool uses to determine which type of notification to display. The default values of the thresholds are defined in the <Installation folder>\Configuration\[MUIculture]CitrixCQI.adml file. The CQI shows the following counters in the “Real time data” section of the option panel.

• ICA RTT – Indicates the time that elapses between the moment you press a key and the moment the keypress becomes visible at the endpoint. 

• ICA Latency – Indicates the time a data packet takes to get from the client-side Winstation Driver (WD) to the server-side WD and back.

Note: ICA RTT is different from network latency.  

Network latency is the time a data packet takes to get from the source NIC to the destination NIC and back. Network latency contributes to ICA RTT, but ICA RTT is also affected by other factors such as application performance, system performance, printing activity, media rendering, and large file redirection.

ICA RTT affects user experience rather than network connection quality.

Session Metrics in Citrix.CQI.Data.csv

CQI collects metrics of all sessions and saves them to Citrix.CQI.Data.csv, which is present in the %SystemRoot%\ServiceProfiles\LocalService\AppData\Local\Temp\Citrix\CQI\Logs\CSV folder.

Logging

The CQI uses two logging options - a plain text file maintained per user session, and a Windows Event log shared across all user sessions running on the VDA.

The plain text log file, Citrix.CQI.log, is stored in the %temp%\Citrix\CQI folder. The CQI also maintains a single archived log file, Citrix.CQI.{YYYY-MM-DD_HH-MM-SS}.0.log, in the same folder. The log file size limit is 5 MB.

The same logging information is written to the Windows Event log. There are two event log channels, Admin and Debug. To see the Debug channel, ensure that the “Show Analytic and Debug Logs” option is enabled.

The CQI logs can be found in the Application and Services Logs\Citrix\VDA\CQI folder within the Event Viewer:

Event logs combine messages from all user sessions on a VDA.

      • The Admin channel contains only critical messages, errors, and warnings.

      • The Debug channel contains additional information to the Admin channel..

Event log records are categorized by level and provided with separate IDs.

How to show more traces in Citrix.CQI.log

The CQI log file, Citrix.CQI.log, does not show all traces by default. To show more traces, find the Citrix.CQI.exe.config configuration file at C:\Program Files (x86)\Citrix\Connection Quality Indicator and change the “LogToFileLevel” key value from 1 to 16. Only those traces whose priorities are lower than or equal to the configured key value can be output to Citrix.CQI.log.

Known Issues

The following table describes the various failure scenarios and the recommended corrective actions.

Contact Information

Questions? Concerns? Comments? Send feedback to https://podio.com/webforms/17047561/1146185.

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.