Product Documentation

Configuration Logging

May 10, 2015
Configuration Logging captures Site configuration changes and administrative activities to the Database. You can use the logged content to:
  • Diagnose and troubleshoot problems after configuration changes are made; the log provides a breadcrumb trail
  • Assist change management and track configurations
  • Report administration activity

You set Configuration Logging preferences, display configuration logs, and generate HTML and CSV reports from Citrix Studio. You can filter configuration log displays by date ranges and by full text search results. Mandatory logging, when enabled, prevents configuration changes from being made unless they can be logged. With appropriate permission, you can delete entries from the configuration log. You cannot use the Configuration Logging feature to edit log content.

Configuration Logging uses a PowerShell 2.0 SDK and the Configuration Logging Service. The Configuration Logging Service runs on every Controller in the Site; if one Controller fails, the service on another Controller automatically handles logging requests.

By default, the Configuration Logging feature is enabled, and uses the Database that is created when you create the Site (the Site Configuration Database). Citrix strongly recommends that you you change the location of the database used for Configuration Logging as soon as possible after creating a Site. The Configuration Logging Database supports the same high availability features as the Site Configuration Database.

Access to Configuration Logging is controlled through Delegated Administration, with the Edit Logging Preferences and View Configuration Logs permissions.

Configuration logs are localized when they are created. For example, a log created in English will be read in English, regardless of the locale of the reader.

What is logged

Configuration changes and administrative activities initiated from Studio, Director, and PowerShell scripts are logged. Examples of logged configuration changes include working with (creating, editing, deleting assigning):
  • Machine Catalogs
  • Delivery Groups (including changing power management settings)
  • Administrator roles and scopes
  • Host resources and connections
  • Citrix policies through Studio
Examples of logged administrative changes include:
  • Power management of a virtual machine or a user desktop
  • Studio or Director sending a message to a user
The following operations are not logged:
  • Autonomic operations such as pool management power-on of virtual machines.
  • Policy actions implemented through the Group Policy Management Console (GPMC); use Microsoft tools to view logs of those actions.
  • Changes made through the registry, direct access of the Database, or from sources other than Studio, Director, or PowerShell.
  • When the deployment is initialized, Configuration Logging becomes available when the first Configuration Logging Service instance registers with the Configuration Service. Therefore, the very early stages of configuration are not logged (for example, when the Database schema is obtained and applied, when a hypervisor is initialized).

Manage Configuration Logging

By default, Configuration Logging is enabled, and mandatory logging is disabled.

By default, Configuration Logging uses the database that is created when you create a Site (also known as the Site Configuration Database). Citrix recommends that you change the location of the database used for Configuration Logging (and the database used for the Monitoring Service, which also uses the Site Configuration Database by default) after creating a Site, for the following reasons:
  • The backup strategy for the Configuration Logging Database is likely to differ from the backup strategy for the Site Configuration Database.
  • The volume of data collected for Configuration Logging (and the Monitoring Service) could adversely affect the space available to the Site Configuration database.
  • It splits the single point of failure for the three databases.

For more information, see Change secondary database locations.

The Configuration Logging Database supports the same high availability features as the Site Configuration Database. Review the database guidance in Plan a deployment.

To enable/disable Configuration Logging and mandatory logging

  1. From Citrix Studio, select Logging in the left pane.
    Note: Editions that do not support Configuration Logging do not have a Logging node.
  2. In the Actions pane, click Preferences. The Configuration Logging dialog box appears, displaying database information and whether Configuration Logging and mandatory logging are enabled or disabled.
    • To enable or disable Configuration Logging:
      • To enable Configuration Logging, select the Enable logging radio button. This is the default setting. If the database cannot be written to, the logging information is discarded, but the operation continues.
      • To disable Configuration Logging, select the Disable logging radio button. If logging was previously enabled, existing logs remain readable with the PowerShell SDK.
    • To enable or disable mandatory logging:
      • To enable mandatory logging, clear the Allow changes when the database is disconnected checkbox. No configuration change or administrative activity that would normally be logged will be allowed unless it can be written in the database used for Configuration Logging.
      • To disable mandatory logging, select the Allow changes when the database is disconnected checkbox. Configuration changes and administrative activities are allowed, even if the database used for Configuration Logging cannot be accessed. This is the default setting.

      The mandatory logging option is available only when Configuration Logging is enabled, that is, when the Enable Configuration Logging radio button is selected. If the Configuration Logging Service fails, and high availability is not in use, mandatory logging is assumed. In such cases, operations that would normally be logged are not performed.

To change the Configuration Logging Database location

  1. Create a database server, using a supported SQL Server version.
  2. From Studio, select Logging in the left pane.
  3. In the Actions pane, click Preferences. The Configuration Logging dialog box appears.
  4. Click Change logging database. The Change Configuration Logging Database dialog box appears.
  5. Specify the location of the server containing the new database server (using one of the forms in the following table) and the database name.
    Database type What to enter With this database configuration
    Standalone or mirror servername The default instance is used and SQL Server uses the default port.
      Servername\INSTANCENAME A named instance is used and SQL Server uses the default port.
      servername,port-number The default instance is used and SQL Server uses a custom port. (The comma is required.)
    Other cluster-name A clustered database.
      availability-group-listener An Always-On database.
  6. If you want Studio to create the database, click OK or Test connection. When prompted, click OK, and Studio will create the database automatically. Studio attempts to access the database using the current Studio user's credentials; if that fails, you are prompted for the database user's credentials. Studio then uploads the database schema to the database. (The credentials are retained only for the database creation time frame.)
  7. If you want to create the database manually, click Generate script (or use Get-LogDBSchema in the PowerShell SDK). The generated script includes instructions for manually creating the database. Ensure that the database is empty and that at least one user has permission to access and change the database before uploading the schema.

The Configuration Logging data in the previous database is not imported to the new database. Logs cannot be aggregated from both databases when retrieving logs. The first log entry in the new Configuration Logging Database will indicate that a database change occurred, but it does not identify the previous database.

Display configuration log content

When initiating configuration changes and administrative activities, Citrix Studio and Citrix Director create high level operations, which are displayed in the upper portion of the center pane in Studio. A high level operation results in one or more service and SDK calls, which are low level operations. When you select a high level operation in the upper portion of the center pane, the lower portion of the center pane displays the low level operations.

If an operation fails before completion, the log operation might not be completed in the Database; for example, a start record will have no corresponding stop record. In such cases, the log indicates that there is missing information. When you display logs based on time ranges, incomplete logs are shown if the data in the logs matches the criteria. For example, if all logs for the last five days are requested and a log exists with a start time in the last five days but has no end time, it is included.

When using a script to call PowerShell cmdlets, if you create a low level operation without specifying a parent high level operation, Configuration Logging will create a surrogate high level operation.

To display configuration log content

From Studio, select Logging in the left pane. By default, the display in the center pane lists the log content chronologically (newest entries first), separated by date.
To filter the display by Complete this action
Search results Enter text in the Search box at the top of the center pane. The filtered display includes the number of search results. To return to the standard logging display, clear the text in the Search box.
Column heading Click a column heading to sort the display by that field.
A date range Select an interval from the drop down list box, which is next to the Search box at the top of the center pane (today, last 7 days, last 28 days, last three months, last six months).

Generate configuration log reports

You can generate CSV and HTML reports containing configuration log data.
  • The CSV report is a data dump of the logging data from a specified time interval. The hierarchical data in the database is flattened into a single CSV table. No aspect of the data has precedence in the file. No formatting is used and no human readability is assumed. The file (named MyReport) simply contains the data in a universally consumable format. CSV files are often used for archiving data or as a data source for a reporting or data manipulation tool such as Microsoft Excel.
  • The HTML report provides a human-readable form of the logging data for a specified time interval. It provides a structured, navigable view for reviewing changes. An HTML report comprises two files, named Summary and Details. Summary lists high level operations: when each operation occurred, by whom, and the outcome. Clicking a Details link next to each operation takes you to the low level operations in the Details file, which provides additional information.

To generate a configuration log report

  1. From Citrix Studio, select Logging in the left pane.
  2. In the Actions pane, click Create custom report.
  3. Select the date range for the report by selecting a predefined interval or specifying a custom time frame.
  4. Select the report format: CSV, HTML, or Both CSV and HTML.
  5. Browse to the location where the report should be saved.
  6. Review your selections on the Summary page and click Finish.

Delete configuration log content

To delete the configuration log, you must have certain Delegated Administration and SQL Server database permissions.
  • Delegated Administration — You must have a Delegated Administration role that allows the deployment configuration to be read. The built-in Full administrator role has this permission. A custom role must have Read Only or Manage selected in the Other permissions category.

    To create a backup of the configuration logging data before deleting it, the custom role must also have Read Only or Manage selected in the Logging Permissions category.

  • SQL Server database — You must have a SQL server login with permission to delete records from the database. There are two ways to do this:
    • Use a SQL Server database login with a sysadmin server role, which allows you to perform any activity on the database server. Alternatively, the serveradmin or setupadmin server roles allow you to perform deletion operations.
    • If your deployment requires additional security, use a non-sysadmin database login mapped to a database user who has permission to delete records from the database.
      1. In SQL Server Management Studio, create a SQL Server login with a server role other than 'sysadmin.'
      2. Map the login to a user in the database; SQL Server automatically creates a user in the database with the same name as the login.
      3. In Database role membership, specify at least one of the role members for the database user: ConfigurationLoggingSchema_ROLE or dbowner.

      For more information, see the SQL Server Management Studio documentation.

To delete the configuration logs

  1. From Studio, select Logging in the left pane.
  2. In the Actions pane, click Delete logs.
  3. You are asked if you want to create a backup of the logs before they are deleted. If you choose to create a backup, browse to the location where the backup archive should be saved. The backup will be created as a CSV file.
  4. Review your selections on the Summary page, and then click Finish.

After the configuration logs are cleared, the log deletion is the first activity posted to the empty log. That entry provides details about who deleted the logs, and when.