%SYS.AppMetadataStack.SQL
hidden class %SYS.AppMetadataStack.SQL extends %Library.SystemBase
The %SYS.AppMetadataStack.SQL class defines the interface for processing and retrieving information from the Application Metadata Stack (AMS) for the SQL application (ApplicationID="%SQL" [WHERE "%SQL"=$$$AMSApplicationIDSQL]). The GetStackInfo() method within this class returns a snapshot of the SQL Query information that is stored on the Application Metadata Stack (AMS), and this information is used by the INFORMATION.SCHEMA.CURRENTSTATEMENTS class for its data ResultSet. The Application Metadata Stack (AMS), which is kept in shared memory, allows applications to push metadata information on the stack to define what task is being performed by the process at any given time. Information from the stack is automatically discarded when the process leaves the current frame (descending the frame stack). This information can be inspected and consumed by monitoring and profiling tools, such as ^%SS & the SMP, and reported to a user upon request. The Application Metadata Stack (AMS) is populated with a $LIST(...) string of metadata information. The elements of this metadata string, along with the position of where each element's data is stored, can be found by inspecting the positional MACROs defined within the %msql.INC file under the section entitled APPLICATION METADATA STACK (AMS) MACROs The first element of this metadata string is the AppMetadataStackID which itself is a $LIST(...) string that is comprised of two or more elements that can be used to uniquely identify each metadata string on the Application Metadata Stack (AMS). The first element of the AppMetadataStackID string is always the ApplicationID which identifies the application that pushed this metadata information onto the Application Metadata Stack (AMS) for future processing. The ApplicationID has the following values:
ApplicationID | Application Name | Description |
"%SQL" ::= $$$AMSApplicationIDSQL | SQL | All SQL Interfaces: Embedded | Dynamic | xDBC SQL generated code and related infrastructure (such as WQM and SQM) will leverage this feature to track relevant SQL metadata, such as the statement being executed and identifiers for a "parent" query in parallelized or sharded cases. |
Method Inventory
Methods
The GetStackInfo() method returns an array of SQL Query information that is stored on the Application Metadata Stack (AMS). The output array amsInfo(...) returned by this method can be further refined by either or both of the input parameters pidList and/or infoOnly. The output array amsInfo(...) is used by the INFORMATION.SCHEMA.CURRENTSTATEMENTS class for its data ResultSet. Parameters:
- pidList
- A $LIST(...) or comma-delimited string of PIDs to refine the output parameter array amsInfo(...), such that only the specified PIDs will be returned in the amsInfo(...) array
- infoOnly
- A flag to determine what is populated and returned in the output parameter array amsInfo(...):
0 - Populate and return all information nodes of the amsInfo(...) array 1 - Populate and return only the "info" node of the amsInfo(...) array
- amsInfo
- An output parameter which return a snapshot of the SQL Query information that is stored
on the Application Metadata Stack (AMS) at the time of this method's invocation.
This output array is returned with the following informational nodes:
Inline-Processing Information amsInfo(<server>,pid,sqlIndexHash,"info")=<ams info list> Master Map: Data Index Maps amsInfo(<server>,pid,sqlIndexHash,"parent")=<parent list> Only defined for Child Queries amsInfo(<server>,pid,sqlIndexHash,"childStmts")=<children list> Only defined for Parent Queries amsInfo("orderStmts")=<order list> Ordered $LIST($LB(Stand-Alone/Parent/Children-Info),...) Post-Processing Information $LIST(<ams info list>,$$$AMSSQLPPStatementOrderPos)=<Statement Order> Position within <order list> $LIST(<ams info list>,$$$AMSSQLPPStatsListPos)=<stats list> <server> ::= $LG($LG(<ams info list>,$$$AMSSQLServerInfoListPos),2) $ZU(110)_":"_$g(^%SYS("SSPort")) <ams list> ::= $SYSTEM.Process.GetAppFrameInfo(pid) For $LIST(...) details, see 'InitAMSInfo^%qaqcasl.MAC' <ams info list> ::= $LG(<ams list>,pos) All pieces of the <ams list> <stats list> ::= $LIST(...) Pieces: 1) workerCnt Number of workers currently active on behalf of this SQL Statement 2) startTS Local timestamp in $ZDT(tsH,3,1,3) format when the SQL Query started running 3) elapsedTime Elapsed time of this running SQL Query in seconds (to 3 decimal points) 4) startTSUTC UTC timestamp in $ZDT(tsH,3,1,3) format when the SQL Query started running NOTE: These pieces are elements of the positional MACRO $$$AMSSQLPPStatsListPos, each having its own SubPos NOTE: Pieces 2, 3 and 4 are based on the following value: $LG(amsInfoList,$$$AMSSQLExecutionTSPos) <parent list> ::= $LIST(...) Pieces: 1) pServer Parent's Host Information 2) pPID Parent's PID 3) pSQLIndexHash Parent's SQL Index Hash 4) cQueryRunType Child's Query Type: { Parallel | Sharded } <children list> ::= $LIST(...) of SQLIndexHash for all Children Queries <order list> ::= $LIST(...) of $LIST(...) Pieces: 1) {SA|P|CP|C} {SA = Stand-Alone | P = Parent | CP = Child & Parent | C = Child} SQL Statement 2) server SQL Statement Host Information 3) pid SQL Statement PID 4) sqlIndexHash SQL Statement Index Hash NOTE: This $LIST(...) is ordered by all Stand-Alone SQL Statements, followed by each Parent SQL Statements and its Children SQL Statements: $LIST({SA1}[,{SA2},...,{SAn}],{P1},{C1:1},...,{C1:n},[,{P2},{C2:1},...,{C2:n},...,{Pn},{Cn:1},...,{Cn:n}]) - skipShardWorkMgr
- A flag to determine whether to skip processing the Application Metadata Stack (AMS)
for Information via the ShardWorkMgr:
0 - Process the Application Metadata Stack (AMS) for Information via the ShardWorkMgr (If one exists) 1 - Skip processing the Application Metadata Stack (AMS) for Information via the ShardWorkMgr
- NOTE: This parameter is for InterSystems INTERNAL USE ONLY! This parameter is used primarily for debugging purposes in order to run this method interactively in the foreground.
- amsDebugID
- An output parameter which returns the amsDebugID node within the SQL Application Metadata Stack - Debugging Tool (AMS-DT) global if the AMS-DT is enabled; Otherwise, returns the empty string ("") which indicates that no debugging information was collected
- NOTE: This parameter is for InterSystems INTERNAL USE ONLY!
- getAllAMS
- A flag to determine if all AMS information should be collected for special internal purposes
- NOTE: This parameter is for InterSystems INTERNAL USE ONLY!
The following is an example of retrieving all of the SQL Query information that is stored on the Application Metadata Stack (AMS) into the amsInfo(...) array:
set tSC=##class(%SYS.AppMetadataStack.SQL).GetStackInfo(,,.amsInfo)