Stack Traces

TheStackTraces 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 isstacktrace:

6-element Array{Base.StackTraces.StackFrame,1}: top-level scope eval at boot.jl:317 [inlined] eval(::Module, ::Expr) at REPL.jl:5 eval_user_input(::Any, ::REPL.REPLBackend) at REPL.jl:85 macro expansion at REPL.jl:116 [inlined] (::getfield(REPL, Symbol("##28#29")){REPL.REPLBackend})() at event.jl:92

Callingstacktrace() returns a vector ofStackTraces.StackFrame s. For ease of use, the aliasStackTraces.StackTrace can be used in place ofVector{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()7-element Array{Base.StackTraces.StackFrame,1}: example() at REPL[1]:1 top-level scope eval at boot.jl:317 [inlined][...]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()9-element Array{Base.StackTraces.StackFrame,1}: child() at REPL[3]:1 parent() at REPL[4]:1 grandparent() at REPL[5]:1[...]

Note that when callingstacktrace() you'll typically see a frame witheval at boot.jl. When callingstacktrace() from the REPL you'll also have a few extra frames in the stack fromREPL.jl, usually looking something like this:

julia> example() = stacktrace()example (generic function with 1 method)julia> example()7-element Array{Base.StackTraces.StackFrame,1}: example() at REPL[1]:1 top-level scope eval at boot.jl:317 [inlined] eval(::Module, ::Expr) at REPL.jl:5 eval_user_input(::Any, ::REPL.REPLBackend) at REPL.jl:85 macro expansion at REPL.jl:116 [inlined] (::getfield(REPL, Symbol("##28#29")){REPL.REPLBackend})() at event.jl:92

Extracting useful information

EachStackTraces.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 bybacktrace:

julia> frame = stacktrace()[3]eval(::Module, ::Expr) at REPL.jl:5julia> frame.func:evaljulia> frame.fileSymbol("~/julia/usr/share/julia/stdlib/v0.7/REPL/src/REPL.jl")julia> frame.line5julia> frame.linfoMethodInstance for eval(::Module, ::Expr)julia> frame.inlinedfalsejulia> frame.from_cfalsejulia> frame.pointer0x00007f92d6293171

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_variablebad_function (generic function with 1 method)julia> @noinline example() = try           bad_function()       catch           stacktrace()       endexample (generic function with 1 method)julia> example()7-element Array{Base.StackTraces.StackFrame,1}: example() at REPL[2]:4 top-level scope eval at boot.jl:317 [inlined][...]

You may notice that in the example above the first stack frame points at line 4, wherestacktrace is called, rather than line 2, wherebad_function is called, andbad_function's frame is missing entirely. This is understandable, given thatstacktrace is called from the context of thecatch. 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 passing the result ofcatch_backtrace tostacktrace. Instead of returning callstack information for the current context,catch_backtrace returns stack information for the context of the most recent exception:

julia> @noinline bad_function() = undeclared_variablebad_function (generic function with 1 method)julia> @noinline example() = try           bad_function()       catch           stacktrace(catch_backtrace())       endexample (generic function with 1 method)julia> example()8-element Array{Base.StackTraces.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)               stacktrace(catch_backtrace())           end       endgrandparent (generic function with 1 method)julia> grandparent()ERROR: Whoops!10-element Array{Base.StackTraces.StackFrame,1}: error at error.jl:33 [inlined] child() at REPL[1]:1 parent() at REPL[2]:1 grandparent() at REPL[3]:3[...]

Exception stacks andcurrent_exceptions

While handling an exception further exceptions may be thrown. It can be useful to inspect all these exceptions to identify the root cause of a problem. The julia runtime supports this by pushing each exception onto an internalexception stack as it occurs. When the code exits acatch normally, any exceptions which were pushed onto the stack in the associatedtry are considered to be successfully handled and are removed from the stack.

The stack of current exceptions can be accessed using thecurrent_exceptions function. For example,

julia> try           error("(A) The root cause")       catch           try               error("(B) An exception while handling the exception")           catch               for (exc, bt) in current_exceptions()                   showerror(stdout, exc, bt)                   println(stdout)               end           end       end(A) The root causeStacktrace: [1] error(::String) at error.jl:33 [2] top-level scope at REPL[7]:2 [3] eval(::Module, ::Any) at boot.jl:319 [4] eval_user_input(::Any, ::REPL.REPLBackend) at REPL.jl:85 [5] macro expansion at REPL.jl:117 [inlined] [6] (::getfield(REPL, Symbol("##26#27")){REPL.REPLBackend})() at task.jl:259(B) An exception while handling the exceptionStacktrace: [1] error(::String) at error.jl:33 [2] top-level scope at REPL[7]:5 [3] eval(::Module, ::Any) at boot.jl:319 [4] eval_user_input(::Any, ::REPL.REPLBackend) at REPL.jl:85 [5] macro expansion at REPL.jl:117 [inlined] [6] (::getfield(REPL, Symbol("##26#27")){REPL.REPLBackend})() at task.jl:259

In this example the root cause exception (A) is first on the stack, with a further exception (B) following it. After exiting both catch blocks normally (i.e., without throwing a further exception) all exceptions are removed from the stack and are no longer accessible.

The exception stack is stored on theTask where the exceptions occurred. When a task fails with uncaught exceptions,current_exceptions(task) may be used to inspect the exception stack for that task.

Comparison withbacktrace

A call tobacktrace returns a vector ofUnion{Ptr{Nothing}, Base.InterpreterIP}, which may then be passed intostacktrace for translation:

julia> trace = backtrace()18-element Array{Union{Ptr{Nothing}, Base.InterpreterIP},1}: Ptr{Nothing} @0x00007fd8734c6209 Ptr{Nothing} @0x00007fd87362b342 Ptr{Nothing} @0x00007fd87362c136 Ptr{Nothing} @0x00007fd87362c986 Ptr{Nothing} @0x00007fd87362d089 Base.InterpreterIP(CodeInfo(:(begin      Core.SSAValue(0) = backtrace()      trace = Core.SSAValue(0)      return Core.SSAValue(0)  end)), 0x0000000000000000) Ptr{Nothing} @0x00007fd87362e4cf[...]julia> stacktrace(trace)6-element Array{Base.StackTraces.StackFrame,1}: top-level scope eval at boot.jl:317 [inlined] eval(::Module, ::Expr) at REPL.jl:5 eval_user_input(::Any, ::REPL.REPLBackend) at REPL.jl:85 macro expansion at REPL.jl:116 [inlined] (::getfield(REPL, Symbol("##28#29")){REPL.REPLBackend})() at event.jl:92

Notice that the vector returned bybacktrace had 18 elements, while the vector returned bystacktrace only has 6. 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)21-element Array{Base.StackTraces.StackFrame,1}: jl_apply_generic at gf.c:2167 do_call at interpreter.c:324 eval_value at interpreter.c:416 eval_body at interpreter.c:559 jl_interpret_toplevel_thunk_callback at interpreter.c:798 top-level scope jl_interpret_toplevel_thunk at interpreter.c:807 jl_toplevel_eval_flex at toplevel.c:856 jl_toplevel_eval_in at builtins.c:624 eval at boot.jl:317 [inlined] eval(::Module, ::Expr) at REPL.jl:5 jl_apply_generic at gf.c:2167 eval_user_input(::Any, ::REPL.REPLBackend) at REPL.jl:85 jl_apply_generic at gf.c:2167 macro expansion at REPL.jl:116 [inlined] (::getfield(REPL, Symbol("##28#29")){REPL.REPLBackend})() at event.jl:92 jl_fptr_trampoline at gf.c:1838 jl_apply_generic at gf.c:2167 jl_apply at julia.h:1540 [inlined] start_task at task.c:268 ip:0xffffffffffffffff

Individual pointers returned bybacktrace can be translated intoStackTraces.StackFrame s by passing them intoStackTraces.lookup:

julia> pointer = backtrace()[1];julia> frame = StackTraces.lookup(pointer)1-element Array{Base.StackTraces.StackFrame,1}: jl_apply_generic at gf.c:2167julia> println("The top frame is from $(frame[1].func)!")The top frame is from jl_apply_generic!