Product Documentation

Citrix Insight Services

Dec 06, 2016

Citrix Insight Services (CIS) is the Citrix flagship 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). 

All information uploaded to Citrix Insight Services is used for troubleshooting and diagnostic purposes, as well as improving the quality, reliability, and performance of products, subject to:

This XenApp and XenDesktop release supports the following tools and technologies.

  • XenApp and XenDesktop install and upgrade analytics
  • Citrix Customer Experience Improvement Program
  • Citrix Call Home
  • 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. For  more information, see http://more.citrix.com/XD-INSTALLER.

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 http://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 upload of install/upgrade analytics (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 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 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.

Call Home runs as a background service under the name Citrix Telemetry Service.

For more information, see http://more.citrix.com/XD-CALLHOME.

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.
htm

Call Home key datapoints

Call Home collects these key datapoints.

Configure and manage summary

You can indicate whether or not you want to participate in Call Home when you install a Delivery Controller or VDA using the graphical interface in the full-product installer. 

After installing components, you can use PowerShell cmdlets to:

  • Enable scheduled Call Home uploads or change your current schedule. This includes enabling scheduled uploads in a master image used in a Machine Catalog, which eliminates having to configure Call Home in each created VM.
  • Manually collect data and upload it to CIS.
  • Manually collect data and store it locally, and then later upload that data to CIS.

For complete PowerShell cmdlet syntax, see the cmdlet help.

When you enroll in scheduled Call Home uploads and when you manually upload diagnostic information to CIS, you must provide Citrix account credentials. CIS 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. 

Enable and configure scheduled uploads

You can enroll in scheduled uploads to Call Home when using the full-product installation wizard or later, using PowerShell cmdlets. By default, data is collected and uploaded to CIS every Sunday at around 3:00 AM, local time. The upload time is randomized with a two hour interval form 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 bundles on a scheduled basis, you can still use PowerShell cmdlets to manually collect and upload Call Home data.

Enable scheduled uploads during component installation

When you use the graphical interface of the full-product XenApp and XenDesktop installer to install a Controller or VDA, you can indicate whether or not you want to participate in scheduled uploads to Call Home. By default, participation is selected. 

  • If you want to participate, sign in to CIS with your Citrix account credentials.
  • If you do not want to participate (or if you want to participate, but your Citrix account credentials could not be validated), decline participation on the wizard page. You can enroll later after Site setup, using PowerShell cmdlets.

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.

Enable scheduled uploads using PowerShell cmdlets

Enter the following cmdlets to enable scheduled uploads of Call Home diagnostic information bundles to CIS. 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

You can create a custom daily or weekly schedule.

$timespan = New-TimeSpan –Hours <hours> -Minutes <minutes>
Set-CitrixCallHomeSchedule –TimeOfDay $timespan –DayOfWeek <day> -UploadFrequency {Daily|Weekly}

Cancel scheduled uploads

Enter the following cmdlet to cancel scheduled uploads. (You can still upload diagnostic data bundles 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

On the machine where Call Home is enabled, in the Program Files\Citrix\Telemetry Service directory, edit the TelemetryService.exe.config file, adding the yellow highlighted portion in the following example. (The example specifies the server address and port 10.158.139.37:3128; yours will differ.)

After an upload completes, you can view the uploaded Call Home information at CIS.citrix.com.

localized image

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:

  1. Log on to Citrix Insight Services using your Citrix account credentials.
  2. Select My Workspace.
  3. 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

Citrix Scout is the predecessor to Call Home. It captures and uploads key data points and CDF traces. See CTX130147 for more information about Citrix Scout.

You can download the Citrix Scout software from that article. The software is also available on the XenApp and XenDesktop ISO.