Configuration Logging
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 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). You can specify a differnt location for the database. 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 uses the database that is created when you create a Site (also known as the Site Configuration database). Citrix recommends that you use a separate location for the Configuration Logging database (and the Monitoring database) 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) might adversely affect the space available to the Site Configuration database.
- It splits the single point of failure for the three databases.
Note: Product editions that do not support Configuration Logging do not have a Logging node in Studio.
Enable and disable Configuration Logging and mandatory logging
By default, Configuration Logging is enabled, and mandatory logging is disabled.
- Select Logging in the Studio navigation pane.
- Select Preferences in the Actions pane. The Configuration Logging dialog box contains database information and indicates whether Configuration Logging and mandatory logging are enabled or disabled.
- Select the desired action:
To enable Configuration Logging, select the Enable 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 radio button. If logging was previously enabled, existing logs remain readable with the PowerShell SDK.
To enable mandatory logging, select the Prevent changes to the site configuration when the database is not available radio button. No configuration change or administrative activity that would normally be logged will be allowed unless it can be written in the Configuration Logging database. You can enable mandatory logging only when Configuration Logging is enabled, that is, when the Enable 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 disable mandatory logging, select the Allow changes when to the site configuration when the database is not available radio button. Configuration changes and administrative activities are allowed, even if the database used for Configuration Logging cannot be accessed. This is the default setting.
Change the Configuration Logging database location
Note: You cannot change the database location when mandatory logging is enabled, because the location change includes a brief disconnect interval that cannot be logged.
- Create a database server, using a supported SQL Server version.
- Select Logging in the Studio navigation pane.
- Select Preferences in the Actions pane.
- In the Logging Preferences dialog box, select Change logging database.
- In the Change Logging Database dialog box, specify the location of the server containing the new database server. Valid formats are listed in the Databases article.
- To allow Studio to create the database, click OK. When prompted, click OK, and the database will be created 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 during database creation.)
- To create the database manually, click Generate database script. 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, the high level operations created by Studio and Director are displayed in the upper middle 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 middle pane, the lower middle 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 that calls 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, select Logging in the Studio navigation 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 middle 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 next to the Search box at the top of the middle pane. |
Generate reports
You can generate CSV and HTML reports containing configuration log data.
- The CSV report contains all 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, select Logging in the Studio navigation pane, and then select Create custom report in the Actions pane.
- Select the date range for the report.
- Select the report format: CSV, HTML, or both.
- Browse to the location where the report should be saved.
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.
- In SQL Server Management Studio, create a SQL Server login with a server role other than ‘sysadmin.’
- 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.
- 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:
- Select Logging in the Studio navigation pane.
- Select Delete logs in the Actions pane.
- 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 is created as a CSV file.
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.