Stack Traces
The StackTraces
module provides simple stack traces that are both human readable and easy to use programmatically.
Viewing a stack trace
The primary function used to obtain a stack trace is stacktrace()
:
julia> stacktrace() 4-element Array{StackFrame,1}: eval(::Module, ::Any) at boot.jl:236 eval_user_input(::Any, ::Base.REPL.REPLBackend) at REPL.jl:66 macro expansion at REPL.jl:97 [inlined] (::Base.REPL.##1#2{Base.REPL.REPLBackend})() at event.jl:73
Calling stacktrace()
returns a vector of StackFrame
s. For ease of use, the alias StackTrace
can be used in place of Vector{StackFrame}
. (Examples with [...]
indicate that output may vary depending on how the code is run.)
julia> example() = stacktrace() example (generic function with 1 method) julia> example() 5-element Array{StackFrame,1}: example() at REPL[1]:1 eval(::Module, ::Any) at boot.jl:236 [...] julia> @noinline child() = stacktrace() child (generic function with 1 method) julia> @noinline parent() = child() parent (generic function with 1 method) julia> grandparent() = parent() grandparent (generic function with 1 method) julia> grandparent() 7-element Array{StackFrame,1}: child() at REPL[3]:1 parent() at REPL[4]:1 grandparent() at REPL[5]:1 [...]
Note that when calling stacktrace()
you'll typically see a frame with eval(...) at boot.jl
. When calling stacktrace()
from the REPL you'll also have a few extra frames in the stack from REPL.jl
, usually looking something like this:
julia> example() = stacktrace() example (generic function with 1 method) julia> example() 5-element Array{StackFrame,1}: example() at REPL[1]:1 eval(::Module, ::Any) at boot.jl:236 eval_user_input(::Any, ::Base.REPL.REPLBackend) at REPL.jl:66 macro expansion at REPL.jl:97 [inlined] (::Base.REPL.##1#2{Base.REPL.REPLBackend})() at event.jl:73
Extracting useful information
Each StackFrame
contains the function name, file name, line number, lambda info, a flag indicating whether the frame has been inlined, a flag indicating whether it is a C function (by default C functions do not appear in the stack trace), and an integer representation of the pointer returned by backtrace()
:
julia> top_frame = stacktrace()[1] eval(::Module, ::Any) at boot.jl:236 julia> top_frame.func :eval julia> top_frame.file Symbol("./boot.jl") julia> top_frame.line 236 julia> top_frame.linfo Nullable{Core.MethodInstance}(MethodInstance for eval(::Module, ::Any)) julia> top_frame.inlined false julia> top_frame.from_c false
julia> top_frame.pointer 0x00007f390d152a59
This makes stack trace information available programmatically for logging, error handling, and more.
Error handling
While having easy access to information about the current state of the callstack can be helpful in many places, the most obvious application is in error handling and debugging.
julia> @noinline bad_function() = undeclared_variable bad_function (generic function with 1 method) julia> @noinline example() = try bad_function() catch stacktrace() end example (generic function with 1 method) julia> example() 5-element Array{StackFrame,1}: example() at REPL[2]:4 eval(::Module, ::Any) at boot.jl:236 [...]
You may notice that in the example above the first stack frame points points at line 4, where stacktrace()
is called, rather than line 2, where bad_function is called, and bad_function
's frame is missing entirely. This is understandable, given that stacktrace()
is called from the context of the catch. While in this example it's fairly easy to find the actual source of the error, in complex cases tracking down the source of the error becomes nontrivial.
This can be remedied by calling catch_stacktrace()
instead of stacktrace()
. Instead of returning callstack information for the current context, catch_stacktrace()
returns stack information for the context of the most recent exception:
julia> @noinline bad_function() = undeclared_variable bad_function (generic function with 1 method) julia> @noinline example() = try bad_function() catch catch_stacktrace() end example (generic function with 1 method) julia> example() 6-element Array{StackFrame,1}: bad_function() at REPL[1]:1 example() at REPL[2]:2 [...]
Notice that the stack trace now indicates the appropriate line number and the missing frame.
julia> @noinline child() = error("Whoops!") child (generic function with 1 method) julia> @noinline parent() = child() parent (generic function with 1 method) julia> @noinline function grandparent() try parent() catch err println("ERROR: ", err.msg) catch_stacktrace() end end grandparent (generic function with 1 method) julia> grandparent() ERROR: Whoops! 7-element Array{StackFrame,1}: child() at REPL[1]:1 parent() at REPL[2]:1 grandparent() at REPL[3]:3 [...]
Comparison with backtrace()
A call to backtrace()
returns a vector of Ptr{Void}
, which may then be passed into stacktrace()
for translation:
julia> trace = backtrace() 21-element Array{Ptr{Void},1}: Ptr{Void} @0x00007f10049d5b2f Ptr{Void} @0x00007f0ffeb4d29c Ptr{Void} @0x00007f0ffeb4d2a9 Ptr{Void} @0x00007f1004993fe7 Ptr{Void} @0x00007f10049a92be Ptr{Void} @0x00007f10049a823a Ptr{Void} @0x00007f10049a9fb0 Ptr{Void} @0x00007f10049aa718 Ptr{Void} @0x00007f10049c0d5e Ptr{Void} @0x00007f10049a3286 Ptr{Void} @0x00007f0ffe9ba3ba Ptr{Void} @0x00007f0ffe9ba3d0 Ptr{Void} @0x00007f1004993fe7 Ptr{Void} @0x00007f0ded34583d Ptr{Void} @0x00007f0ded345a87 Ptr{Void} @0x00007f1004993fe7 Ptr{Void} @0x00007f0ded34308f Ptr{Void} @0x00007f0ded343320 Ptr{Void} @0x00007f1004993fe7 Ptr{Void} @0x00007f10049aeb67 Ptr{Void} @0x0000000000000000 julia> stacktrace(trace) 5-element Array{StackFrame,1}: backtrace() at error.jl:46 eval(::Module, ::Any) at boot.jl:236 eval_user_input(::Any, ::Base.REPL.REPLBackend) at REPL.jl:66 macro expansion at REPL.jl:97 [inlined] (::Base.REPL.##1#2{Base.REPL.REPLBackend})() at event.jl:73
Notice that the vector returned by backtrace()
had 21 pointers, while the vector returned by stacktrace()
only has 5. This is because, by default, stacktrace()
removes any lower-level C functions from the stack. If you want to include stack frames from C calls, you can do it like this:
julia> stacktrace(trace, true) 27-element Array{StackFrame,1}: jl_backtrace_from_here at stackwalk.c:103 backtrace() at error.jl:46 backtrace() at sys.so:? jl_call_method_internal at julia_internal.h:248 [inlined] jl_apply_generic at gf.c:2215 do_call at interpreter.c:75 eval at interpreter.c:215 eval_body at interpreter.c:519 jl_interpret_toplevel_thunk at interpreter.c:664 jl_toplevel_eval_flex at toplevel.c:592 jl_toplevel_eval_in at builtins.c:614 eval(::Module, ::Any) at boot.jl:236 eval(::Module, ::Any) at sys.so:? jl_call_method_internal at julia_internal.h:248 [inlined] jl_apply_generic at gf.c:2215 eval_user_input(::Any, ::Base.REPL.REPLBackend) at REPL.jl:66 ip:0x7f1c707f1846 jl_call_method_internal at julia_internal.h:248 [inlined] jl_apply_generic at gf.c:2215 macro expansion at REPL.jl:97 [inlined] (::Base.REPL.##1#2{Base.REPL.REPLBackend})() at event.jl:73 ip:0x7f1c707ea1ef jl_call_method_internal at julia_internal.h:248 [inlined] jl_apply_generic at gf.c:2215 jl_apply at julia.h:1411 [inlined] start_task at task.c:261 ip:0xffffffffffffffff
Individual pointers returned by backtrace()
can be translated into StackFrame
s by passing them into StackTraces.lookup()
:
julia> pointer = backtrace()[1]; julia> frame = StackTraces.lookup(pointer) 1-element Array{StackFrame,1}: jl_backtrace_from_here at stackwalk.c:103 julia> println("The top frame is from $(frame[1].func)!") The top frame is from jl_backtrace_from_here!
© 2009–2016 Jeff Bezanson, Stefan Karpinski, Viral B. Shah, and other contributors
Licensed under the MIT License.
https://docs.julialang.org/en/release-0.6/manual/stacktraces/