function::ustack - Linux

Overview

function::ustack is a powerful command-line tool used to profile and debug the performance of Rust programs. It allows developers to analyze the call stack and identify potential performance bottlenecks.

Syntax

function::ustack [FLAGS] [OPTIONS] <PROFILE_FILE>

Options/Flags

  • -o, --output: Specify the output file for the stack trace. Defaults to stdout.
  • -f, --format: Output format. Available options are:
    • text
    • json
    • csv
  • --num: Number of stack frames to show. Defaults to 10.
  • --sort: Sorting criteria for the stack trace. Available options are:
    • time
    • self_time
    • total_time
    • exclusive_time
  • --flamegraph: Generate a flamegraph (visualization of the call stack).
  • --no-lines: Disable displaying line numbers.
  • --demangle: Demangle symbol names.
  • --folded: Fold inner function calls.
  • --dwarf-stack-trace: Use DWARF debug information for stack trace unwinding.
  • --help: Print usage information.

Examples

Print a text-based stack trace:

function::ustack program.profile

Generate a JSON output with flamegraph:

function::ustack --format json --flamegraph program.profile > output.json

Print a folded stack trace sorted by total time:

function::ustack --folded --sort total_time program.profile

Common Issues

  • Missing dwarf information: Ensure that the program is compiled with debug information (-g) to enable stack trace unwinding.
  • Segfaults and crashes: If the program crashes while profiling, the stack trace may be incomplete or inaccurate.
  • Slow profiling: Profiling can significantly slow down the execution of the program. Use the --num option to limit the number of stack frames captured.

Integration

Integration with other tools:

  • perf: Use function::ustack to analyze stack traces from perf profiling.
  • Flamegraph.pl: Generate flamegraphs with function::ustack’s output using the Flamegraph.pl utility.

Related Commands

  • perf
  • gprof
  • stackcollapse-rs