iControl Apps - #08 - System IP Statistics

A question came across recently about how to query aggregate IP based statistics for the entire BIG-IP.  My previous tech tip covered reporting on System HTTP statistics so I thought this was a great chance to continue on that thread with another PowerShell example of system wide IP based statistics that are exposed in the System.Statistics interface.

Usage

The arguments for this application are the address, username, and password of the BIG-IP.  This is declared in the top of the script with the following param statement.  There is also a Write-Usage function to display the arguments to the user.

param (
  $g_bigip = $null,
  $g_uid = $null,
  $g_pwd = $null
);

Set-PSDebug -strict;

#-------------------------------------------------------------------------
# function Write-Usage
#-------------------------------------------------------------------------
function Write-Usage()
{
  Write-Host "Usage: GlobalIPStats.ps1 host uid pwd";
  exit;
}

Initialization

As is with all of my PowerShell scripts, the initialization component will look to see if the iControlSnapIn is loaded into the current PowerShell session.  If not, the Add-PSSnapIn Cmdlet is called to add the snapin into the runtime.  Then a call to the Initialize-F5.iControl cmdlet to setup the connection to the BIG-IP.  If this succeeds, then a call to the Get-GlobalIPStatistics function is called to query the IP Statistics and output them to the console.

function Do-Initialize()
{
  if ( (Get-PSSnapin | Where-Object { $_.Name -eq "iControlSnapIn"}) -eq $null )
  {
    Add-PSSnapIn iControlSnapIn
  }
  $success = Initialize-F5.iControl -HostName $g_bigip -Username $g_uid -Password $g_pwd;
 
  return $success;
}

if ( ($g_bigip -eq $null) -or ($g_uid -eq $null) -or ($g_pwd -eq $null) )
{
  Write-Usage;
}

if ( Do-Initialize )
{
  Get-GlobalHttpStatistics $g_subset;
}
else
{
  Write-Error "ERROR: iControl subsystem not initialized"
}

Global IP Statistics

The System.Statistics.get_IP_statistics() is the only method that's called here.  It takes no arguements and returns a System.Statistics structure containing the timestamp when the statistics were taken, along with a list of Common.Statistics structures containing the statistic type along with the 64bit values of the returned data..

To pretty up the presentation, an empty System.Object was created named stat_obj.  The statistics list is iterated upon and each of the statistics that match the subset are added as a property to the stats_obj object using Add-Member Cmdlet.  This way I can use the PowerShell Format-List CmdLet to make a nice columnar display on the console.

Once all of the statistics have been iterated through, they are written to the console by passing the stats_obj object through the PowerShell pipeline to the Format-List Cmdlet.

function Get-GlobalIPStatistics()
{
  param($subset = $null);
  if ( $subset -eq $null ) { $subset = "all"; }
 
  Write-Host "Global IP Statistics"
 
  $stat_obj = New-Object -TypeName System.Object;
 
  $SystemStatistics = (Get-F5.iControl).SystemStatistics.get_ip_statistics();
  $t = Get-TimeFromTimeStamp $SystemStatistics.time_stamp;
  $Statistics = $SystemStatistics.statistics;
 
  $stat_obj | Add-Member -Type noteProperty -Name "Time Stamp" $t;
  $stat_obj | Add-Member -Type noteProperty -Name "--------------------------------" "";

  foreach($Statistic in $Statistics)
  {
    $val = Convert-To64Bit $Statistic.value.high $Statistic.value.low;
    switch ($Statistic.type)
    {
      "STATISTIC_IP_TRANSMITTED_PACKETS" {
        $label = "Packets transmitted";
      }
      "STATISTIC_IP_RECEIVED_PACKETS" {
        $label = "Packets recieved";
      }
      "STATISTIC_IP_DROPPED_PACKETS" {
        $label = "Packets dropped";
      }
      "STATISTIC_IP_TRANSMITTED_FRAGMENTS" {
        $label = "Fragments transmitted";
      }
      "STATISTIC_IP_DROPPED_TRANSMITTED_FRAGMENTS" {
        $label = "Fragments dropped on transmit";
      }
      "STATISTIC_IP_RECEIVED_FRAGMENTS" {
        $label = "Fragments recieved";
      }
      "STATISTIC_IP_DROPPED_RECEIVED_FRAGMENTS" {
        $label = "Fragments dropped on receive";
      }
      "STATISTIC_IP_REASSEMBLED_PACKETS" {
        $label = "Packets reassembled";
      }
      "STATISTIC_IP_INVALID_CHECKSUM_ERRORS" {
        $label = "Errors - Invalid checksum";
      }
      "STATISTIC_IP_INVALID_LENGTH_ERRORS" {
        $label = "Errors - Invalid length";
      }
      "STATISTIC_IP_MEMORY_ERRORS" {
        $label = "Errors - Memory";
      }
      "STATISTIC_IP_RETRANSMITTED_ERRORS" {
        $label = "Errors - Retransmitted";
      }
      "STATISTIC_IP_INVALID_PROTOCOL_ERRORS" {
        $label = "Errors - Invalid protocol";
      }
      "STATISTIC_IP_OPTIONS_ERRORS" {
        $label = "Errors - Options";
      }
      "STATISTIC_IP_REASSEMBLED_TOO_LONG_ERRORS" {
        $label = "Errors - Reassembly";
      }
    }
    #Write-Host "$label : $val"
    $stat_obj | Add-Member -Type noteProperty -Name $label $val;
  }
  $stat_obj | format-list
}

Utility functions

Several utility functions are included as well that will do the 64 bit math conversion as well as converting the iControl TimeStamp structure to a .Net DateTime.

function Get-TimeFromTimeStamp()
{
  param ($TimeStamp);
  $dt = new-object -typename System.DateTime
  $dt = $dt.AddYears($TimeStamp.year-1).AddMonths($TimeStamp.month-1).AddDays($TimeStamp.day-1);
  $dt = $dt.AddHours($TimeStamp.hour).AddMinutes($TimeStamp.minute).AddSeconds($TimeStamp.second);
  return $dt;
}

function Convert-To64Bit()
{
  param($high, $low);
  return ($high*[Math]::Pow(2,32)) + $low;
}

Running the Application

The following example shows my somewhat idle BIG-IP's statistics.  While these are not very exciting, the numbers you are likely to see will be more interesting depending on the activity of your device.

PS C:\> .\GlobalIPStats.ps1 bigip_address username password
Global IP Statistics

Time Stamp                       : 8/29/2008 4:39:58 AM
-------------------------------- :
Packets transmitted              : 33616926
Packets recieved                 : 33795620
Packets dropped                  : 22059
Fragments transmitted            : 0
Fragments dropped on transmit    : 0
Fragments recieved               : 0
Fragments dropped on receive     : 0
Packets reassembled              : 0
Errors - Invalid checksum        : 0
Errors - Invalid length          : 0
Errors - Memory                  : 0
Errors - Retransmitted           : 0
Errors - Invalid protocol        : 0
Errors - Options                 : 0
Errors - Reassembly              : 0

Conclusion

Now you've got two sets of system statistics under you belt, I'm sure you are craving some more so stay tuned for further examples illustrating the various other system level statistics exposed in the System.Statistics iControl interface.

A link to the full sample application can be found at PsSystemIpStats in the iControl CodeShare.