Citrix Virtual Apps and Desktops

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

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

This Citrix Virtual Apps and Desktops release supports the following technologies.

In addition to (and separate from) CIS and Citrix Analytics: Google Analytics are collected (and later uploaded) automatically when you install (or upgrade) Studio. After installing Studio, you can change this setting with the registry key HKLM\Software\Citrix\DesktopStudio\GAEnabled. A value of 1 enables collection and upload, 0 disables collection and upload.

Install and upgrade analytics

When you use the full-product installer to deploy or upgrade Citrix Virtual Apps and Desktops 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 is 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.

Control automatic uploads:

  • 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
     <!--NeedCopy-->
    
  • 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

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 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 Citrix Virtual Apps and Desktops 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 is enabled in the upgraded Site.
  • If you upgrade from a version that supported CEIP, and participation was disabled, CEIP is disabled in the upgraded Site.
  • If you upgrade from 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 is 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
<!--NeedCopy-->

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 Citrix Provisioning, AppDNA, Citrix License Server, Citrix Workspace app 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 Citrix Virtual Apps and Desktops, 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 Citrix Virtual Apps and Desktops, 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). AOT logs are saved to disk at C:\Users\CitrixTelemetryService\Appdata\Local\CitrixAOT.

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 Citrix Virtual Apps and Desktops 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.
  • Installation and upgrade information. This can include the full product metainstaller log, failing MSI logs, output from the MSI log analyzer, StoreFront logs, Licensing compatibility check logs, and results from preliminary site upgrade tests.

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 the key datapoints listed in 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 basis (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.

If you enable Call Home when you install a component, you can disable it later.

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 does not 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. There are three options:

When you’re installing a Controller, you cannot 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, you’re not asked about participating.

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
     <!--NeedCopy-->
    

    To confirm that scheduled uploads are enabled, enter Get-CitrixCallHomeGet-CitrixCallHome. If enabled, the return is 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. If enabled, the return is IsEnabled=True and IsMasterImage=True.

  • Create a custom schedule: Create 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}
     <!--NeedCopy-->
    

Examples:

The following cmdlet creates a schedule to bundle and upload data at 10:20 every evening. 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
<!--NeedCopy-->

To confirm the schedule, enter Get-CitrixCallHomeSchedule. In the preceding example, it returns StartTime=22:20:00, DayOfWeek=Sunday (ignored), Upload Frequency=Daily.

The following cmdlet creates a schedule to bundle and upload data at 10:20 every Wednesday evening.

$timespan – New-TimeSpan –Hours 22 –Minutes 20
Set-CitrixCallHomeSchedule –TimeOfDay $timespan –DayOfWeek Wed -UploadFrequency Weekly
<!--NeedCopy-->

To confirm the schedule, enter Get-CitrixCallHomeSchedule. In the preceding example, it returns StartTime=22:20:00, DayOfWeek=Wednesday, Upload Frequency=Weekly.

Disable Call Home

You can disable Call Home using a PowerShell cmdlet or through Citrix Scout.

AOT logs are collected and saved to disk, even when Call Home scheduled uploads are disabled. (When scheduled uploads are disabled, AOT logs are not automatically uploaded to Citrix.) You can disable the collection and local storage of AOT logs.

Disable Call Home with PowerShell

After running the following cmdlet, diagnostic data will not be uploaded to Citrix automatically. (You can still upload diagnostic data using Citrix Scout or telemetry PowerShell cmdlets.)

Disable-CitrixCallHome

To confirm that Call Home is disabled, enter Get-CitrixCallHome. If disabled, the return is IsEnabled=False and IsMasterImage=False.

Disable a collection schedule using Citrix Scout

To disable a diagnostic collection schedule using Citrix Scout, follow the guidance in Schedule collections. In step 3, click Off to cancel the schedule for the selected machines.

Disable collection of AOT logs

After running the following cmdlet (with the Enabled field set to false), AOT logs will not be collected.

Enable-CitrixTrace -Listen‘{“trace”:{“enabled”:false,“persistDirectory”:“C:\Users\Public”,”maxSizeBytes”:1000000, “sliceDurationSeconds”:300}}’

The Listen parameter contains arguments in JSON format.

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.

  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.

  2. In PowerShell, run netsh winhttp import proxy source=ie.

    Example of running netsh command when configuring a proxy server

  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.

    Add proxy information to the TelemetryService.exe file

  4. Restart the Telemetry Service.

Run the Call Home cmdlets in PowerShell.

Manually collect and upload diagnostic information

You can use the CIS website 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 website:

  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. Later, 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 might 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>]
<!--NeedCopy-->

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 strings] [<CommonParameters>]
<!--NeedCopy-->

The following parameters are valid:

  • 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 is 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’
    • ‘file’
    • ‘msi’
    • ‘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 <PSCredentia\> -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 of Citrix Provisioning VDAs, which were noted at 2:30 PM for Citrix Support case 123456. In addition to the Call Home data, the file “c:\Diagnostics\ExtraData.zip” is incorporated into the uploaded bundle.

C:\PS\>Start-CitrixCallHomeUpload -InputPath "c:\Diagnostics\ExtraData.zip" -Description "Registration failures with Citrix Provisioning VDAs" -IncidentTime "14:30" -SRNumber 123456 -Name "RegistrationFailure-021812016" -Collect "{'wmi':{'enabled':false}}" -UploadHeader "{'key1':'value1'}" -AppendHeaders "{'key2':'value2'}"
<!--NeedCopy-->

The following cmdlet saves Call Home data related to Citrix Support case 223344, noted at 8:15 AM. The data 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
<!--NeedCopy-->

The following cmdlet uploads the data bundle you saved earlier.

$cred=Get-Credential
C:\PS>Send-CitrixCallHomeBundle –Credential $cred -Path \\mynetwork\myshare\mydata.zip
<!--NeedCopy-->
Citrix Insight Services