Create an Agent that Monitors a Link Variable

The Network Health category has several agents that monitor your Inbound and Outbound links (Traffic Performance and Partition Utilization), but if you want to monitor other types of statistics on your link, you can create an agent that analyzes any link measurement variable available in PacketWise. For example, you can monitor a link's peak rate (peak-bps), percentage of retransmitted TCP packets (tcp-retx-pkts%), or percentage of refused connections (tcp-conn-server-refuses%). See Measurement Variables for a complete list.

In this example, we will create a new agent called Inbound Peak Rate. This agent will monitor the peak-bps measurement variable for the Inbound link. When the class' peak rate exceeds a user-defined threshold, 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 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 link measurement 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 Link ME Variables.
   
   
4. Enter a unique identifying name for the new agent in the Name field, for example Inbound Peak Rate.
   
   
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 link to be monitored (for example, /Inbound).
   
   
7. In the MeVariableName field, enter the measurement variable to be monitored (peak-bps). For a complete list of measurement variables you can use, see Measurement Variables; you can select any variable in the Common and Link 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 Peak Rate agent, this number represents the highest rate, in bits per second, recorded during the MeDuration (see step 11 below). For instance, if the RedThreshold is set to 500000, the agent's status will change to red when the link's peak rate is over 500 kbps in the MeDuration.
   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 300000, the agent's status will be green when the peak rate is less than 300 kbps 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 if the link's peak rate surpassed the red threshold.

Check the Agent Status

To check the status of the Peak Rate 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 Peak Rate 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 Peak Rate agent that you defined. The value (for example, 903848) indicates the link's peak rate recorded during the MeDuration.
   
   What color is its status indicator?
   
   Green — During the MeDuration, the peak on the link was at an acceptable rate (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, the peak on the link was at an unacceptable rate (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 Peak Rate 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 peak rate on a link is too high (that is, above 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 Peak Rate 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: peak

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

#Title: red action file for Peak Rate agent
send email <address> "<subject>" ["<body>"]

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

send email raltman@test.com "Inbound peak rate" "The peak rate on the Inbound link was above the red threshold."

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 peak rate of the $class-id link was $me-value bps. This is over the red threshold ($RedThreshold BPS). Go to the info tab to view the report for the $agentname agent."

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

The peak rate of the /Inbound link was 982438 BPS This is over the red threshold (900000 BPS). Go to the info tab to view the report for the Inbound Peak Rate agent."

7. Click save.

8. Enter the name of your action file in the Red Action File field (for example, peak.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 Peak Rate agent returns to a green status.