PSL Profiler Tool

The PSL Profiler is a measurement component built into the PATROL Agent to measure how many resources each PSL script consumes. This allows the determination of which scripts have the largest usage cost and provides information as to where the cost is distributed within the PSL script.

The main PATROL Agent resource measured by the PSL Profiler is CPU time. This is broken into user time and system time, to indicate that the system calls may take some time in some of the PSL built-in functions. The PSL Profiler does not explicitly measure other cost measures such as the number of child processes, the amount of memory, PSL locks, global channels, and so on. However, some of this information can be gathered from the execution counts and the built-in function call counts. For example, child processes can be measured reasonably accurately as the number of calls to PSL system(), execute(), and popen() functions.

The PSL Profiler tool is used to collect profiling information from PSL processes. Primarily, the PSL Profiler records which PSL functions are called, how often each PSL function is called, and the time spent in each PSL function for each PSL process. All the profiling information that is collected for a PSL process is stored internally until the PSL process exits. When the PSL process does exit, the profiling information is written to the binary file specified by the PSL_PROF_LOG environment variable.

The PSL Profiler saves the profile data for PSL processes to the profile file as they terminate. Profiler output is saved in the file specified by the PSL_PROF_LOG environment variable. When the PATROL Agent is shut down in an orderly fashion, the Profiler saves the profile data for those PSL processes that have not been destroyed.

There are a number of interfaces to the PSL Profiler:

PSL functions--The PSL Profiler can be dynamically enabled via PSL and reports can be printed in PSL.
PSL Profiler Viewer (ppv) utility--This is an off-line reporting tool that analyzes a profiling data file that the PATROL Agent can generate during profiling.
PSL Profiler API--The PSL Profiler API allows the PSL Profiler to be controlled (started, stopped, etc.) and queried at run-time.

Supported Platforms

Operating Systems

UNIX
Windows

PATROL Versions

PATROL 3.2 and later Agent

To Use the PSL Profiling Capability in PATROL v3.1

The list of PSL processes currently running in the Agent can be sampled and used to generate a rough picture of the cost of each PSL process. Use this tool as a sampling technique for PATROL v3.1 products in lieu of the PSL Profiler offered in v3.2.

Resource Requirements

PSL Profiler requires no additional resources beyond those specified for running the PATROL for Windows product.

When to Use the PSL Profiler

The primary purpose of the PATROL profiling tools in the KM development environment is to aid in the KM performance tuning task.

Use the PSL Profiler to

tune the CPU usage of a PSL script
find the highest consuming PSL script
tune the number of external processes

The Profiler tools can also be used as a PATROL Agent configuration or deployment tool in production systems to determine which KMs and PSL scripts are taking too many resources.

Limitations of the PSL Profiler

The main limitation of the PSL Profiler is that it does not go very deep within each script to examine performance. For example, there is no line-by-line report showing which lines are executed most frequently. The analysis of built-in functions is useful but there is no similar analysis of PSL user-defined functions. The PSL Profiler can be dynamically enabled and disabled during Agent execution. Enabling the PSL Profiler will turn on the measurement for the specified PSL scripts. Disabling the Profiler will discard all measured data and return the Agent to the normal non-profiling state.

The impact of turning on the PSL Profiler is a marginal degradation of PSL execution performance. This results because each PSL timeslice must also be added to measurement counters. However, this is mainly a low in-memory cost. The largest costs are when the reports are generated. Reports are generated only when the data have been collected.

How to Install the PSL Profiler

This tool is part of the PATROL product. No further setup is required once PATROL has been installed.

How to Start the PSL Profiler

You can activate the PSL Profiler as follows:

using PSL functions
starting the PATROL Agent with the -profiling option

In all cases, the output report is of a similar format. The PSL Profiler reports tell you which PSL scripts have the highest CPU usage and also measure how much each built-in PSL function has used.

Scheduling frequency of the PSL processes affects the results since the CPU usage timers are cumulative. However, since the number of executions is also measured, the average cost per execution can also be easily generated in reports.

The Profiler output is saved in the file specified by the PSL_PROF_LOG environment variable.

PSL Profiler PSL Functions

The following PSL functions support the PSL Profiler tool:

Name	Description
`ProfDefaultOptions()`	sets the default Profiler options to options
`ProfGet()`	retrieves the profile of the process identifiedbypid
`ProfGetTotalCpu()`	retrievesthetotalreal, user, and CPU time as well as the percent of CPU usage
`ProfOptions()`	sets the profiling options of the process identified by pid to `options`
`ProfReset()`	resets the profiling data for all processes
`ProfTop()`	retrieves the profiles of the top_procs highest CPU time processes

ProfDefaultOptions()

The default Profiler options are queried or changed by using the ProfDefaultOptions() function, with the following format:

ProfDefaultOptions(options)

This function sets the default profiler options to options. If options is omitted, then the current default options are returned. Changing the default Profiler options does not affect the profiling options of existing processes.

Options

Value	Description
0	disable profiling
1	enable process-level profiling
2	enable function-level profiling
4	cumulative
8	save at exit

ProfGet()

The profiles of one or more PSL processes are retrieved by using the ProfGet() function, with the following format:

ProfGet( pid , top_funcs )

This function retrieves the profile of the process identified by pid. If pid is -1 or "", then the profiles of all existing PSL processes are returned. Iftop_funcs, a numeric value, is specified, then only top_funcs highest CPU-time function calls are returned to the profile of each process. Otherwise, all function call data available for each process are returned.

ProfGetTotalCpu()

The total CPU usage statistics for the current interval (since profiling was started or reset) are retrieved by the ProfGetTotalCpu() function, with the following format:

ProfGetTotalCpu()

The ProfGetTotalCpu() function returns, in order, the real CPU time, user CPU time, system CPU time, and CPU percent in the following format:

2:25:52.275 0:01:07.998 0:00:14.200 0.94

ProfOptions()

The profiling options of existing processes are queried or changed by using the ProfOptions() function, with the following format:

ProfOptions( pid,options)

This function sets the profiling options of the process identified by pid to options. If pid is -1 or "", then the profiling options of all existing processes are changed to options. If options is omitted, then the current profiling options of the process identified by pid are returned.

ProfReset()

The profiling data for all processes are reset by using the ProfReset() function, with the following format:

ProfReset()

This function resets the profiling data of all processes and sets the Profiler's reference point to the current time so the future ProfGetTotalCpu()function call reflects the totals from the ProfReset() function call.

ProfTop()

The profiles of the highest CPU time-consuming processes are retrieved by using the ProfTop() function, with the following format:

ProfTop( top_procs , [ top_funcs ])

This function retrieves the profiles of the top_procs highest CPU-time processes. If top_funcs is specified, then the top_funcs highest CPU-time function calls are returned in the profile of each process. Otherwise, all function call data available for each process are returned.

Note

The top_procs and top_funcs variables are both numeric values.

About the PSL Profile Viewer (ppv) Tool

The PSL Profile Viewer tool (also known as the ppv utility) provides the capability to view the PSL profiling information stored in a binary profile.

To view the binary profile file after the Agent (or PSL stand-alone) has terminated, use the ppv utility. This tool uses one argument, the name of the profile file, and stores statistics for the PATROL Agent and each PSL process that the Agent has executed. The Agent's data includes the following:

number of PSL processes profiled
elapsed time of the Agent
cumulative CPU time of the PATROL Agent
average percent CPU load of the PATROL Agent

The PSL process data includes the number of executions and real and CPU times used by each process, the number of calls, and a breakdown of the real and CPU time used by each function that a process calls.

All of this information is sorted in descending order by the highest CPU time and by the name in the event that two processes (or function calls) have the same cumulative CPU time.

About the PSL Profiler API

The PSL Profiler API allows the PSL Profiler to be controlled (started, stopped, etc.) and queried at run-time. Profiling is possible without needing the -profiling option and without stopping the Agent.

Profiling behavior is controlled by assigning a process the sum of one or more of the following options:

Value	Description
0	disable profiling
1	enable process-level profiling
2	enable function-level profiling
4	cumulative
8	save at exit

When first created, a process is assigned the current default Profiler options. The sum of the default Profiler options is 15 if the Agent is started with the -profiling option ( -p option for the PSL stand-alone) or 0 otherwise.