Create an Agent that Monitors a Partition Variable

The Partition Utilization agent monitors a partition's average rate over a time interval. But what if you want to monitor another aspect of a partition, such as the number of dropped packets or the amount of time (or percent of time) during which allocated bandwidth exceeded the partition minimum size? This is a job for a User Event Emulation agent based on a partition ME variable.

In this example, we will create a new agent called Partition Over Limit. This agent will monitor the partition-over-limit-time% measurement variable (the percentage of time that allocated bandwidth in a class exceeded the partition minimum size). When the class' traffic exceeds the partition minimum size more than a certain percentage of time, the adaptive response feature will alert you that a threshold has been exceeded. The standard alert is a red indicator on the info tab (PacketWise) or configuration tab (PolicyCenter). In addition, you can have an email, SNMP trap, or syslog message sent when the red threshold is crossed; this method requires that you create an action file — a text file of PacketWise commands. The action file can take other actions, as well, such as modifying the partition size, and can include any CLI command that can run without additional user input. See Action File Overviews for more information.

In order to create agents, the adaptive response feature must be enabled.

Create a New Agent

To create an agent for a partition variable:

1. On the setup tab, click the Adaptive Response Settings link.
   
   
2. Click add. The Add Agent Entry window will open.
   
   
3. Click the create a new agent from this agent template drop-down list, and choose Partition ME Variables.
   
   
4. Enter a unique identifying name for the new agent in the Name field, for example FTP Partition Over Limit.
   
   
5. Click OK and Edit Parms. This will open the Edit Agent Entry window where you can define the parameter values for your new agent.
   
   
6. In the ClassName field, enter the name of the class to be monitored (for example, Inbound/FTP). Note that the class must already have a partition defined.
   
   
7. In the MeVariableName field, enter the measurement variable to be monitored (partition-over-limit-time%). For a complete list of measurement variables you can use, see Measurement Variables; you can select any variable in the Common and Partition categories.
   
   
8. Specify the threshold values:
   
   RedThreshold — The value at which the status of the agent turns red, and a red action file is triggered, if present. For a Partition Over Limit agent, this number represents the percent of time at which bandwidth allocation exceeded the minimum partition size. For instance, if the RedThreshold is set to 60, the agent's status will change to red when the class' bandwidth allocation exceeded the minimum partition size more than 60 percent of the time in the MeDuration (see step 11 below).
   GreenThreshold — The value at which the status of the agent turns green, and a green action file is triggered, if present. For instance, if the GreenThreshold is set to 30, the agent's status will be green when the bandwidth allocation of the class exceeds the minimum partition size less than 30 percent of the time in the MeDuration.
   
   
9. If desired, change the values for GreenOperator and/or RedOperator.
   
   In this example, the values for GreenOperator (LT— less than) and RedOperator (GT— greater than) are appropriate. This agent will have a red status when the current value of the measurement variable is greater than (GT) the RedThreshold value and a green status when the current value is less than (LT) the GreenThreshold value.
   
   
10. If desired, change the evaluation interval, in minutes (how often the agent should measure its target).
    
    
11. Specify the MeDuration, the period of time over which measurements will be looked at.
    
    The MeDuration can be different from the evaluation interval. For example, suppose you set the evaluation interval to 5 minutes and the MeDuration to 60 minutes. The agent will look at the last hour of measurement data every five minutes to see if the red threshold has been exceeded. At 12:00, the agent would analyze data collected between 11:00 and 12:00; at 12:05, the agent would analyze data collected between 11:05 and 12:05; and so forth.
    
    
12. Click OK to save your changes.

After creating the agent, you will want to monitor it to see how often traffic in the class exceeded its partition minimum size.

Check the Agent Status

To check the status of the Partition Over Limit agent:

1. Click the info tab. The PacketShaper’s info tab shows an icon for each agent category, and a colored status indicator for each. The Partition Over Limit agent is in the User Event Emulation category (the last one).
   
   
2. To see the status of each individual agent in the User Event Emulation category, hover your mouse over the colored status indicator, as shown below.
   
   
   
   
3. In the pop-up window, locate the Partition Over Limit agent that you defined. The value (16 in the figure above) indicates the percent of time that bandwidth allocation in the class exceeded the partition minimum size during the MeDuration.
   
   What color is its status indicator?
   
   Green — During the MeDuration, traffic in the partition did not exceed its minimum size very often (less than the green threshold).
   Yellow — During the MeDuration, the score (the value of the measurement variable) was between the red and green thresholds.
   Red — During the MeDuration, traffic in the class exceeded its partition minimum size frequently (more than the red threshold). If the status indicator is red, you should look at the incident report for details.
   
   If the agent has ever changed status (from green/yellow to red or from red/yellow to green, a report icon with a link to a detailed report will be available for that agent.
   
   
4. If there is a report for the Partition Over Limit agent, click the report icon. The incident report appears in a separate browser window.
   
   
   
   

Create an Action File that Sends an Email Notification

If you would like to be notified by email when the class exceeds its partition minimum size too frequently (with "too frequently" being defined as the red threshold), you can create a command file that contains a single line: the send email command. By designating this command file as the red action file, an email will be sent when the red threshold is crossed.

Note: In order to send email notification, you must configure an SMTP server in PacketWise.

To create an action file that sends an email notification:

1. If the info tab is currently displayed, click the Settings link; otherwise, go to the setup tab and click the Adaptive Response Settings link.

2. Click the edit button next to the Partition Over Limit agent.

3. Click the browse files button. The File Browser window opens and shows the contents of the 9.258/agent/cmd directory (where action files need to be stored).

4. Click the new cmd file button. A command file window opens.

5. In the File Name field, enter a unique name for your action file up to eight characters long, including 0-9, a-z, AZ, -,_, and . (period). Spaces are not allowed. Example: partover

6. In the Contents area, enter the following commands:

#Title: red action file for Partition Over Limit agent
send email <address> "<subject>" ["<body>"]

where <address> is the email address of the recipient. For example:

send email raltman@test.com "FTP partition" "Bandwidth allocation in the Inbound/FTP class frequently exceeded its partition minimum."

Note: If you want to send an email notification to more than one recipient, repeat the send email command for each email address.

Alternatively, you can include the variables for the agent name, ($agentname), class name ($class-id), value of the measurement variable ($me-value), and the red threshold ($RedThreshold) in the <subject> or <body>, as the following example shows:

send email raltman@test.com "$agentname agent" "The $class-id class was over its partition minimum size $me-value percent of the time. This is over the red threshold ($RedThreshold)."

When the message is sent, the body of the email message would look something like this:

The Inbound/FTP class was over its partition minimum size 67 percent of the time. This is over the red threshold (60).

7. Click save.

8. Enter the name of your action file in the Red Action File field (for example, partover.cmd).

9. Click OK.

After the next evaluation interval, an email will be sent if and when the agent's red threshold is crossed. If you like, you can create a green action file to notify you when the Partition Over Limit agent returns to a green status.