Jump to content
Welcome to our new Citrix community!

Tech Paper: Citrix Director - Manage and configure alerts and notifications with PowerShell

  • Contributed By: Allen Furmanski, Vijay Nagarajan, Gerhard Krenn

With Citrix Director, you are able to configure policies and conditions that alert you when the configured threshold is breached.
This feature was first introduced in XenDesktop 7.7 and is available today in all versions of Citrix Virtual Apps and Desktops.
This article helps you configure your proactive alerts and notifications using the PowerShell cmdlets.

Configuring the notification subscription

Let’s assume that you are a Citrix Virtual Apps and Desktops admin and you are trying to understand the usage of your deployment. You need to be proactively alerted when the number of concurrent sessions crosses a threshold value.
Before you can configure alerts and notifications, you need to configure your notification subscription. Therefore, you first need to add an SMTP Exchange server which you can use later to send emails when there is an alert.

The Set-MonitorNotificationEmailServerConfiguration POSH cmdlet helps you in configuring the SMTP server.

Look at a sample script:

    asnp Citrix.Monitor.*
    PS C:\Users\administrator> Set-MonitorNotificationEmailServerConfiguration -ProtocolType SMTP -ServerName NameOfTheSMTPServerOrIPAddress -PortNumber PortNumber -SenderEmailAddress EmailAddressFromWhichDirectorShouldSendAnEmailWhenThereIsAnAlert -RequiresAuthentication 0
    ProtocolType : SMTP
    ServerName : NameOfTheSMTPServerOrIPAddress
    PortNumber : PortNumber
    SenderEmailAddress : EmailAddressFromWhichDirectorShouldSendAnEmailWhenThereIsAnAlert
    RequiresAuthentication : False
    Credential :

    PS C:\Users\administrator> Set-MonitorNotificationEmailServerConfiguration -ProtocolType SMTP -ServerName NameOfTheSMTPServerOrIPAddress -PortNumber PortNumber -SenderEmailAddress EmailAddressFromWhichDirectorShouldSendAnEmailWhenThereIsAnAlert -RequiresAuthentication 1 -Credential “SenderEmailAddressUserNameAsPerYourExchangeServerOrAD”
    ProtocolType : SMTP
    ServerName : NameOfTheSMTPServerOrIPAddress
    PortNumber : PortNumber
    SenderEmailAddress : EmailAddressFromWhichDirectorShouldSendAnEmailWhenThereIsAnAlert
    RequiresAuthentication : False
    Credential : System.Management.Automation.PSCredential

In case your SMTP server does not require authentication, you can set the -RequiresAuthentication flag to false.

    PS C:\Users\administrator> Set-MonitorNotificationEmailServerConfiguration -ProtocolType SMTP -ServerName NameOfTheSMTPServerOrIPAddress -PortNumber PortNumber -SenderEmailAddress EmailAddressFromWhichDirectorShouldSendAnEmailWhenThereIsAnAlert -RequiresAuthentication 0
    ProtocolType : SMTP
    ServerName : NameOfTheSMTPServerOrIPAddress
    PortNumber : PortNumber
    SenderEmailAddress : EmailAddressFromWhichDirectorShouldSendAnEmailWhenThereIsAnAlert
    RequiresAuthentication : False
    Credential :

Director also supports multiple protocols to connect with your SMTP server, including SMTP, SMTP-SSL, and SMTP-TLS.

Note: You can’t remove an SMTP configuration, but you can edit it and change its value.

A sample script

Look at a sample script that helps us in creating a policy with an alert rule, parameters, conditions, and email recipients. We break each part of the script to understand more about it.

    asnp Citrix.Monitor.*
    # Add Parameters
    $timeSpan = New-TimeSpan -Seconds 30
    $alertThreshold = 1
    $alarmThreshold = 2
    # Add Target UID’s
    $targetIds = @()
    $targetIds += “0e406be1-1647-4a97-845c-7601ae1d8883”
    # Add email addresses
    $emailaddress = @()
    $emailaddress += “acme@citrix.com”
    # Create new policy
    $policy = New-MonitorNotificationPolicy -Name “MyTestPolicy” -Description “Policy created to test new cmdlets” -Enabled $true
    Add-MonitorNotificationPolicyCondition -Uid $policy.Uid -ConditionType SessionsConcurrentCount -AlertThreshold $alertThreshold -AlarmThreshold $alarmThreshold -AlertRenotification $timeSpan -AlarmRenotification $timeSpan
    Add-MonitorNotificationPolicyCondition -Uid $policy.Uid -ConditionType SessionsPeakconnectedCount -AlertThreshold $alertThreshold -AlarmThreshold $alarmThreshold -AlertRenotification $timeSpan -AlarmRenotification $timeSpan
    Add-MonitorNotificationPolicyTargets -Uid $policy.Uid -Scope “My Test Targets” -TargetKind DesktopGroup -TargetIds $targetIds
    Add-MonitorNotificationPolicyEmailAddresses -Uid $policy.Uid -EmailAddresses $emailaddress -EmailCultureName “en-US”
    $policy = Get-MonitorNotificationPolicy -Uid $policy.Uid
    $policy

Configuring recipient email addresses

Now that you’ve configured the SMTP Exchange server, you need to configure the email recipients next.

Using the Add-MonitorNotificationPolicyEmailAddresses cmdlet, you can specify the recipients of the email notification and choose the locale.

    $emailaddress = @()
    $emailaddress += “acme@citrix.com”
    Add-MonitorNotificationPolicyEmailAddresses -Uid $policy.Uid -EmailAddresses $emailaddress -EmailCultureName “en-US”

Configuring targets and target values

Now you create a policy. The first thing to do is specify a target. A target is nothing more than the entity on which the alert rule is applied.
For example, if my rule is “Alert me when the Peak Connected Session hits 100 on all the machines in my Delivery Group xyz,” then “delivery group xyz” is the target.

To specify a target and target value, you have to use the cmdlet:

    Add-MonitorNotificationPolicyTargets

Let’s suppose that you want to set the session concurrent alert on a Delivery Group for RDS machines. You have to get the DG unique identifier and supply it as a value to the Add-MonitorNotificationPolicyTargets cmdlet.

How can you get it? Use the get-brokerDesktopGroup cmdlet, and you find the unique identifier under UUID

So now we have set the target value of the Delivery Group on which we want to target our alert rule.

Next, we have to specify the target and target type. Here, we can use the Add-MonitorNotificationPolicyTargets and specify the target type as RDSWorker.

    $targetIds = @()
    $targetIds += “0e406be1-1647-4a97-845c-7601ae1d8883”
    Add-MonitorNotificationPolicyTargets -Uid $policy.Uid -Scope “My Test Targets” -TargetKind DesktopGroup -TargetIds $targetIds

We can specify the target type as RDSWorker, Site, Desktop Group (Delivery Group), or User.

In general, alert policies can be targeted at four different scopes.

  1. Site – Applies to all the machines in the entire Site, and the alert threshold applies on the aggregate value of all the machines included.

  2. Desktop Group – Applies to all the machines in the entire Delivery Group, and the alert threshold applies on the aggregate value of all the machines included.

  3. RDS Worker – Applies to all the machines in the Delivery Group, but the alert threshold value applies to individual machines.

  4. User - Applies to specific users with an alert threshold value evaluated for each user.

Configuring conditions and parameters

In the example, we wanted to set an alert rule policy for monitoring the number of sessions. There are other conditions for which you can set policies using the Add-MonitorNotificationPolicyCondition cmdlet.
You can specify a specific alert type and condition in the cmdlet by passing the appropriate value for the ConditionType parameter:

Condition Type Value Alert Type & Condition Checked
SessionsPeakConnectedCount Peak Connected Sessions - Detected when an instantaneous (one-minute sample) number of peak-connected sessions for the entire site of a particular Delivery Group exceeds a configured count threshold.
SessionsPeakDisconnectedCount Peak Disconnected Sessions - Detected when an instantaneous (one-minute sample) number of peak disconnected sessions for the entire site of a particular Delivery Group exceeds a configured count threshold.
Peak Concurrent Sessions Detected when an instantaneous (one-minute samples) number of peak concurrent (total) sessions for the entire site of a particular Delivery Group exceeds a configured count threshold.
ConnectionFailuresCount Connection Failure Count - Detected when the number of connections in a configurable time period fails across the entire site of a particular Delivery Group exceeds a configured count threshold.
ConnectionFailuresRate Connection Failure Rate - Detected when the ratio of connection failures to connection attempts in a configurable time period across the entire site of a particular Delivery Group exceeds a configured percentage threshold.
FailedDesktopMachineCount Failed Desktop OS Machines - Detected when an instantaneous (one-minute sample) number of desktop OS machines in a failure state for the entire site of a particular Delivery Group exceeds a configured count threshold.
FailedServerMachineCount Failed Server OS Machines - Detected when an instantaneous (one-minute sample) number of server OS machines in a failure state for the entire site of a particular Delivery Group exceeds a configured count threshold.
AverageLogonDuration Average Logon Duration - Detected when the average session logon time in a configurable time period across the entire site or for a particular Delivery Group exceeds a configured duration threshold.
RDSLoadEvaluator RDS Load Evaluator Index - Detected when a configured load index value is sustained for five minutes.
SessionsConcurrentCount Peak Concurrent Total Sessions - Detected when an instantaneous (one-minute sample) number of concurrent connected sessions for the entire site of a particular Delivery Group exceeds a configured count threshold.
LogonDuration Logon Duration (User) - Detected when the duration for logons for the specified user that occurred over the last hour exceeds the configured threshold.
ICARoundtripTime ICA RTT (User) - Detected when the ICA round-trip time for the specified user for even one session exceeds the configured threshold.
ICARoundtripTimeAverage ICA RTT (Average) - Detected when the average of ICA round-trip time for user sessions for an entire site or particular Delivery Group exceeds the configured threshold.
ICARoundtripTimeSessionCount ICA RTT (No. of Sessions) - Detected when the number of sessions that exceed the threshold ICA round-trip time for a particular Delivery Group exceeds.
ICARoundtripTimeSessionPercent ICA RTT (% of Sessions) - Detected when the percentage of sessions that exceed the average ICA round-trip time for a particular Delivery Group exceeds.

Note:

For greater details on the various alert types and their behaviors refer to the Alerts and notifications - Director article.

Using the Add-MonitorNotificationPolicyCondition, we can add the alarm threshold, the alert threshold, the alert and the alarm re-notification times, and the period based on the alert-type chosen.

    Add-MonitorNotificationPolicyCondition -Uid $policy.Uid -ConditionType SessionsConcurrentCount -AlertThreshold $alertThreshold -AlarmThreshold $alarmThreshold -AlertRenotification $timeSpan -AlarmRenotification $timeSpan
  • AlertThreshold – Threshold value at which the warning notification will be triggered

  • AlarmThreshold – Threshold value at which the critical notification will be triggered

  • AlertRenotification – Duration after which the warning notification will be re-triggered

  • AlarmRenotification – Duration after which the critical notification will be re-triggered

  • Period – Window in which the alert threshold condition, warning, or critical, is checked

Finally, the New-MonitorNotificationPolicy cmdlet helps you in creating a policy.


User Feedback


There are no comments to display.



Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

×
×
  • Create New...