ST05: Application Programming Interface

[ManfredMensch]

After a little more than one year I am now adding one more blog post to my series Use ST05 to Analyze the Communication of the ABAP Work Process with External Resources. All previous blog posts in this sequence have assumed that you work interactively with dialog transaction ST05 to start and stop trace recording and to display and analyze the resulting traces. However, there may be circumstances where this approach is inconvenient, cumbersome, or outright impossible. Examples are requirements where you need to monitor regularly or even frequently the communication of multiple applications with external resources. This is certainly beneficial for the detection of regressions early in the development process so that you can counteract immediately. In other cases you may want to very restrictively limit the tracing to dedicated parts of your application which you suspect to use external entities in a way that impairs performance or scalability. In all these situations you want to use the API functions that come with the ST05 software. They are contained in function group ST05_API within SAP_BASIS, also known as ABAP Platform.

In this blog post I cover the most important of these API functions and describe their intended use. The focus is very much on the technicalities of using the APIs. Please refer to my other blog posts in the series for an explanation of the semantics of the provided data.

The functions can be subdivided into three categories:

1. Functions that deal with the activation or deactivation of tracing.
2. Functions that retrieve trace records with a level of detail or aggregation that best supports your intended investigation.
3. Functions that permanently store trace records in the system's database or on your local hard disc.

Trace Recording

Let me begin with functions related to writing the trace records, especially the complementary pair of functions to start and stop trace recording.

ST05_Activate_Trace

With this remote-enabled function you switch tracing on. Through the function's IMPORTING parameters you specify the communication interface you want to monitor, and you set filter criteria for the events to be covered. Functionally, the parameters cover everything that is available via the SAP GUI option Activate Trace with Filter described in my blog post Activate Trace Recording with Filter. Please visit this post for a more comprehensive explanation of the supported filter conditions.

• TRACE_TYPES  TYPE  ST05_API_TRACE_TYPES
  With this mandatory parameter you define the trace types, i.e., the communication channels, you want to monitor. Structure ST05_API_TRACE_TYPES contains Boolean fields (TRUE = 'X' ; FALSE = ' ') for all trace types supported by ST05 (SQL, BUF, ENQ, RFC, HTTP, APC, AMC), and additionally for the authorization trace (AUTH) covered by ST01. The fields are called <type>_ON. At least one trace type must be selected, otherwise the call of the function ends with exception MISSING_TRACE_TYPE.
• TRACE_FILTER  TYPE  ST05_API_TRACE_FILTER
  This optional parameter allows you to precisely filter individual communication events triggered by the application which shall be traced. The default imposes no restrictions. The TRACE_FILTER consists of fields:
  1. CLIENT  TYPE  SYMANDT
     This is very new. Previously, trace recording was not client-specific but always cross-client. Now (ABAP Release 9.12 (quarterly) / 8.16 (biennially); ABAP platform 2408 (cloud) / 2025 (classic); Kernel Release 9.12) you can define the client via this field. With a closing wildcard (e.g., 00*) you can activate tracing on multiple clients matching the given pattern.
  2. TRACE_USER  TYPE  ST05_USER_NAME_PATTERN
     This field limits the trace activation to the specified back-end user. Only her or his activities are recorded. User name patterns with the asterisk * as a terminating wildcard character are supported.
     
  3. TRANSACTION_CODE  TYPE  PTC_TRANSACTION_CODE
     PROGRAM           TYPE  PTC_PROGRAM_NAME
     RFC_FUNCTION      TYPE  ST05_RFC_FUNCTION_NAME
     URL               TYPE  ST05_URL
     With this group of four fields, you can limit the captured events to those that are triggered while executing a particular application. Because this application must be at the very top of the call hierarchy, you may give a value for at most one of the fields. Patterns with the asterisk * as a terminating wildcard are allowed.
     
  4. WP_ID  TYPE  PTC_WP_ID
     Setting the WP_ID field confines the trace recording to events called from the given ABAP work process. This is hardly ever useful in an API call, i.e., there the benefit of this filter criterion is even smaller than in the SAP GUI dialog option Activate Trace with Filter.
     
  5. INCLUDED_TABLES  TYPE  ST05_OBJECT_INCL_EXCL
     EXCLUDED_TABLES  TYPE  ST05_OBJECT_INCL_EXCL
     INCLUDE_MISSING_TABLE_NAME_ON  TYPE  PTC_BOOLEAN
     For an SQL trace, you can restrict the recording of SQL statements to those that work on certain database tables (or database views, including CDS views). You may define up to 5 tables to be included. Similarly, you can exclude up to 5 database tables. Statements accessing these excluded tables will then not be recorded. For both options, you may filter on groups of tables by terminating entries in fields INCLUDED_TABLES or EXCLUDED_TABLES with an asterisk *. For implemented Open SQL JOINs, the table name filter applies to the first of the JOINed database tables. If a database table matches entries in both fields INCLUDED_TABLES and EXCLUDED_TABLES, SQL statements against this table will not be recorded.
     If you specify a table in the INCLUDED_TABLES, and also want to trace all statements that do not directly affect an individual table (e.g., COMMITs, ROLLBACKs, SET SESSION VARIABLE, SET CLIENT INFO), you must set the Boolean field INCLUDE_MISSING_TABLE_NAME_ON to 'X'.
     
  6. STACK_TRACE_ON  TYPE  PTC_BOOLEAN
     With this field you determine whether the trace records shall contain the ABAP call hierarchy for the recorded events. The advantages (and disadvantages) of this option are described in detail in my blog post ST05: Basic Use. For use cases that call the ST05 APIs, the stack trace is typically not needed, and you should not request it to minimize the trace recording overhead.
• ALL_SERVERS  TYPE  PTC_BOOLEAN
  By default, function ST05_Activate_Trace starts trace recording only on the server where it is running. With the optional Boolean parameter ALL_SERVERS you can request the activation on all application server instances of the system. This works like the option <ALL> for field Instance in the filter conditions popup when you Activate Trace with Filter in ST05. 

Via EXPORTING parameter SERVER_INFORMATION_TABLE (of TYPE  ST05_SERVER_INFORMATION_TABLE), function ST05_Activate_Trace reports back to its caller where tracing was activated (fields INSTANCE and HOST) and when (fields DATE and TIME). Field IS_LOCAL marks the application server instance where the function was executed. The GUID will always be initial, i.e., a string of 32 zeros.

Through several EXCEPTIONS, function ST05_Activate_Trace informs its caller if errors occurred during its runtime.

• NO_AUTHORITY
  The user has insufficient authorizations. Required is value ST0M for field S_ADMI_FCD in object S_ADMI_FCD .
• MISSING_TRACE_TYPE
  No trace type has been selected, i.e., IMPORTING parameter TRACE_TYPES is INITIAL.
• NO_CROSS_CLIENT_TRACING
  Cross client tracing from an application client to another client is forbidden. An application client is recognized if a call to method cl_system_client_check=>is_system_client( ) returns ' ' (blank). This is relevant only in systems with tenant separation.
• USER_MISMATCH
  Tracing is already active for another user. It is not possible to change this user without first completely deactivating the trace recording.
• ACTIVATION_ERROR
  Trace recording cannot be activated for other reasons.
• NO_SERVER_LIST
  This exception is not yet used, i.e., never RAISEd.
• INTERNAL_ERROR
  Some internal error prevented the trace activation.

ST05_Deactivate_Trace

With this remote-enabled function you switch tracing off. Functionally, it corresponds to the SAP GUI options Deactivate Trace or Deactivate Trace on All Instances.
With the function's IMPORTING parameters you precisely control what the trace deactivation shall achieve.

• TRACE_TYPES  TYPE ST05_API_TRACE_TYPES
  ALL          TYPE  PTC_BOOLEAN
  With an appropriate combination of these two optional parameters you specify the trace types for which you want to deactivate the recording. Typically, this will be the set of trace types you have previously passed into function ST05_Activate_Trace. Then it will be convenient to set ALL to 'X' and leave TRACE_TYPES initial. This is also the approach to establish clean initial conditions where all components of the System Trace (ST01) are switched off - even those not accessible to ST05. If you want to deactivate tracing only for a subset of the currently monitored communication channels, set the corresponding fields in TRACE_TYPES to 'X'. Do not let the field names of structure ST05_API_TRACE_TYPES confuse you: they are called <type>_ON, but function ST05_Deactivate_Trace will switch off the recording when they are set to 'X'.
  If both, TRACE_TYPES and ALL, are initial, the function will terminate with exception MISSING_TRACE_TYPE. If ALL is set to 'X', it will overwrite whatever is passed into ST05_Deactivate_Trace with parameter TRACE_TYPES, i.e., then the content of this parameter will be ignored.
• ALL_SERVERS  TYPE  PTC_BOOLEAN
  If you set this optional parameter to 'X', trace recording will be switched off on all application server instances of the system.
• ALL_USERS  TYPE  PTC_BOOLEAN
  If this optional flag has the value 'X', the selected TRACE_TYPES will be deactivated, independent of who activated them. Otherwise and if the trace recording was activated by another user, the function will terminate with exception DEACTIVATION_ERROR.

As with function ST05_Activate_Trace, the EXPORTING parameter SERVER_INFORMATION_TABLE (TYPE  ST05_SERVER_INFORMATION_TABLE) informs callers of function ST05_Deactivate_Trace where tracing was deactivated (fields INSTANCE and HOST) and when (fields DATE and TIME). Field IS_LOCAL marks the application server instance where the function was executed. The value of the GUID field identifies the trace directory entry corresponding to the just ended trace recording. Please refer to my blog post Trace Directory for more details on this component of ST05.

Similar to ST05_Activate_Trace, function ST05_Deactivate_Trace communicates errors to its caller by several EXCEPTIONS:

• NO_AUTHORITY
  The user has insufficient authorizations. Required is value ST0M for field S_ADMI_FCD in object S_ADMI_FCD .
• MISSING_TRACE_TYPE
  No trace type has been selected, i.e., IMPORTING parameters TRACE_TYPES and ALL are INITIAL.
• DEACTIVATION_ERROR
  Trace recording cannot be activated for other reasons.
  Example: Tracing was activated by another user and parameter ALL_USERS was not set.
• NO_SERVER_LIST
  This exception is not yet used, i.e., never RAISEd.
• INTERNAL_ERROR
  Some internal error prevented the trace deactivation.

Pseudo code for a typical scenario that uses these two functions:

CALL FUNCTION 'ST05_ACTIVATE_TRACE' ... .
    Execute some part of the application
    which communicates with external resource
    in a potentially critical way.
CALL FUNCTION 'ST05_DEACTIVATE_TRACE' ... .

If you have passed appropriate arguments into functions ST05_Activate_Trace and ST05_Deactivate_Trace, you have recorded traces of your application's accesses to external resources. The corresponding trace records are stored in the file systems of the application server instances. From there you can fetch the traces for detailed analyses as described in the following section Trace Analysis.

ST05_GET_TRACE_STATE

This function (also remote-enabled) is closely related to the two functions explained above. It retrieves the current trace state from the application server instance where it was called. You would use it to convince yourself that it is possible and safe to call function ST05_ACTIVATE_TRACE without interfering with ongoing trace recordings of other users, or to double-check that previous calls to ST05_ACTIVATE_TRACE  or ST05_Deactivate_Trace were successful.
The function's sole EXPORTING parameter TRACE_STATE of type ST05_TRACE_STATE has the components

• CLIENT  TYPE  SYMANDT
• TRACE_USER  TYPE  ST05_USER_NAME_PATTERN
• MODIFICATION_USER  TYPE  SYUNAME
  Name of the user who has last changed the trace state on the local application server instance.
• MODIFICATION_DATE  TYPE  DATS
  MODIFICATION_TIME  TYPE  TIMS
  Date and Time when the trace state was last changed on the local application server instance.
• TRACE_TYPES  TYPE  ST05_TRACE_TYPES
• FILTER_ON  TYPE  PTC_BOOLEAN
  Flag to indicate whether trace recording was activated with filter.
• TRANSACTION_CODE  TYPE  PTC_TRANSACTION_CODE
  PROGRAM           TYPE  PTC_PROGRAM_NAME
  RFC_FUNCTION      TYPE  ST05_RFC_FUNCTION_NAME
  URL               TYPE  ST05_URL
• WP_ID  TYPE  PTC_WP_ID
• INCLUDED_TABLES  TYPE  ST05_OBJECT_INCL_EXCL
• EXCLUDED_TABLES  TYPE  ST05_OBJECT_INCL_EXCL
• INCLUDE_MISSING_TABLE_NAME_ON  TYPE  PTC_BOOLEAN
• STACK_TRACE_ON  TYPE  PTC_BOOLEAN
• PROGRESS_INDICATOR_ON  TYPE  PTC_BOOLEAN
  This flag has no meaning any more.

Structure components that are not explained in the above list correspond to the matching fields of the IMPORTING parameter TRACE_FILTER of function ST05_ACTIVATE_TRACE. They are described above.

Trace Analysis

Let me now move on and continue with the API based processing and analysis of previously recorded traces. Three functions support different levels of detail for your investigation. I have already explained the available aggregation options in my blog post Aggregate Trace Records. The most comprehensive function is ST05_GET_TRACE_TABLES, which supplies internal tables of trace records for all supported degrees of aggregation plus the raw format of the ABAP call stack. Function ST05_GET_SUMMARY_TABLES focuses on the summarized trace records, and function ST05_GET_TABLE_ACCESS_RECORDS only provides the database table access trace records.
Functions ST05_GET_TRACE_TABLES and ST05_GET_SUMMARY_TABLES have the same IMPORTING parameters, a subset of which is also available to ST05_GET_TABLE_ACCESS_RECORDS.

• TRACE_TYPES  TYPE  ST05_TRACE_TYPES
  Specify the trace types you are interested in by setting the corresponding flags <type>_ON to 'X'. The flags AUTH_ON and ST01_ON have no effect.
• TRACE_INTERVAL  TYPE  ST05_TRACE_INTERVAL
  Indicate the trace period by giving its START_DATE and START_TIME, and its END_DATE and END_TIME. You will typically fill these fields with values obtained from functions ST05_Activate_Trace and ST05_Deactivate_Trace via their EXPORTING parameter SERVER_INFORMATION_TABLE.
  (Fields START_MS and END_MS allow to set the beginning and end, respectively, of the trace interval to milli-second precision. They are hardly ever meaningful.)
• READ_FILTER_CONDITIONS  TYPE  ST05_READ_FILTER_CONDITIONS
  With this parameter you restrict the set of trace records to those that are associated with EPP root context IDs contained in EPP_ROOT_CONTEXT_ID_RANGE. This is of limited value because you seldom know the EPP root context ID, and if you have managed to "very restrictively limit the tracing" almost all trace records will have identical EPP root context IDs.
  
• GUID  TYPE  SYSUUID_X16
  If you specify this parameter, the corresponding trace directory entry will be processed. The GUID takes precedence over the TRACE_TYPES, TRACE_INTERVAL, and READ_FILTER_CONDITIONS parameters.
  If flag SAVE_TO_DB is set, and there is not yet a trace directory entry that permanently stores the trace records in the database, it will be created and identified with this GUID.
• KIND  TYPE  CHAR4
  Control the level of detail or aggregation of the trace records to be provided by the API functions. Possible values are
  1. CDS
     statistics on CDS view usage
  2. ALL (default)
     all of the following levels
  3. MAIN
     main trace records
  4. DET (not supported by function ST05_GET_SUMMARY_TABLES)
     detailed trace records
  5. DET+ (not supported by function ST05_GET_SUMMARY_TABLES)
     detailed trace records plus kernel format of the ABAP call stack
  6. STRU
     structure-identical trace records
  7. VAL
     value-identical trace records
  8. TAB
     table accesses trace records
• ACCEPT_INCOMPLETE_TRACE  TYPE  PTC_BOOLEAN
  As I have described in my blog post Technical Background of Trace Recording and Analysis, a trace may be partially overwritten due to the round-robin approach used internally for the trace file administration. The default behaviour of the ST05 API functions in this case is to return no trace records at all. You can overrule this by setting the flag  ACCEPT_INCOMPLETE_TRACE to 'X'. Then  the functions will supply all appropriate trace records that are still available.
• SAVE_TO_DB  TYPE  PTC_BOOLEAN
  Set this flag if you want the trace records to be stored in a trace directory entry on the database to ensure that they are not overwritten.
  This is a special option for dedicated internal purposes. If you wish to save trace records to the database I advise you to instead use the generic function ST05_SAVE_TRACE, which I describe below in section Trace Administration.

Function ST05_GET_TABLE_ACCESS_RECORDS does not support IMPORTING parameters READ_FILTER_CONDITIONS, KIND, and SAVE_TO_DB, but offers the Boolean flag CONDENSE. If set to 'X', INSERTs, DELETEs, UPDATEs as well as various buffer accesses to a database table will be summarized.

The functions' EXPORTING parameters provide trace records in ABAP internal tables to their callers. Please refer to my Aggregate Trace Records blog post for an explanation of the fields in the underlying structures.

• DETAILED_RECORD_TABLE  TYPE  ST05_DETAILED_RECORD_TABLE
  This internal table does not summarize the trace records, thus can support all conceivable investigations. 
• MAIN_RECORD_TABLE  TYPE  ST05_MAIN_RECORD_TABLE
  I have described the purpose and the most relevant fields of this level of aggregation in my Basic Use blog post.
• STRUCTURE_ID_RECORD_TABLE  TYPE  ST05_IDENTICAL_RECORD_TABLE
  For many types of investigation this is the appropriate level of detail. It perfectly balances the available information granularity with the size of the internal table. It also augments the trace records with meta data on the accessed database tables.
• VALUE_ID_RECORD_TABLE  TYPE  ST05_IDENTICAL_RECORD_TABLE
  Use this internal table to detect redundant accesses to database tables. They fetch identical result sets from the database. This creates unnecessary load on the central database server and slows down the application. Please note that superfluous database accesses do not necessarily lead to value-identical trace records, i.e., even if VALUE_ID_RECORD_TABLE is empty, the traced application may need some performance optimization.
• TABLE_ACCESS_RECORD_TABLE  TYPE  ST05_TABLE_ACCESS_RECORD_TABLE
  This internal table aggregates SQL trace records corresponding to statements of the same category (e.g., SELECT, INSERT, UPDATE, DELETE) that access a table or view. It also summarizes BUF trace records that access an object with the same number of key fields. Other trace types are not covered.
• KERNEL_CALL_STACK  TYPE  ST05_KERNEL_CALL_STACK
  This is the raw format of the ABAP call hierarchy. As I have already mentioned, it is not relevant for the typical use cases that call the ST05 APIs, and you should not even record it.
• TRACE_DIRECTORY_ENTRY  TYPE  PTC_DIRECTORY_ENTRY
  This is only available if the IMPORTING parameter GUID was specified. Then it contains the corresponding entry from the trace directory. For the use cases covered in this blog post, it is not relevant.
• INCOMPLETE_TRACE  TYPE  PTC_BOOLEAN
  If the functions set this Boolean flag to 'X', the trace and therefore the internal tables are potentially incomplete. You want to repeat the trace recording with a more restrictive filter passed into function ST05_Activate_Trace.

Function ST05_GET_SUMMARY_TABLES does not support EXPORTING parameters DETAILED_RECORD_TABLE and KERNEL_CALL_STACK. 
Function ST05_GET_TABLE_ACCESS_RECORDS only offers EXPORTING parameters TABLE_ACCESS_RECORD_TABLE and INCOMPLETE_TRACE.

Trace Administration

With functions ST05_SAVE_TRACE and ST05_EXPORT_TRACE you can save sets of trace records to the trace directory on the database or export them to your local front end file system, respectively. In either case, this will persist the trace records so that you can analyze them even when they are no longer in the application server instance's file system.

Both functions offer IMPORTING parameters TRACE_TYPES and TRACE_INTERVAL as described above.

If you specify a DESCRIPTION when calling ST05_SAVE_TRACE, this will be used for the trace directory entry. If you leave the DESCRIPTION empty, the user will be prompted in a dialog to describe the set of trace records.
Function ST05_SAVE_TRACE supports Boolean flags ACCEPT_INCOMPLETE_TRACE and ALL_SERVERS. If you set ALL_SERVERS = 'X' the function will go through all application server instances and save trace records that match the filter criteria into individual trace directory entries.

With function ST05_EXPORT_TRACE you may specify a GUID of a trace that is already stored in the trace directory. This trace will then be exported to your hard disc, and parameters TRACE_TYPES and TRACE_INTERVAL will be ignored.
With the FORMAT parameter you can determine whether the trace shall be exported in binary format ( value 'BIN', suitable for later re-import and further analysis with ST05), or in ASCII format (value 'CSV_*', where * indicates the aggregation level), e.g., for subsequent analysis with spreadsheet software.
The FILE_NAME parameter will be used to name the file on the front end. If no name is passed into function ST05_EXPORT_TRACE, it will prompt the user.