Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

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:

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.

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 inet

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:

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 -E

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:

The process for debugging a script varies depending on the script. A generic outline is presented here:

  1. Enter debugging mode.
  2. 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":

  3. Increment script execution by issuing the continue, finish, next, over, and step commands at the debugger prompt.

    For example:

  4. Review the value of variables as the program executes to ensure that they have the expected value.
  5. To reload the script contents at any point and restart script execution from the beginning, issue the reload command.

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:

Table 2 lists the profile command options. Issuing the profile command with no additional options toggles the profiler on and off.

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:

  1. Enter debugging mode. The profiler is enabled by default.
  2. Step through script execution, or execute a script in its entirety.
  3. 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.

    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.

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:

  1. Enter debugging mode.
  2. Issue the callflow command at the SLAX debugger prompt, (sdb).

  3. 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.