Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

SLAX Debugger, Profiler, and callflow

The libslax distribution includes the SLAX debugger and profiler. These tools enable you to trace the execution and analyze the performance of SLAX scripts.

SLAX Debugger, Profiler, and callflow Overview

The Junos OS CLI and the libslax distribution include the SLAX debugger (sdb), which you can use 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 is automatically enabled when you start the debugger. The profiler tracks script execution until the script terminates. At any point, you can display or clear profiling information, and you can temporarily enable or disable the profiler. 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 the script has 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 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.

Optional values:

  • clear—Clear profiling information.

  • on—Enable the profiler.

  • off—Disable the profiler.

  • report—Display profiling information for the current script.

  • report brief—Display brief 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.

How to Use the SLAX Debugger, Profiler, and callflow

Invoke the SLAX Debugger

Both the Junos OS CLI and the SLAX processor include the SLAX debugger (sdb). You can use the SLAX debugger 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:

In the Junos OS CLI, you can only use the debugger with op scripts that you enable in the configuration. To invoke the SLAX debugger in the CLI, issue the op invoke-debugger cli operational mode command. Include the op script name and any necessary script arguments.

The following example invokes the SLAX debugger for the op script ge-interfaces.slax. The script has two parameters, interface and protocol. The command supplies values for both arguments.

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 the script does not require an input file, 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 (stdin) is used. When using stdin, 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. The input document is empty, and the output file is script1-output.xml.

Use 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. Breakpoints are numbered sequentially as you create them. To add, view, or remove breakpoints, use the following commands:

    • break—Add a breakpoint at the current line of execution.

    • break (template-name | [file:]line)—Add a breakpoint at the specified location.

    • info breakpoints—View a list of breakpoints.

    • delete—Delete all breakpoints.

    • delete num—Delete the given breakpoint.

    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.

Use the SLAX Profiler

The SLAX debugger includes a profiler that can report information about the activity and performance of a script. When you invoke the SLAX debugger, it automatically enables the profiler. You can also disable or enable the profiler as needed. The profiler tracks script execution until the script terminates. At any point, you can display or clear profiling information. Additionally, starting in SLAX version 1.3, you can use the slaxproc command with the profile and profile-mode options to run the profiler directly on a script, without invoking the debugger. For additional information, see Run the Profiler on a Script.

To access the profiler within the SLAX debugger, 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, the profiler displays the lines with dashes.

    The following sample output shows a profile report with and without the brief option. The example truncates the source code data for display purposes.

The profile report includes the following information:

  • Line—Source code line number.

  • Hits—Number of times the 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 it can also show which lines that the script executes. This information can help debug scripts where the execution does not match expectations.

Use the callflow Command

The SLAX debugger callflow command enables you to print 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.

Related Documentation