iControl Apps - #11 - Global GTM Statistics

Continuing on with my series of applications on system level statistics, this application will look into the insides of the GTM processes on the system and dump out the available statistics exposed in the System.Statistics.get_gtm_global_statistics() method.

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()
{
  Write-Host "Usage: GlobalGTMStats.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-GTMStatistics function is called to query the GTM 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;
}

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

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

Querying GTM Statistics

The system level GTM statistics include some fun data that is not easily accessed outside of the iControl API methods.  The code below makes the call to the get_gtm_global_statistics() method in the System.Statistics interface.  This returns a SystemStatistics structure that contains the timestamp for the statistics snapshot along with an array of StatisticEntry structures, each containing the type and value for each specific statistic.  The code loops over that array and dynamically adds them to the stat_obj object.  When the loop is complete and all the statistics have been added to the object, the stats_obj object is passed through the PowerShell pipeline to the Format-List Cmdlet to allow for some nice columnar formatting.

function Get-GTMStatistics()
{
  param($subset = $null);
  if ( $subset -eq $null ) { $subset = "all"; }
 
  Write-Host "GTM Statistics"
 
  $GTMStatistics = (Get-F5.iControl).SystemStatistics.get_gtm_global_statistics();
  $t = Get-TimeFromTimeStamp $GTMStatistics.time_stamp;
 
  $stat_obj = New-Object -TypeName System.Object;
 
  $stat_obj | Add-Member -Type noteProperty -Name "Time Stamp" $t;
  $stat_obj | Add-Member -Type noteProperty -Name "--------------------------------" "";
 
  $Statistics = $GTMStatistics.statistics;
 
  foreach($Statistic in $Statistics)
  {
    $val = Convert-To64Bit $Statistic.value.high $Statistic.value.low;
    switch ($Statistic.type)
    {
      "STATISTIC_GTM_WIDEIP_REQUESTS" {
        $label = "Wideip - Requests"
      }
      "STATISTIC_GTM_WIDEIP_RESOLUTIONS" {
        $label = "Wideip - Resolutions"
      }
      "STATISTIC_GTM_WIDEIP_PERSISTED" {
        $label = "Wideip - Persisted Resolutions "
      }
      "STATISTIC_GTM_WIDEIP_PREFERRED_LB_METHODS" {
        $label = "Wideip - Preferred LB Method Count"
      }
      "STATISTIC_GTM_WIDEIP_ALTERNATE_LB_METHODS" {
        $label = "Wideip - Alternate LB Method Count"
      }
      "STATISTIC_GTM_WIDEIP_FALLBACK_LB_METHODS" {
        $label = "Wideip - Fallback LB Method Count"
      }
      "STATISTIC_GTM_WIDEIP_DROPPED_CONNECTIONS" {
        $label = "Wideip - Dropped Connections"
      }
      "STATISTIC_GTM_WIDEIP_EXPLICIT_IP" {
        $label = "Wideip - Defaulted back to Explicit IP"
      }
      "STATISTIC_GTM_WIDEIP_RETURN_TO_DNS" {
        $label = "Wideip - Resolutions defaulted to DNS"
      }
      "STATISTIC_GTM_IQUERY_RECONNECTS" {
        $label = "iQuery - Number of Reconnects"
      }
      "STATISTIC_GTM_IQUERY_RECEIVED_BYTES" {
        $label = "iQuery - Received Bytes"
      }
      "STATISTIC_GTM_IQUERY_SENT_BYTES" {
        $label = "iQuery - Sent Bytes"
      }
      "STATISTIC_GTM_BACKLOGGED_SENDS" {
        $label = "Backlogged Sends"
      }
      "STATISTIC_GTM_DROPPED_BYTES" {
        $label = "Dropped Bytes"
      }
      "STATISTIC_GTM_TOTAL_LDNSES" {
        $label = "Number of Local DNSes"
      }
      "STATISTIC_GTM_TOTAL_PATHS" {
        $label = "Number of Paths"
      }
      default {
        $type = $Statistic.type;
        Write-Error "Label '$type' not found"
      }
    }
    #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;
}

Usage

By passing in the BIG-IP address, username, and password, the application displays the following values for my 6400 running BIG-IP v9.4.5.

PS C:\> .\GlobalGTMStatistics.ps1 bigip_address username password
GTM Statistics

Time Stamp                             : 9/25/2008 1:16:40 PM
--------------------------------       :
Wideip - Requests                      : 0
Wideip - Resolutions                   : 0
Wideip - Persisted Resolutions         : 0
Wideip - Preferred LB Method Count     : 0
Wideip - Alternate LB Method Count     : 0
Wideip - Fallback LB Method Count      : 0
Wideip - Dropped Connections           : 0
Wideip - Defaulted back to Explicit IP : 0
Wideip - Resolutions defaulted to DNS  : 0
iQuery - Number of Reconnects          : 0
iQuery - Received Bytes                : 0
iQuery - Sent Bytes                    : 0
Backlogged Sends                       : 0
Dropped Bytes                          : 221430
Number of Local DNSes                  : 0
Number of Paths                        : 0

Conclusion

The System.Statistics interface has a bunch of hidden nuggets of fun and interesting data. While my system doesn't have an active GTM setup, the data is mostly zeros, but for an active system, knowing how GTM is performing at a high level can be an important part of your management strategy.

For the full script, check it PsSystemGtmStats in the iControl CodeShare.