This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?

%SYS.PTools.Stats

persistent class %SYS.PTools.Stats extends %Library.Persistent

SQL Table Name: %SYS_PTools.Stats

This class is designed to gather performance statistics for any type of routine or code block.

The data for this class is stored in ^%SYS.PTools.Stats, ^%SYS.PTools.StatsD and ^%SYS.PTools.StatsI. These globals default to the %SYS NameSpace, you might want to map them to a different NameSpace to avoid filling %SYS.

By calling pairs of the Start() and Stop() methods we will record GlobalRef, commands executed, TotalTime, and some process info for each code block.

You need to manually add the calls to the Start() and Stop() methods to your code.

Each method takes 3 parameters: Namespace - Current namespace the code is being executed in RoutineName - Name of the routine you are gathering stats for ModuleName - Name of the sub block with a given routine, Defaults to 1

For example when the code below is executed we will put three entries into the %SYS_PTools.Stats table, one for each call to Stop().

  Test	;
  	DO ##class(%SYS.PTools.Stats).Start("Samples","Test","Full Routine")
  	DO ##class(%SYS.PTools.Stats).Start("Samples","Test","Part 1")
  	
  	DO ##class(Sample.Person).Populate(1000)
  	
  	DO ##class(%SYS.PTools.Stats).Stop("Samples","Test","Part 1")
  	DO ##class(%SYS.PTools.Stats).Start("Samples","Test","Part 2")
  	
  	DO ##class(Sample.Person).PrintPersons()
  	
  	DO ##class(%SYS.PTools.Stats).Stop("Samples","Test","Part 2")
  	DO ##class(%SYS.PTools.Stats).Stop("Samples","Test","Full Routine")
  	QUIT
  
  

Property Inventory

Method Inventory

Properties

property Counter as %Integer;
This is the number of times the query has been run since the last compile.
Property methods: CounterDisplayToLogical(), CounterGet(), CounterGetStored(), CounterIsValid(), CounterLogicalToDisplay(), CounterNormalize(), CounterSet()
property DiskWait as %Integer;
Number of Milliseconds spent waiting for Disk reads in this Module for the given query the Modules are nested and the count for the outer ones is cumulative
Property methods: DiskWaitDisplayToLogical(), DiskWaitGet(), DiskWaitGetStored(), DiskWaitIsValid(), DiskWaitLogicalToDisplay(), DiskWaitNormalize(), DiskWaitSet()
property ExeName as %String;
Name of the executable that ran this query
Property methods: ExeNameDisplayToLogical(), ExeNameGet(), ExeNameGetStored(), ExeNameIsValid(), ExeNameLogicalToDisplay(), ExeNameLogicalToOdbc(), ExeNameNormalize(), ExeNameSet()
property GlobalRefs as %Integer;
How many global references were done in this Module for the given query the Modules are nested and the count for the outer ones is cumulative
Property methods: GlobalRefsDisplayToLogical(), GlobalRefsGet(), GlobalRefsGetStored(), GlobalRefsIsValid(), GlobalRefsLogicalToDisplay(), GlobalRefsNormalize(), GlobalRefsSet()
property IPAddress as %String;
IP Address of the machine that ran this query
Property methods: IPAddressDisplayToLogical(), IPAddressGet(), IPAddressGetStored(), IPAddressIsValid(), IPAddressLogicalToDisplay(), IPAddressLogicalToOdbc(), IPAddressNormalize(), IPAddressSet()
property LinesOfCode as %Integer;
How many lines of COS code were executed in this Module for the given query the Modules are nested and the count for the outer ones is cumulative
Property methods: LinesOfCodeDisplayToLogical(), LinesOfCodeGet(), LinesOfCodeGetStored(), LinesOfCodeIsValid(), LinesOfCodeLogicalToDisplay(), LinesOfCodeNormalize(), LinesOfCodeSet()
property MachineName as %String;
Name of the machine that ran this query
Property methods: MachineNameDisplayToLogical(), MachineNameGet(), MachineNameGetStored(), MachineNameIsValid(), MachineNameLogicalToDisplay(), MachineNameLogicalToOdbc(), MachineNameNormalize(), MachineNameSet()
property ModuleCount as %String;
Number of times we entered this module for the run of the query Used only by Sub class
Property methods: ModuleCountDisplayToLogical(), ModuleCountGet(), ModuleCountGetStored(), ModuleCountIsValid(), ModuleCountLogicalToDisplay(), ModuleCountLogicalToOdbc(), ModuleCountNormalize(), ModuleCountSet()
property ModuleName as %String;
Sections of the SQL statement, these should match up the the Module names in the Query Plan output When used with this class it can be used to distinguish block of code within a give routine this will default to 1 if nothing is provided
Property methods: ModuleNameDisplayToLogical(), ModuleNameGet(), ModuleNameGetStored(), ModuleNameIsValid(), ModuleNameLogicalToDisplay(), ModuleNameLogicalToOdbc(), ModuleNameNormalize(), ModuleNameSet()
property Pid as %String;
OS level Process ID
Property methods: PidDisplayToLogical(), PidGet(), PidGetStored(), PidIsValid(), PidLogicalToDisplay(), PidLogicalToOdbc(), PidNormalize(), PidSet()
property RoutineInfo as %String;

Contains the NameSpace and Routine these stats are for The format is NameSpace|RoutineName This is not used in the %SYS.PTools.SQLStats class

Property methods: RoutineInfoDisplayToLogical(), RoutineInfoGet(), RoutineInfoGetStored(), RoutineInfoIsValid(), RoutineInfoLogicalToDisplay(), RoutineInfoLogicalToOdbc(), RoutineInfoNormalize(), RoutineInfoSet()
property RowCount as %Integer;
How many rows did the query return for this run Used only by Sub class
Property methods: RowCountDisplayToLogical(), RowCountGet(), RowCountGetStored(), RowCountIsValid(), RowCountLogicalToDisplay(), RowCountNormalize(), RowCountSet()
property StartTime as %TimeStamp;
TimeStamp of when the query was run
Property methods: StartTimeDisplayToLogical(), StartTimeGet(), StartTimeGetStored(), StartTimeIsValid(), StartTimeLogicalToDisplay(), StartTimeNormalize(), StartTimeOdbcToLogical(), StartTimeSet()
property TimeToFirstRow as %Numeric;
How much time was spent finding the first row This is only set for Module Main
Property methods: TimeToFirstRowDisplayToLogical(), TimeToFirstRowGet(), TimeToFirstRowGetStored(), TimeToFirstRowIsValid(), TimeToFirstRowLogicalToDisplay(), TimeToFirstRowNormalize(), TimeToFirstRowSet()
property TotalTime as %Float;
How much time was spent in this Module for the given query the Modules are nested and the count for the outer ones is cumulative
Property methods: TotalTimeDisplayToLogical(), TotalTimeGet(), TotalTimeGetStored(), TotalTimeIsValid(), TotalTimeLogicalToDisplay(), TotalTimeNormalize(), TotalTimeSet()
property UserName as %String [ InitialExpression = $UserName ];
Cache UserName of the person who ran this query
Property methods: UserNameDisplayToLogical(), UserNameGet(), UserNameGetStored(), UserNameIsValid(), UserNameLogicalToDisplay(), UserNameLogicalToOdbc(), UserNameNormalize(), UserNameSet()

Methods

classmethod LogHeader(File, version)
This is the header row that will be in the output file. The columns should be comma delimited
classmethod LogSave(NS, Rou, Mod, Counter, ST, Grefs, LoC, TTime, User, Machine, IP, Exe, LogFile)
classmethod Report(FileName="")
Generates a comma delimited file containing the data from the %SYS_PTools.Stats table By default the file will be created in the mgr directory of the Cache Instantance You can pass in a value for FileName if you want to override the default
classmethod Start(NS As %String, Rou As %String, Mod As %String = 1)
called to start the counters for gather stats
classmethod Stop(NS As %String, Rou As %String, Mod As %String = 1)
Called to stop the counter for gather stats INSERT a row into %SYS_PTools.Stats table

Indexes

index (IDKEY on ) [IdKey, Type = key];
Index methods: IDKEYCheck(), IDKEYDelete(), IDKEYExists(), IDKEYOpen(), IDKEYSQLCheckUnique(), IDKEYSQLExists(), IDKEYSQLFindPKeyByConstraint(), IDKEYSQLFindRowIDByConstraint()

Inherited Members

Inherited Methods

Storage

Storage Model: CacheStorage (%SYS.PTools.Stats)

^%SYS.PTools.StatsD(ID)
=
%%CLASSNAME
ModuleName
Counter
RowCount
GlobalRefs
LinesOfCode
TotalTime
StartTime
UserName
IPAddress
MachineName
ExeName
ModuleCount
NameSpace
RoutineInfo
TimeToFirstRow
Pid
DiskWait

Subclasses

Feedback