Grafana-based GUI for mgstat, a system monitoring tool for InterSystems Caché, Ensemble or HealthShare

/// This class is an object-oriented implementation of ^mgstat routine.
/// Unlike the last the Caché version check is skipped.
/// If you want to monitor seizes you should set parameter ISSEIZEGATHERED = 1.
/// Unlike ^mgstat routine Seizes metrics show as diff (not as percentage).
/// Some of $zutil functions are unknown for me, but they are used in ^mgstat so they're leaved here.
Class my.Metrics Extends %RegisteredObject
{

/// Metrics prefix
Parameter PREFIX = "isc_cache_mgstat_";

/// Metrics for Prometheus must be divided by 'new line'
Parameter NL As COSEXPRESSION = "$c(10)";

/// Unknown parameter -). Used as in ^mgstat.int
Parameter MAXVALUE = 1000000000;

/// 2**64 - 10. Why minus 10? It's a question -) Used as in ^mgstat.int
Parameter MAXVALGLO = 18446744073709551610;

/// Resources that we are interested to monitor. You can change this list
Parameter SEIZENAMES = "Global,ObjClass,Per-BDB";

/// Default value - $zutil(69,74). You can start gather seize statistics it by setting "1"
Parameter ISSEIZEGATHERED = 0;

Parameter MAXECPCONN As COSEXPRESSION = "$system.ECP.MaxClientConnections()";

/// Number of global buffers types (8K, 16K etc.)
Parameter NUMBUFF As COSEXPRESSION = "$zutil(190, 2)";

/// Memory offset (for what? -))
Parameter WDWCHECK As COSEXPRESSION = "$zutil(40, 2, 146)";

/// Memory offset for write daemon phase
Parameter WDPHASEOFFSET As COSEXPRESSION = "$zutil(40, 2, 145)";

/// Memory offset for journals
Parameter JOURNALBASE As COSEXPRESSION = "$zutil(40, 2, 94)";

ClassMethod getSamples(delay As %Integer = 2) As %Status
{
    set sc = $$$OK
    try {
        set sc = ..gather(.oldValues)
        hang delay
        set sc = ..gather(.newValues)
        set sc = ..diff(delay, .oldValues, .newValues, .displayValues)
        set sc = ..output(.displayValues)
    } catch e {
        write "Error: "_e.Name_"_"_e.Location, ..#NL
    }
    quit sc
}

ClassMethod gather(Output values) As %Status
{
    set sc = $$$OK
    
    // Get statistics for globals
    set sc = ..getGlobalStat(.values)
    
    // Get write daemon statistics
    set sc = ..getWDStat(.values)
    
    // Get journal writes
    set values("journal_writes") = ..getJournalWrites()
    
    // Get seizes statistics
    set sc = ..getSeizeStat(.values)
    
    // Get ECP statistics
    set sc = ..getECPStat(.values)
    
    quit sc
}

ClassMethod diff(delay As %Integer = 2, ByRef oldValues, ByRef newValues, Output displayValues) As %Status
{
    set sc = $$$OK
    
    // Process metrics for globals
    set sc = ..loopGlobal("global", .oldValues, .newValues, delay, 1, .displayValues)
    
    set displayValues("read_ratio") = $select(
        displayValues("physical_reads") = 0: 0,
        1: $number(displayValues("logical_block_requests") / displayValues("physical_reads"),2)
    )
    set displayValues("global_remote_ratio") = $select(
        displayValues("remote_global_refs") = 0: 0,
        1: $number(displayValues("global_refs") / displayValues("remote_global_refs"),2)
    )
    
    // Process metrics for write daemon (not per second)
    set sc = ..loopGlobal("wd", .oldValues, .newValues, delay, 0, .displayValues)
    
    // Process journal writes
    set displayValues("journal_writes") = ..getDiff(oldValues("journal_writes"), newValues("journal_writes"), delay)
    
    // Process seize metrics
    set sc = ..loopGlobal("seize", .oldValues, .newValues, delay, 1, .displayValues)
    
    // Process ECP client metrics
    set sc = ..loopGlobal("ecp", .oldValues, .newValues, delay, 1, .displayValues)
    set displayValues("act_ecp") = newValues("act_ecp")
    
    quit sc
}

ClassMethod getDiff(oldValue As %Integer, newValue As %Integer, delay As %Integer = 2) As %Integer
{
    if (newValue < oldValue) {
        set diff = (..#MAXVALGLO - oldValue + newValue) \ delay
        if (diff > ..#MAXVALUE) set diff = newValue \ delay
    } else {
        set diff = (newValue - oldValue) \ delay
    }
    quit diff
}

ClassMethod loopGlobal(subscript As %String, ByRef oldValues, ByRef newValues, delay As %Integer = 2, perSecond As %Boolean = 1, Output displayValues) As %Status
{
    set sc = $$$OK
    
    set i = ""
    for {
        set i = $order(newValues(subscript, i)) 
        quit:(i = "")
        if (perSecond = 1) {
            set displayValues(i) = ..getDiff(oldValues(subscript, i), newValues(subscript, i), delay)
        } else {
            set displayValues(i) = newValues(subscript, i)
        }
    }
    
    quit sc
}

ClassMethod output(ByRef displayValues) As %Status
{
    set sc = $$$OK
    set i = ""
    for {
        set i = $order(displayValues(i))
        quit:(i = "")
        write ..#PREFIX_i," ", displayValues(i),..#NL
    }
    write ..#NL
    quit sc
}

ClassMethod getGlobalStat(ByRef values) As %Status
{
    set sc = $$$OK
    
    set gloStatDesc = "routine_refs,remote_routine_refs,routine_loads_and_saves,"_
        "remote_routine_loads_and_saves,global_refs,remote_global_refs,"_
        "logical_block_requests,physical_reads,physical_writes,"_
        "global_updates,remote_global_updates,routine_commands,"_
        "wij_writes,routine_cache_misses,object_cache_hit,"_
        "object_cache_miss,object_cache_load,object_references_newed,"_
        "object_references_del,process_private_global_refs,process_private_global_updates"
        
    set gloStat = $zutil(190, 6, 1)
    
    for i = 1:1:$length(gloStat, ",") {
        set values("global", $piece(gloStatDesc, ",", i)) = $piece(gloStat, ",", i)
    }

    quit sc
}

ClassMethod getWDStat(ByRef values) As %Status
{
    set sc = $$$OK
    
    set tempWdQueue = 0 
    for b = 1:1:..#NUMBUFF { 
        set tempWdQueue = tempWdQueue + $piece($zutil(190, 2, b), ",", 10) 
    }
    
    set wdInfo = $zutil(190, 13)
    set wdPass = $piece(wdInfo, ",")
    set wdQueueSize = $piece(wdInfo, ",", 2)
    set tempWdQueue = tempWdQueue - wdQueueSize 
    if (tempWdQueue < 0) set tempWdQueue = 0
    
    set misc = $zutil(190, 4)
    set ijuLock = $piece(misc, ",", 4)
    set ijuCount = $piece(misc, ",", 5)
    
    set wdPhase = 0 
    if (($view(..#WDWCHECK, -2, 4)) && (..#WDPHASEOFFSET)) {
        set wdPhase = $view(..#WDPHASEOFFSET, -2, 4)
    }
    
    set wdStatDesc = "write_daemon_queue_size,write_daemon_temp_queue,"_
        "write_daemon_pass,write_daemon_phase,iju_lock,iju_count"
    
    set wdStat = wdQueueSize_","_tempWdQueue_","_wdPass_","_wdPhase_","_ijuLock_","_ijuCount
    
    for i = 1:1:$length(wdStat, ",") {
        set values("wd", $piece(wdStatDesc, ",", i)) = $piece(wdStat, ",", i)
    }
    
    quit sc
}

ClassMethod getJournalWrites() As %String
{
    quit $view(..#JOURNALBASE, -2, 4)
}

ClassMethod getSeizeStat(ByRef values) As %Status
{
    set sc = $$$OK
    
    set seizeStat = "", seizeStatDescList = ""
    set selectedNames = ..#SEIZENAMES
    
    set seizeNumbers = ..getSeizeNumbers(selectedNames)  // seize statistics
    set isSeizeGatherEnabled = ..#ISSEIZEGATHERED
    if (seizeNumbers = "") { 
        set SeizeCount = 0 
    } else { 
        set SeizeCount = isSeizeGatherEnabled * $length(seizeNumbers, ",") 
    }
    
    for i = 1:1:SeizeCount { 
        set resource = $piece(seizeNumbers, ",", i)
        set resourceName = ..getSeizeLowerCaseName($piece(selectedNames, ",", i))
        set resourceStat = $zutil(162, 3, resource)
        set seizeStat = seizeStat_$listbuild($piece(resourceStat, ","))
        set seizeStat = seizeStat_$listbuild($piece(resourceStat, ",", 2))
        set seizeStat = seizeStat_$listbuild($piece(resourceStat, ",", 3))
        set seizeStatDescList = seizeStatDescList_$listbuild(
            resourceName_"_seizes", resourceName_"_n_seizes", resourceName_"_a_seizes"
        )
    }
    set seizeStatDesc = $listtostring(seizeStatDescList, ",")
    
    set seizeStat = $listtostring(seizeStat, ",")
    
    if (seizeStat '= "") {
        for k = 1:1:$length(seizeStat, ",") {
            set values("seize", $piece(seizeStatDesc, ",", k)) = $piece(seizeStat, ",", k)
        }
    }
    
    quit sc
}

ClassMethod getSeizeNumbers(selectedNames As %String) As %String
{
    /// USER>write $zu(162,0)
    // Pid,Routine,Lock,Global,Dirset,SatMap,Journal,Stat,GfileTab,Misc,LockDev,ObjClass...
    set allSeizeNames = $zutil(162,0)_"," //Returns all resources names
    
    set seizeNumbers = ""
    for i = 1:1:$length(selectedNames, ",") {
        set resourceName = $piece(selectedNames,",",i)
        continue:(resourceName = "")||(resourceName = "Unused")
        set resourceNumber = $length($extract(allSeizeNames, 1, $find(allSeizeNames, resourceName)), ",") - 1
        continue:(resourceNumber = 0)
        if (seizeNumbers = "") {
            set seizeNumbers = resourceNumber
        } else {
            set seizeNumbers = seizeNumbers_","_resourceNumber
        }
    }
    quit seizeNumbers
}

ClassMethod getSeizeLowerCaseName(seizeName As %String) As %String
{
    quit $tr($zcvt(seizeName, "l"), "-", "_")
}

ClassMethod getECPStat(ByRef values) As %Status
{
    set sc = $$$OK
    
    set ecpStat = ""
    
    if (..#MAXECPCONN '= 0) {
        set fullECPStat = $piece($system.ECP.GetProperty("ClientStats"), ",", 1, 21)
        set activeEcpConn = $system.ECP.NumClientConnections()
        set addBlocks = $piece(fullECPStat, ",", 2)
        set purgeBuffersByLocal = $piece(fullECPStat, ",", 6)
        set purgeBuffersByRemote = $piece(fullECPStat, ",", 7)
        set bytesSent = $piece(fullECPStat, ",", 19)
        set bytesReceived = $piece(fullECPStat, ",", 20)
    }
    set ecpStatDesc = "add_blocks,purge_buffers_local,"_
        "purge_server_remote,bytes_sent,bytes_received"
    
    set ecpStat = addBlocks_","_purgeBuffersByLocal_","_
        purgeBuffersByRemote_","_bytesSent_","_bytesReceived
        
    if (ecpStat '= "") {
        for l = 1:1:$length(ecpStat, ",") {
            set values("ecp", $piece(ecpStatDesc, ",", l)) = $piece(ecpStat, ",", l)
        }
        set values("act_ecp") = activeEcpConn
    }
    
    quit sc
}

}

Class my.Mgstat Extends %CSP.REST
{

XData UrlMap [ XMLNamespace = "http://www.intersystems.com/urlmap" ]
{
<Routes>
<Route Url="/:delay" Method="GET" Call="getMgstat"/>
</Routes>
}

ClassMethod getMgstat(delay As %Integer = 2) As %Status
{
    // By default, we use 2 second interval for averaging
    quit ##class(my.Metrics).getSamples(delay)
}

}