SLAX Debugger, Profiler, and callflow
SLAX Debugger, Profiler, and callflow Overview
The Junos OS command-line interface (CLI) and the libslax distribution include the SLAX debugger (sdb), which is used to trace the execution of SLAX scripts. The SLAX debugger enables you to step through script execution, pause script execution at defined breakpoints, and review the value of script variables at any point.
The SLAX debugger operation and command syntax resemble that of the GNU Project Debugger (GDB). Many of the sdb commands follow their GDB counterparts, to the extent possible.Table 1 lists the SLAX debugger commands and a brief description of each command.
The SLAX debugger includes a profiler that can report information about the activity and performance of a script. The profiler, which is automatically enabled when you start the debugger, tracks script execution until the script terminates. At any point, profiling information can be displayed or cleared, and the profiler can be temporarily disabled or enabled. The SLAX debugger callflow command enables printing of informational data when you enter or exit levels of the script.
Table 1: SLAX Debugger Commands
Command | Description |
|---|---|
break [loc] | Add a breakpoint to the script at the current line of execution. Optionally specify [file:]line or a template name to create a breakpoint at that position. |
callflow [on | off] | Enable or disable callflow tracing. You can explicitly specify the on or off value. Omitting the value toggles callflow on and off. |
continue [loc] | Continue running the script until it reaches the next breakpoint. If there are no defined breakpoints, the script runs in its entirety. Optionally, specify [file:]line or a template name. When you include the optional argument, script execution continues until it reaches either a breakpoint or the specified line number or template name, whichever comes first. |
delete [num] | Delete one or all breakpoints. Breakpoints are numbered sequentially as they are created. Omit the optional argument to delete all breakpoints. Include the breakpoint number as an argument to delete only the specified breakpoint. View currently active breakpoints with the info command. |
finish | Finish executing the current template. |
help | Display the help message. |
info [breakpoints | profile | profile brief] | Display information about the current script. The default command lists all breakpoints in the script. Optionally specify the profile or profile brief arguments to display profiling information. |
list [loc] | List the contents of the current script. Optionally specify [file:]line or a template name from which point the debugger lists partial script contents. The output includes the filename, line number, and code. |
next | Execute the next instruction, stepping over any function or template calls. |
over | Execute the next instruction, stepping over any function or template calls or instruction hierarchies. |
print <xpath> | Print the value of the XPath expression. |
profile [clear | on | off | report | report brief] | Enable or disable the profiler. The profiler is enabled by default. Include the clear option to clear profiling information. Include the report or report brief option to display profiling information for the current script. |
quit | Exit debugging mode. |
reload | Reload the script. |
run | Restart script execution from the beginning of the script. |
step | Execute the next instruction, stepping into any function or template calls or instruction hierarchies. |
where | Show the backtrace of template calls. |
Using the SLAX Debugger, Profiler, and callflow
Invoking the SLAX Debugger
Both the Junos OS CLI and the SLAX processor in the libslax distribution include the SLAX debugger (sdb), which is used to trace the execution of SLAX scripts.
When you invoke the SLAX debugger, the command-line prompt changes to (sdb) to indicate that you are in debugging mode. For example:
sdb: The SLAX Debugger (version ) Type 'help' for help (sdb)
When using the SLAX debugger from the Junos OS CLI, you can only use the debugger with op scripts that are enabled in the configuration. To invoke the SLAX debugger from the CLI on a device running Junos OS, issue the op invoke-debugger cli operational mode command, include the op script name, and optionally include any necessary script arguments.
user@host>op invoke-debugger cli script <argument-name argument-value>
The following example invokes the SLAX debugger for
the op script ge-interfaces.slax,
which has two parameters, interface and protocol. Values are supplied for both arguments.
user@host> op invoke-debugger cli ge-interfaces
interface ge-0/2/0.0 protocol inetsdb: The SLAX Debugger (version ) Type 'help' for help (sdb)
To invoke the SLAX debugger when using the SLAX processor, issue the slaxproc command with the --debug or -d option. Specify the script file and any input or output files. If no input file is required, use the -E option to indicate an empty input document. If the -i or --input argument has the value "‑", or if you do not include the input option or an input file, standard input is used. When using standard input, press Ctrl+d to signal the end-of-file. The general syntax is:
$ slaxproc --debug [options] [script] [files]
The following example invokes the SLAX debugger for
the script script1.slax with an empty
input document and an output file script1-output.xml
$ slaxproc --debug -n script1.slax -o script1-output.xml
-Esdb: The SLAX Debugger (version ) Type 'help' for help (sdb)
Using the SLAX Debugger (sdb)
To view the SLAX debugger help message, issue the help command at the (sdb) prompt. To display the help message for a single command, issue help command, where command is the sdb command for which you want more information. For example:
(sdb) help break break [loc] Add a breakpoint at [file:]line or template
The process for debugging a script varies depending on the script. A generic outline is presented here:
- Enter debugging mode.
- Insert breakpoints in the script using the break command.
During execution, the debugger pauses at defined breakpoints.
The breakpoint location can be the name of a template or a line number in the current script, or the filename and a line number separated by a colon. If you do not include an argument, a breakpoint is created at the current line of execution. Breakpoints are numbered sequentially as you create them. To view a list of breakpoints, issue the info breakpoints command. To delete a breakpoint, issue the delete num command, and specify the breakpoint number. To delete all breakpoints, issue the delete command with no argument.
The following example creates three breakpoints, the first at line 7, the second at line 25, and the third at the template named "three":
(sdb) break 7 Breakpoint 1 at file script1.slax, line 7 (sdb) break 25 Breakpoint 2 at file script1.slax, line 25 (sdb) break three Breakpoint 3 at file script1.slax, line 51 (sdb) info breakpoints List of breakpoints: #1 [global] at script1.slax:7 #2 template two at script1.slax:25 #3 template three at script1.slax:51 Increment script execution by issuing the continue, finish, next, over, and step commands at the debugger prompt.
For example:
(sdb) next Reached breakpoint 1, at script1.slax:7 script1.slax:3: var $byte = "10011001";
- Review the value of variables as the program executes
to ensure that they have the expected value.
print xpath-expression
To reload the script contents at any point and restart script execution from the beginning, issue the reload command.
(sdb) reload The script being debugged has been started already. Reload and restart it from the beginning? (y or n) y Reloading script... Reloading complete.
Using the SLAX Profiler
The SLAX debugger includes a profiler that can report information about the activity and performance of a script. The profiler, which is automatically enabled when you start the debugger, tracks script execution until the script terminates. At any point, profiling information can be displayed or cleared, and the profiler can be temporarily disabled or enabled.
To access the profiler, issue the profile command at the SLAX debugger prompt, (sdb), and include any options. The profile command syntax is:
(sdb) profile [options]
Table 2 lists the profile command options. Issuing the profile command with no additional options toggles the profiler on and off.
(sdb) profile Disabling profiler (sdb)
You can access the profiler help by issuing the help profile command at the (sdb) prompt.
Table 2: Profile command options
Option | Description |
|---|---|
clear | Clear profiling information |
off | Disable profiling |
on | Enable profiling |
report [brief] | Report profiling information |
To enable the profiler and print a report:
- Enter debugging mode. The profiler is enabled by default.
- Step through script execution, or execute a script in
its entirety.
(sdb) run <?xml version="1.0"?> <message>Down rev PIC in Fruvenator, Fru-Master 3000</message> Script exited normally.
At any point during script execution, display profiling information.
The brief option instructs sdb to avoid showing lines that were not hit, since there is no valid information. If you omit the brief option, dashes are displayed.
(sdb) profile report brief
The following sample output shows a profile report with and without the brief option. The source code data in the example is truncated for display purposes.
(sdb) profile report Line Hits User U/Hit System S/Hit Source 1 - - - - - version 1.0; 2 - - - - - 3 2 4 2.00 8 4.00 match / { 4 1 25 25.00 13 13.00 var .... 5 - - - - - 6 - - - - - for-each.... 7 1 45 45.00 10 10.00 .. 8 1 12 12.00 5 5.00 <message> 9 1 45 45.00 15 15.00 .... 10 - - - - - } 11 - - - - - } Total 6 131 51 Total (sdb) pro rep b Line Hits User U/Hit System S/Hit Source 3 2 4 2.00 8 4.00 match / { 4 1 25 25.00 13 13.00 var .... 7 1 45 45.00 10 10.00 .... 8 1 12 12.00 5 5.00 <message> 9 1 45 45.00 15 15.00 .... Total 6 131 51 Total
The profile report includes the following information:
- Line—Line number in the source file.
- Hits—Number of times this line was executed.
- User—Number of microseconds of "user" time spent processing this line.
- U/Hit—Average number of microseconds of "user" time per hit.
- System—Number of microseconds of "system" time spent processing this line.
- S/Hit—Average number of microseconds of "system" time per hit.
- Source—Source code line.
This information not only shows how much time is spent during code execution, but can also show which lines are being executed, which can help debug scripts where the execution does not match expectations.
Using callflow
The SLAX debugger callflow command enables printing of informational data when you enter or exit levels of the script.
To enable callflow and view callflow data for a script:
- Enter debugging mode.
Issue the callflow command at the SLAX debugger prompt, (sdb).
(sdb) callflow Enabling callflow
Step through script execution, or execute a script in its entirety.
Callflow prints information as it enters and exits different levels of the script. Each output line references the instruction, filename, and line number of the frame.
(sdb) run callflow: 0: enter <xsl:template> in match / at script3.slax:5 callflow: 1: enter <xsl:template> in template one at script3.slax:14 callflow: 2: enter <xsl:template> in template two at script3.slax:20 callflow: 3: enter <xsl:call-template> at script3.slax:22 ... <?xml version="1.0"?> <message>Down rev PIC in Fruvenator, Fru-Master 3000</message> Script exited normally.
