Configuration logging
Configuration logging is a feature that captures site configuration changes and administrative activities to the database. The feature is enabled by default. 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 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 different 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 is 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 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.
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.
- Sign in to Web Studio and select Logging in the left pane.
- Select Preferences in the action bar. 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 Enable. 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 Disable. If logging was previously enabled, existing logs remain readable with the PowerShell SDK.
To enable mandatory logging, select Prevent changes to the site configuration when the database is not available. No configuration change or administrative activity that is normally logged is allowed unless it can be written in the configuration logging database. You can enable mandatory logging only when configuration logging is enabled (when Enable 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 Allow changes when to the site configuration when the database is not available. Configuration changes and administrative activities are allowed, even if the configuration logging database cannot be accessed. This is the default setting.
Change the configuration logging database location
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.
- Sign in to Web Studio and select Logging in the left pane.
- Select Preferences in the action bar.
- 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. See Database address formats for valid formats.
- To allow Studio to create the database, click OK. When prompted, click OK, and the database is 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 indicates 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 listed 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 pane, the lower 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 creates a surrogate high level operation.
To display configuration log content, select Logging in the Studio navigation pane. By default, the center pane lists the log content chronologically (newest entries first), separated by date. You can:
- Sort the display by column header.
- Filter the display by specifying a day interval, or entering text in the Search box. To return to the standard display after using search, clear the text in the Search box.
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) 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 action bar.
- Select the date range for the report.
- Select the report format: CSV, HTML, or both.
- Browse to the location where you want to save the report.
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 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
serveradminorsetupadminserver roles allow you to perform deletion operations. -
If your deployment requires more 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_ROLEordbowner.
For more information, see the SQL Server Management Studio documentation.
-
To delete the configuration logs:
- Sign in to Web Studio and select Logging in the left pane.
- Select Delete logs in the action bar.
- 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 is 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.
View API and PowerShell logs
To monitor API requests made during your current session, click the APIs tab. API logs are cleared after you sign out of Web Studio.
To view PowerShell commands corresponding to UI actions you’ve taken during the day, click the PowerShell tab.
Associate metadata with configuration logs
You can attach metadata to configuration logs by associating a name-value pair called MetadataMap with the log records.
Note:
- You can only attach metadata to high-level operation objects.
- Metadata is associated with the existing records at the time of execution.
Set the metadata
Run the PowerShell command Set-LogHighLevelOperationMetadata to associate a log record with the MetadataMap.
Set-LogHighLevelOperationMetadata takes the following parameters:
- Id: ID of the high-level operation.
-
InputObject: The high-level operations to which you add the metadata. This is an alternative to the
Idparameter where a high-level operation object or list of objects is passed to the PowerShell command. -
Name: Property name of the metadata to be added. The property must be unique for the high-level operation specified. The property cannot contain any of the following characters ()\/;:#.*?=<> []”’. - Value: Value for the property.
-
Map: Dictionary of (name, value) pairs for the properties. This is an alternative to setting the metadata using the
-Nameand-Valueparameters.
For example, to attach the metadata to all the high-level log records with Id 40, run the following PowerShell command:
Get-LogHighLevelOperation – Id 40 | Set-LogHighLevelOperationMetadata -Name A -Value B
To attach the metadata to the high-level record with the user abc@example.com, run the following PowerShell command:
Get-LogHighLevelOperation – User `abc@example.com` | Set-LogHighLevelOperationMetadata -Name C -Value D
Retrieve using the metadata
Run the following PowerShell commands to use the associated metadata to retrieve the log records:
-
Search by key and value:
Get-LogHighLevelOperation -Metadata "Key:Value" -
Search by value any key:
Get-LogHighLevelOperation -Metadata "*:Value" -
Search by key and any value:
Get-LogHighLevelOperation -Metadata "Key:*"
Remove the metadata
Run the PowerShell command Remove-LogHighLevelOperationMetadata to remove the associated metadata.
Remove-LogHighLevelOperationMetadata takes the following parameters:
- Id: ID of the high-level operation.
-
InputObject: The high-level operations to which you add the metadata. This is an alternative to the
Id` parameter where a high-level operation object or list of objects is passed to the PowerShell command. - Name: Property name of the metadata to be removed. Set to $null to remove all the metadata for the specified object.
- Map: Dictionary of (name, value)-pairs for the properties. This can be either a hashtable (created with @{“name1” = “val1”; “name2” = “val2”}) or a string dictionary (created with new-object “System.Collections.Generic.Dictionary[String, String]”). The properties whose names match the keys in the map are removed.
In this article
- What is logged
- Manage configuration logging
- Enable and disable configuration logging and mandatory logging
- Change the configuration logging database location
- Display configuration log content
- Generate reports
- Delete configuration log content
- View API and PowerShell logs
- Associate metadata with configuration logs