Citrix Insight Services
Citrix Insight Services (CIS) is a Citrix platform for instrumentation, telemetry, and business insight generation. Its instrumentation and telemetry capabilities enable technical users (customers, partners, and engineers) to self-diagnose and fix problems and optimize their environments. For details and the latest information about CIS and how it works, see https://cis.citrix.com (Citrix account credentials required).
The features offered by Citrix Insight Services continue to grow and evolve, and now form an integral part of Citrix Smart Tools. Citrix Smart Tools enables you to automate deployment tasks, health checks, and power management. For information about the technologies, see the Citrix Smart Tools documentation.
All information uploaded to Citrix is used for troubleshooting and diagnostic purposes, as well as improving the quality, reliability, and performance of products, subject to:
- Citrix Insight Services Policy at https://cis.citrix.com/legal
- Citrix Privacy Policy at https://www.citrix.com/about/legal/privacy.html
This XenApp and XenDesktop release supports the following tools and technologies.
- XenApp and XenDesktop install and upgrade analytics
- Citrix Customer Experience Improvement Program
- Citrix Smart Tools
- Citrix Call Home (part of Citrix Smart Tools)
- Citrix Scout
Install and upgrade analytics
When you use the full-product installer to deploy or upgrade XenApp or XenDesktop components, anonymous information about the installation process is gathered and stored on the machine where you are installing/upgrading the component. This data is used to help Citrix improve its customers’ installation experiences.
The information is stored locally under %ProgramData%\Citrix\CTQs.
Automatic upload of this data is enabled by default in both the graphical and command line interfaces of the full-product installer.
- You can change the default value in a registry setting. If you change the registry setting before installing/upgrading, that value will be used when you use the full-product installer.
- You can override the default setting if you install/upgrade with the command line interface by specifying an option with the command.
Registry setting that controls automatic upload of install/upgrade analytics (default = 1):
Location: HKLM:\Software\Citrix\MetaInstall Name: SendExperienceMetrics Value: 0 = disabled, 1 = enabled
Using PowerShell, the following cmdlet disables automatic upload of install/upgrade analytics:
New-ItemProperty -Path HKLM:\SOFTWARE\Citrix\MetaInstall -Name SendExperienceMetrics -PropertyType DWORD -Value 0
To disable automatic uploads with the XenDesktopServerSetup.exe or XenDesktopVDASetup.exe command, include the /disableexperiencemetrics option.
To enable automatic uploads with the XenDesktopServerSetup.exe or XenDesktopVDASetup.exe command, include the /sendexperiencemetrics option.
Citrix Customer Experience Improvement Program (CEIP)
When you participate in the Citrix Customer Experience Improvement Program (CEIP), anonymous statistics and usage information are sent to Citrix to help Citrix improve the quality and performance of Citrix products. For more information, see https://more.citrix.com/XD-CEIP.
Enrollment during Site creation or upgrade
You are automatically enrolled in CEIP when you create a XenApp or XenDesktop Site (after you install the first Delivery Controller). The first upload of data occurs approximately seven days after you create the Site. You can stop your participation at any time after creating the Site; select the Configuration node in the Studio navigation pane (Product Support tab) and follow the guidance.
When you upgrade a XenApp or XenDesktop deployment:
- If you upgrade from a version that did not support CEIP, you are asked if you want to participate.
- If you upgrade from a version that supported CEIP, and participation was enabled, CEIP will be enabled in the upgraded Site.
- If you upgrade from a version that supported CEIP, and participation was disabled, CEIP will be disabled in the upgraded Site.
- If you upgrade form a version that supported CEIP, and participation is unknown, you are asked if you want to participate.
The collected information is anonymous, so it cannot be viewed after it is uploaded to Citrix Insight Services.
Enrollment when installing a VDA
By default, you are automatically enrolled in CEIP when you install a Windows VDA. You can change this default in a registry setting. If you change the registry setting before installing the VDA, that value will be used.
Registry setting that controls automatic enrolment in CEIP (default = 1):
Location: HKLM:\Software\Citrix\Telemetry\CEIP Name: Enabled Value: 0 = disabled, 1 = enabled
By default, the “Enabled” property is hidden in the registry. When it remains unspecified, the automatic upload feature is enabled.
Using PowerShell, the following cmdlet disables enrollment in CEIP:
New-ItemProperty -Path HKLM:\SOFTWARE\Citrix\Telemetry\CEIP -Name Enabled -PropertyType DWORD -Value 0
The collected runtime datapoints are periodically written as files to an output folder (default %programdata%/Citrix/VdaCeip).
The first upload of data occurs approximately seven days after you install the VDA.
Enrollment when installing other products and components
You can also participate in CEIP when you install related Citrix products, components, and technologies, such as Provisioning Services, AppDNA, Citrix License Server, Citrix Receiver for Windows, Universal Print Server, and Session Recording. See their documentation for details about installation and participation default values.
Citrix Smart Tools
You can enable Smart Tools access when you install a Delivery Controller.
The option to enable Smart Tools access (and participate in Call Home, if it is not already enabled) is selected by default. Click Connect. A browser window opens and navigates automatically to a Smart Services web page, where you enter your Citrix Cloud account credentials. (If you don’t have a Citrix Cloud account, simply enter your Citrix account credentials, and a new Citrix Cloud account is automatically created for you.) After you’re authenticated, a certificate is silently installed in the Smart Tools Agent directory.
To use the Smart Tools technologies, see the Smart Tools documentation.
Citrix Call Home
When you install certain components and features in XenApp or XenDesktop, you are offered the opportunity to participate in Citrix Call Home. Call Home collects diagnostic data and then periodically uploads telemetry packages containing that data directly to Citrix Insight Services (via HTTPS on default port 443) for analysis and troubleshooting.
In XenApp and XenDesktop, Call Home runs as a background service under the name Citrix Telemetry Service. For more information, see https://more.citrix.com/XD-CALLHOME.
The Call Home scheduling functionality is also available in Citrix Scout. For details, see Citrix Scout.
What is collected
Citrix Diagnostic Facility (CDF) tracing logs information that can be useful for troubleshooting. Call Home collects a subset of CDF traces that can be helpful when troubleshooting common failures, for example, VDA registrations and application/desktop launches. This technology is known as always-on tracing (AOT). Call Home does not collect any other Event Tracing for Windows (ETW) information, nor can it be configured to do so.
Call Home also collects other information, such as:
- Registries created by XenApp and XenDesktop under HKEY_LOCAL_MACHINE\SOFTWARE\Citrix
- Windows Management Instrumentation (WMI) information under the Citrix namespace
- List of processes running
- Crash dumps of Citrix processes that are stored in %PROGRAM DATA%\Citrix\CDF
The trace information is compressed as it is collected. The Citrix Telemetry Service retains a maximum of 10 MB of compressed recent trace information, with a maximum time limit of eight days.
- Compressing data allows Call Home to maintain a small footprint on the VDA.
- Traces are held in memory to avoid IOPs on provisioned machines.
- The trace buffer uses a circular mechanism to retain traces in memory.
Call Home collects these key datapoints: Call Home key datapoints
Configure and manage summary
You can enroll in Call Home when using the full-product installation wizard or later, using PowerShell cmdlets. When you enroll, by default, diagnostics are collected and uploaded to Citrix every Sunday at approximately 3:00 AM, local time. The upload is randomized with a two hour interval from the specified time. This means an upload using the default schedule occurs between 3:00 AM and 5:00 AM.
If you do not want to upload diagnostic information on a scheduled bassis (or if you want to change a schedule), you can use PowerShell cmdlets to manually collect and upload diagnostics or store them locally.
When you enroll in scheduled Call Home uploads and when you manually upload diagnostic information to Citrix, you provide Citrix account or Citrix Cloud credentials. Citrix exchanges the credentials for an upload token that is used to identify the customer and upload the data. The credentials are not saved.
When an upload occurs, a notification is emailed to the address associated with the Citrix account.
Prerequisites
- The machine must be running PowerShell 3.0 or later.
- The Citrix Telemetry Service must be running on the machine.
- The system variable PSModulePath must be set to Telemetry’s install path, for example, C:\Program Files\Citrix\Telemetry Service\.
Enable Call Home during component installation
During VDA installation or upgrade: When you install or upgrade a Virtual Delivery Agent using the graphical interface in the full-product installer, you are asked if you want to participate in Call Home. There are two options:
- Participate in Call Home.
- Do not participate in Call Home.
If you’re upgrading a VDA and previously enrolled in Call Home, that wizard page won’t appear.
During Controller installation or upgrade: When you install or upgrade a Delivery Controller using the graphical interface, you are asked if you want to participate in Call Home and connect to Citrix Smart Tools. There are three options:
- Connect to Citrix Smart Tools, which includes the Call Home functionality via the Smart Tools agent. This is the default and recommended option. If you choose this option, the Smart Tools agent is configured. (The Smart Tools agent is installed, regardless of whether this option is selected.)
- Participate only in Call Home, but do not connect to Smart Tools. If you choose this option, the Smart Tools agent is installed, but not configured. Call Home functionality is provided through the Citrix Telemetry Service and Citrix Insight Services.
- Do not connect to Smart Tools or participate in Call Home.
When you’re installing a Controller, you will not be able to configure information on the Call Home page in the installation wizard if that server has an Active Directory GPO with the policy setting “Log on as a service” applied. For details, see CTX218094.
If you’re upgrading a Controller and previously enrolled in Call Home, the page will ask only about Smart Tools. If you’re already enrolled in Call Home and the Smart Agent is already installed, the wizard page won’t appear.
For information about Smart Tools, see the Smart Tools documentation.
PowerShell cmdlets
The PowerShell help provides comprehensive syntax, including descriptions of cmdlets and parameters that are not used in these common use cases.
To use a proxy server for uploads, see Configure a proxy server.
Enable scheduled uploads
Diagnostic collections are automatically uploaded to Citrix. If you do not enter additional cmdlets for a custom schedule, the default schedule is used.
$cred = Get-Credential Enable-CitrixCallHome -Credential $cred
To confirm that scheduled uploads are enabled, enter Get-CitrixCallHome. It should return IsEnabled=True and IsMasterImage=False.
Enable scheduled uploads for machines created from a master image
Enabling scheduled uploads in a master image eliminates having to configure each machine that is created in the machine catalog.
Enable-CitrixCallHome -Credential $cred -MasterImage
To confirm that scheduled uploads are enabled, enter Get-CitrixCallHome. It should return IsEnabled=True and IsMasterImage=True.
Create a custom schedule
Ceate a daily or weekly schedule for diagnostic collections and uploads.
$timespan = New-TimeSpan –Hours <hours> -Minutes <minutes> Set-CitrixCallHomeSchedule –TimeOfDay $timespan –DayOfWeek <day> -UploadFrequency {Daily|Weekly}
Cancel scheduled uploads
After you cancel scheduled uploads, you can still upload diagnostic data using PowerShell cmdlets.
Disable-CitrixCallHome
To confirm that scheduled uploads are disabled, enter Get-CitrixCallHome. It should return IsEnabled=False and IsMasterImage=False.
Examples
The following cmdlet creates a schedule to bundle and upload data at 11:20 every evening. Note that the Hours parameter uses a 24-hour clock. When the UploadFrequency parameter value is Daily, the DayOfWeek parameter is ignored, if specified.
$timespan – New-TimeSpan –Hours 22 –Minutes 20 Set-CitrixCallHomeSchedule –TimeOfDay $timespan -UploadFrequency Daily
To confirm the schedule, enter Get-CitrixCallHomeSchedule, In the above example,it should return StartTime=22:20:00, DayOfWeek=Sunday (ignored), Upload Frequency=Daily.
The following cmdlet creates a schedule to bundle and upload data at 11:20 every Wednesday evening.
$timespan – New-TimeSpan –Hours 22 –Minutes 20 Set-CitrixCallHomeSchedule –TimeOfDay $timespan –DayOfWeek Wed -UploadFrequency Weekly
To confirm the schedule, enter Get-CitrixCallHomeSchedule, In the above example, it should return StartTime=22:20:00, DayOfWeek=Wednesday, Upload Frequency=Weekly.
Configure a proxy server for Call Home uploads
Complete the following tasks on the machine where Call Home is enabled. Example diagrams in the following procedure contain server address and port 10.158.139.37:3128. Your information will differ.
Step 1. Add proxy server information in your browser. In Internet Explorer, select Internet Options > Connections > LAN settings. Select Use a proxy server for your LAN” and enter the proxy server address and port number.
Step 2. In PowerShell, run netsh winhttp import proxy source=ie.
Step 3. Using a text editor, edit the TelemetryService.exe config file, which is located in C:\Program Files\Citrix\Telemetry Service. Add the information shown in the red box below.
Step 4. Restart the Telemetry Service.
Run the Call Home cmdlets in PowerShell.
Manually collect and upload diagnostic information
You can use the CIS web site to upload a diagnostic information bundle to CIS. You can also use PowerShell cmdlets to collect and upload diagnostic information to CIS.
To upload a bundle using the CIS web site:
- Log on to Citrix Insight Services using your Citrix account credentials.
- Select My Workspace.
- Select Healthcheck and then navigate to the location of your data.
CIS supports several PowerShell cmdlets that manage data uploads. This documentation covers the cmdlets for two common cases:
- Use the Start-CitrixCallHomeUpload cmdlet to manually collect and upload a diagnostic information bundle to CIS. (The bundle is not saved locally.)
- Use the Start-CitrixCallHomeUpload cmdlet to manually collect data and store a diagnostic information bundle locally. This allows you to preview the data. Then, at a later time, use the Send-CitrixCallHomeBundle cmdlet to manually upload a copy of that bundle to CIS. (The data you originally saved remains locally.)
The PowerShell help provides comprehensive syntax, including descriptions of cmdlets and parameters that are not used in these common use cases.
When you enter a cmdlet to upload data to CIS, you are prompted to confirm the upload. If the cmdlet times out before the upload completes, check the status of the upload in the system event log. The upload request may be rejected if the service is already performing an upload.
Collect data and upload bundle to CIS
Start-CitrixCallHomeUpload [-Credential] <PSCredential> [-InputPath <String>] [-Description <String>] [-IncidentTime <String>] [-SRNumber <String>] [-Name <String>] [-UploadHeader <String>] [-AppendHeaders <String>] [-Collect <String>] [<CommonParameters>]
Collect data and save it locally
Start-CitrixCallHomeUpload -OutputPath <String> [-InputPath <String>] [-Description <String>] [-IncidentTime <String>] [-SRNumber <String>] [-Name <String>] [-UploaderHeader <String>] [-AppendHeaders <String>] [-Collect <String>] [<CommonParameters>]
| Parameter | Description |
|---|---|
| Credential | Directs the upload to CIS. |
| InputPath | Location of zip file to include in the bundle. This might be an additional file that Citrix Support requests. Be sure to include the .zip extension. |
| OutputPath | Location where the diagnostic information will be saved. This parameter is required when saving Call Home data locally. |
| Description and Incident Time | Free form information about the upload. |
| SRNumber | Citrix Technical Support incident number. |
| Name | Name that identifies the bundle. |
| UploadHeader | JSON-formatted string specifying the upload headers uploaded to CIS. |
| AppendHeaders | JSON-formatted string specifying the appended headers uploaded to CIS. |
| Collect | JSON-formatted string specifying which data to collect or omit, in the form {‘collector’:{‘enabled’:Boolean}}”, where Boolean is true or false. Valid collector values are: ‘wmi’; ‘process’; ‘registry’; ‘crashreport’; ‘trace’; ‘localdata’; ‘sitedata’; ‘sfb’. By default, all collectors except ‘sfb’ are enabled. The ‘sfb’ collector is designed to be used on demand to diagnose Skype for Business issues. In addition to the ‘enabled’ parameter, the ‘sfb’ collector supports the ‘account’ and ‘accounts’ parameters to specify target users. Use one of the forms: “-Collect “{‘sfb’:{‘account’:’domain\user1’}}”; -Collect “{‘sfb’:{‘accounts’:[‘domain\user1’, ‘domain\user2’]}}” |
| Common Parameters | See the PowerShell help. |
Upload data that was previously saved locally
Send-CitrixCallHomeBundle -Credential <PSCredential> -Path <String> [<CommonParameters>]
The Path parameter specifies the location of the previously-saved bundle.
Examples
The following cmdlet requests an upload of Call Home data (excluding data from the WMI collector) to CIS. This data relates to registration failures for PVS VDAs, which was noted at 2:30 PM for Citrix Support case 123456. In addition to the Call Home data, the file “c:\Diagnostics\ExtraData.zip” will be incorporated into the uploaded bundle.
C:\PS>Start-CitrixCallHomeUpload -InputPath “c:\Diagnostics\ExtraData.zip” -Description “Registration failures with PVS VDAs” -IncidentTime “14:30” -SRNumber 123456 -Name “RegistrationFailure-021812016” -Collect “{‘wmi’:{‘enabled’:false}}” -UploadHeader “{‘key1’:’value1’}” -AppendHeaders “{‘key2’:’value2’}”
The following cmdlet saves Call Home data related to Citrix Support case 223344, noted at 8:15 AM. The data will be saved in the file mydata.zip on a network share. In addition to the Call Home data, the file “c:\Diagnostics\ExtraData.zip” will be incorporated into the saved bundle.
C:\PS>Start-CitrixCallHomeUpload -OutputPath \\mynetwork\myshare\mydata.zip -InputPath “c:\Diagnostics\ExtraData.zip” -Description “Diagnostics for incident number 223344” -IncidentTime “8:15” -SRNumber 223344
The following cmdlet uploads the data bundle you saved earlier.
$cred=Get-Credential C:\PS>Send-CitrixCallHomeBundle –Credential $cred -Path \\mynetwork\myshare\mydata.zip
Citrix Scout
For full details, see Citrix Scout.
In this article
- Install and upgrade analytics
- Citrix Customer Experience Improvement Program (CEIP)
- Citrix Smart Tools
- Citrix Call Home
- Configure and manage summary
- Prerequisites
- Enable Call Home during component installation
- PowerShell cmdlets
- Configure a proxy server for Call Home uploads
- Manually collect and upload diagnostic information
- Citrix Scout