Digging in to Citrix Configuration Logging: Reporting

This is the fourth part in a series on Citrix XenApp Configuration Logging. This part will foucus on out of the box reporting tool. In a later article, we will look at custom reporting.

This is the fourth part in the Citrix Configuration Logging Series. In part 1, we discussed what Citrix Configuration Logging was. In part 2, we discussed how to prepare the database to log configuration changes. In part 3, we discussed how to set up the Citrix XenApp farm for Configuration Logging. In this part, we will look at the out of the box reporting tools (in a later article, we will look at custom reporting).

Citrix Report Center

Report Center is part of the Citrix Access Management Console. Report Center allows you to create, schedule, and distribute various types of canned reports. One of the types of reports available is the, you guessed it, “Configuration Logging Report”. There are several other reports available as well including, but not limited to:

  • Alerts Report
  • Application Usage Report
  • Client Type Report
  • CPU Utilization Management Report
  • Policy Report
  • Server Availability Report
  • Environment Usage Report

Report Specification

Before you can run any report in the Access Management Console, you have to create a report specification. A report specification basically tells a report where to get its data and where/how to output the data. Different reports will have different data sources. For instance, the Configuration Logging Report’s data source would be the Configuration Logging database, whereas the Application Usage Report’s data source would be the Resource Manager Summary Database. There is a wizard in the AMC that will step you through setting up a report specification. To start the wizard, simply right-click the Report Center node in the AMC and select “Generate specification”. The wizard is pretty self explanatory, but I do want to point out one part.


When you choose to store a report for later viewing, the report is stored in your user profile (actually, all report specification options as well as the report specification itself is stored in the user profile). The bad thing about this is all this stuff is stored in your local profile by default in the following path:

%USERPROFILE%\Local Settings\Application Data\Citrix\ReportCenter\

If you are using roaming profiles, these reports/specifications will get wiped out when you log off (since Local Settings do not roam). However, there is an option to store reports in your roaming profile. This setting is located in the middle column of the AMC when you select the Report Center node.


Scheduling Reports

One of the interesting things you can do is schedule a report to run on a recurring basis. Say you wanted to get a summary of configuration changes every morning. You could create a schedule to run this report and email it to you. To schedule a report, right-click the report specification and select “Schedule report”.


Clicking “Schedule report” brings up a wizard that looks a lot like Windows Task Scheduler. The reason it looks like Windows Task Scheduler is because you are actually creating an ordinary Windows Scheduled Task. However, if you try to look for this scheduled task in Windows, you probably will not see it. That is because Citrix was sneaky and made the scheduled task hidden. To view the schedule task in Windows, you will have to enable “View Hidden Tasks”.


Viewing Reports

To view a report, you first need to run a job. You can run a job by right-clicking on a report specification and selecting “Run report now”. Scheduled reports create jobs as well. Once a job completes, you can view the report from the “Jobs” section of Report Center. Reports can be generated in HTML format or CSV format. The default format of a report is specified in the report specification; however, you can view any report in either format via the AMC.


Modifying the Report Layout

There isn’t much to discuss about the CSV format, but I do want to show you a few things about the HTML format. By default, the HTML format report looks pretty ugly.


There are a few things we can do to make this report look better. To better understand how to modify the report, it is important to understand how the reports are generated.

The raw data behind a report is XML. A command line utility called genrep.exe is responsible for going out to the data source and generating the XML in the form of a dataset. Once the data has been retrieved, a XML style sheet transformation (XSLT) is applied to produce the resulting HTML. The XSLT files are stored in:

%ProgramFiles%\Common Files\Citrix\Access Management Console – Report Center\Reports\ConfigurationLoggingReport

There are some common and language specific transforms here. The simplest way to style the report is to modify ConfigurationLoggingReportHTML.xslt. Here is a screen shot of a report generated with a modified transform:


This concludes our look at “out of the box” capabilities. Even though we were talking mainly about Configuration Logging reporting, most of this information also applies to other reports in Report Center. In the next posts, we will explore the back end database and how to do some custom reporting.

Digging in to Citrix Configuration Logging: Setting up the Citrix XenApp farm for Configuration Logging

This is the third part in a series on Citrix XenApp Configuration Logging. This part will show you how to configure your Citrix XenApp farm for Configuration Logging, what all the settings mean, what happens when you configure your farm for logging, what happens when things go wrong, and more.

This is the third part in the Citrix Configuration Logging Series.  In part 1, we discussed what Citrix Configuration Logging was.  In part 2, we discussed how to prepare the database to log configuration changes.  In this part, we will discuss how to set up the Citrix XenApp farm to use the database and what happens under the covers when we do this.

Configuring the Citrix XenApp Farm to use the Database

You use the Access Management Console to configure the XenApp farm for Configuration Logging.  Configuration Logging is a farm setting, so once you open the Access Management Console, simply right-click your farm name and select “Properties”.  Select “Configuration Logging” from the Farm-wide properties.


Now, we need to point our farm to the database we created before.  To do this, click the “Configure Database…” button to start the database configuration wizard.


The screen shot above is pretty self-explanatory, but here are a couple of tips:

  • Even though there is a drop down next to the “Server name” box, the discovery does not always work.  I suggest just typing in the database server name or IP address.
  • Be sure to specify server\instance if you are not using the default database instance.
  • If using Windows integrated security, type domain\username in the “User name” field
  • Keep in mind that the username and password is saved in the data store.  So, be sure that the password does not expire, or remember to change this when the password does expire.
  • Discovery does not work well with the database name on the next step either.  Again, you will most likely have to type in the database name.


The screen shot above shows a lot of settings, but there is not a lot of explanation of what these settings do.  Remember, Configuration Logging is built on top of ADO.NET.  In order to make sense of these settings, you can look at ADO.NET properties.  So, here ya go:

  • Connection time-out (seconds) – amount of time to wait for a command to execute.  If a database write command cannot execute in 20 seconds, you’ve got a problem.
  • Packet size (bytes) – the size of the network packet.  8192 is the default.  This value can be anywhere from 512 to 32767.
  • Use encryption – more on this in a minute…
  • Connection pooling enabled – connection pooling is just like session sharing.  Building up and tearing down database connections can be an expensive process.  Connection pooling allows a connection to stay up for an amount of time before closing just in case another database request comes in.  If another database request comes in before the time out, the request will use the same connection.
  • Minimum pool size – specifies the minimum number of connections to maintain in a pool.  If you set this number to 3, for example, ADO.NET would create 3 connections the first time you connect to the server. Zero is the ADO.NET default.
  • Maximum pool size – maximum number of connections in a pool.  100 is the ADO.NET default.
  • Connection lifetime (seconds) – specifies the maximum age of connections. If a connection has been open for more than this number of seconds when you call its Close() or Dispose() method, it will be destroyed rather than being returned to the pool. Zero is the ADO.NET default, which means that connections are kept in the pool regardless of age.
  • Connection reset – specifies whether the database connection is reset when being removed from the pool.  True is the ADO.NET default.
  • Enlist – specifies whether to enlist this connection into a current transaction context of the creation thread.  In other words, if this is set to true and the database server is doing some transactions, let the connection use the already generated transaction.  True is the ADO.NET default.

Almost all of those defaults are just great.  The only one you need to be careful about is the “Use encryption” option.  This option is set to “Yes” by default.  But, in order to use Configuration Logging encryption, you must be using IMA encryption.  If you are not using IMA encryption, you cannot use Configuration Logging encryption.  You will get this nasty undescriptive error when you test the connection if there is a mismatch:


For information on how to setup IMA encryption, check out the Citrix XenApp documentation.

Configuring the Citrix XenApp farm to Log Changes

Now that we have the farm configured to point to the database, we have some options on how to log changes.  Remember this screen shot?


This is pretty easy, there are only 3 checkboxes:

  • Log administrative tasks to logging database – this is what tells the IMA service to use the CitrixLogServer.dll hook to log changes explained in part 1.
  • Allow changes to the farm when database is disconnected – this is self explanatory.
  • Require administrators to enter database credentials before clearing the log – “the log” referred to in this option is all the data in the database.  An administrator can clear the log by opening the AMC, right-clicking on the farm name – > All Tasks –> Clear configuration log.

If you do not allow changes to be made to your farm and your Configuration Logging database is offline, you will get the following error message when trying to make a change:


Wow – that error message is actually pretty descriptive!

Note – even if you do not allow changes to be made to your Citrix XenApp farm when the Configuration Logging database cannot be reached, you can still change which database your farm uses.  That means if you are trying to make a change and your database took a dive and it doesn’t look like it will be back up anytime soon, you can always change which database logs the changes and carry on.  Of course, changing which database logs changes gets logged <- say that 5 times fast…

Adjusting Database Permissions

As you may recall, when we created the data base user in part 2, we had to make sure the database user belonged to the db_owner role.  This is due to the fact when the XenApp farm connects to the database, the schema is checked.  If the schema does not exit, it is created – which requires db_owner rights.  So, after that first connection, you can dial back the permissions.  Here are the minimum operating permissions:

Configuration Logging Task Database permissions needed
To create log entries in the database tables INSERT for the database tables,
EXECUTE for the stored procedures, and
SELECT for sysobjects and sysusers (SQL Server) or sys.all_objects (Oracle)

(Oracle also requires SELECT for sequence objects and the create session system privilege)

To clear the log DELETE/INSERT for the database tables,
EXECUTE for the GetFarmData stored procedure, and
SELECT for sysobjects and sysusers (SQL Server)
or sys.all_objects (Oracle) (Oracle also requires SELECT for sequence objects and the create session system privilege)
To create a report EXECUTE for the Citrix Configuration Logging
stored procedures
SELECT for sysobjects and sysusers (SQL Server) or sys.all_objects (Oracle)
(Oracle also requires the create session system


Delegated Administration

Delegated administration is supported to an extent.  It is basically an on or off thing.  It is a good idea to make sure administrators have to enter credentials to clear the log as well.