Blog

User Session Script Collecting Custom Metrics (Citrix ICA RTT)

uberAgent is often used in conjunction with Universal Forwarder, Splunk’s generic agent that monitors logs and collects the output from custom scripts. The combination of the two agents is a powerful one, as it allows customers to add any metric they require to uberAgent’s already rich dataset.

However, running two agents side by side has drawbacks, too: the administrative overhead increases as do the hardware resources required on the endpoints.

As of uberAgent 4.1 there exists an attractive alternative: what started out with the intention of providing a way of collecting custom metrics from individual user sessions turned into a generic script execution engine. It runs any type of script at any desired interval, either per machine or per user session.

Overview: How to Configure Custom Script Execution

The execution of custom scripts is handled by uberAgent’s endpoint agent. Scripts are configured as part of timer stanzas in uberAgent’s configuration. The following lists the relevant configuration options:

#   Setting name: Name
#   Description: Arbitrary name for the timer.
#   Valid values: any string
#   Default: empty
#   Required: yes
#
#   Setting name: Interval
#   Description: How long to wait before collecting data again. Unit: milliseconds.
#   Valid values: any number
#   Default: [none]
#   Required: yes
#
#   Setting name: Script
#   Description: Run a script once or periodically, depending on the configured Interval (0 = run only once). The script's output to stdout is sent to Splunk, each line as a new event. Can be specified more than once per timer.
#   Valid values: Any valid command line, optionally including command line parameters.
#   Default: empty
#   Required: no
#
#   Setting name: ScriptContext
#   Description: The user context to run a script in.
#   Valid values: Session0AsSystem | UserSessionAsSystem | UserSessionAsUser
#   Default: Session0AsSystem
#   Required: no

Please note that the uberAgent service on the endpoint is running in the context of LocalSystem, so the referenced script must be accessible by and executable to the LocalSystem account. This is particularly relevant when running scripts stored on a network file share.

The Script

You can use any script written in your preferred scripting language, e.g. PowerShell or VBScript. Our agent will capture all script output sent to standard output (stdout), i.e. printed to the console. Every line of output is sent as its own event to the backend. Script output must be formatted as key-value pairs (e.g. key=value).

Please keep in mind that any data collected in addition to our default dataset has an impact on the generated data volume. Running custom scripts generates additional load on the endpoint the amount of which depends on the executed process (e.g. powershell.exe or cscript.exe) and the underlying data source. Especially Windows Management Instrumentation (WMI) can cause a significant load.

Additionally, please choose an appropriate timer interval for your script. Data that does not change often, like inventory information, probably only needs to be collected once a day whereas volatile metrics like network throughput might have to be collected once per minute.

uberAgent does not manage the deployment process of custom scripts to the endpoints. Please feel free to use either your existing software distribution system or Splunk’s Deployment Server.

The Script Context

Custom scripts can be executed in three different contexts:

  • Session0AsSystem: the script runs in session 0 as LocalSystem
  • UserSessionAsSystem: the script runs in every interactive user session as LocalSystem
  • UserSessionAsUser: the script runs in every interactive user session as the user logged on to the session

The script context is configured per timer. Of course, you can configure multiple timers for independent execution of different scripts.

Example: Querying WMI Data Using a PowerShell Script

This example shows how to collect the ICA RTT metric in every user session by way of a custom script running every 30s. The ICA protocol round trip time (RTT) is an important metric supplementing uberAgent’s remoting protocol latency in Citrix XenApp / XenDesktop environments. You can find a detailed description of the ICA RTT metric here.

The following PowerShell script queries the ICA RTT as a property of a WMI class:

$Citrix_Euem_RoundTrip = Get-WmiObject -Namespace root\Citrix\euem -Class Citrix_Euem_RoundTrip
$CurrentSessionID = [System.Diagnostics.Process]::GetCurrentProcess().SessionId

foreach ($Session in $Citrix_Euem_RoundTrip)
{
   if ($Session.SessionID -eq $CurrentSessionID)
   {
      [Hashtable]$Output = @{
         'RoundtripTime'=$($Session.RoundtripTime) 
         'SessionID'=$($Session.SessionID)
         'SessionUser'=[System.Security.Principal.WindowsIdentity]::GetCurrent().Name
      }
      Write-Output $($Output.Keys.ForEach({"$_=$($Output.$_)"}) -join ' ')
   }
}

All properties (SessionUser, SessionID and RoudtripTime) are written to stdout as key-value pairs:

SessionUser=AD\timmtest02 SessionID=5 RoundtripTime=28

This script (named Citrix_Euem_RoundTrip.ps1) is located in the %ProgramFiles%\vast limits\uberAgent\Scripts directory on the endpoint.

I configured the script execution as follows in uberAgent’s configuration:

############################################
# Timer 10
############################################
[Timer]
Name           = PowerShell Citrix Euem RoundTrip
Interval       = 30000
Script         = powershell.exe -executionpolicy bypass -file "C:\Program Files\vast limits\uberAgent\Scripts\Citrix_Euem_RoundTrip.ps1"
ScriptContext  = UserSessionAsUser

As you can see, this script is executed every 30 seconds (30,000 milliseconds) as user inside every interactive session.

The Splunk search results look as follows:

By default, all collected data is sent to the Splunk index uberagent. The Splunk sourcetype used for the script’s output is a concatenation of uberAgent:Script: and the timer name specified in uberAgent’s configuration.

Comments (2)

  1. Jeremy Cooper says:

    Hi Timm,
    My question is around additional user / session data that is also collected in conjunction with the script outputs.
    I see from the screenshot that the host event is captured, is there any other data that is also captured or that would allow this to be correlated? E.g. Session GUID or username?
    I do see a way of including the username as an output from the script for creating a correlation in SPLUNK.
    I haven’t implement the script yet to see everything that would be returned as this blog post outlines.

    Thanks again for your and Helge’s work on this product.

    Jeremy

    1. Hi Jeremy,

      I updated the PowerShell example code to reflect your requirements.
      Now the SessionUser is written to stdout in addition to the SessionID and the RoundtripTime, which makes a lot of sense.

      Thanks, Timm

Leave a Reply

Your email address will not be published. Required fields are marked *