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()3-elementArray{StackFrame,1}:evalatboot.jl:265[inlinedcodefromREPL.jl:3]eval_user_inputatREPL.jl:62[inlinedcodefromREPL.jl:92]anonymousattask.jl:63Calling 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(genericfunction with1method)julia>example()6-elementArray{StackFrame,1}:inexample()atnone:1ineval(::Module,::Any)atboot.jl:234ineval_user_input(::Any,::Bool)atclient.jl:117ineval(::Module,::Any)atboot.jl:234ineval_user_input(::Any,::Bool)atclient.jl:117in_start()atclient.jl:355julia>@noinlinechild()=stacktrace()child(genericfunction with1method)julia>@noinlineparent()=child()parent(genericfunction with1method)julia>grandparent()=parent()grandparent(genericfunction with1method)julia>grandparent()8-elementArray{StackFrame,1}:inchild()atnone:1inparent()atnone:1ingrandparent()atnone:1...Note that when calling stacktrace() you’ll typically see a frame with
eval(...)atboot.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(genericfunction with1method)julia>example()5-elementArray{StackFrame,1}:inexample()atREPL[1]:1ineval(::Module,::Any)atboot.jl:234ineval_user_input(::Any,::Base.REPL.REPLBackend)atREPL.jl:62inmacroexpansionatREPL.jl:92[inlined]in(::Base.REPL.##1#2{Base.REPL.REPLBackend})() at event.jl:46Extracting 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]ineval(::Module,::Any)atboot.jl:234julia>top_frame.func:evaljulia>top_frame.fileSymbol("./boot.jl")julia>top_frame.line234julia>top_frame.linfoNullable{LambdaInfo}(LambdaInfoforeval(::Module,::Any))julia>top_frame.inlinedfalsejulia>top_frame.from_cfalsejulia>top_frame.pointer13203085684This 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>@noinlinebad_function()=undeclared_variablebad_function(genericfunction with1method)julia>@noinlineexample()=trybad_function()catchstacktrace()endexample(genericfunction with1method)julia>example()6-elementArray{StackFrame,1}:inexample()atnone:4ineval(::Module,::Any)atboot.jl:234...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>@noinlinebad_function()=undeclared_variablebad_function(genericfunction with1method)julia>@noinlineexample()=trybad_function()catchcatch_stacktrace()endexample(genericfunction with1method)julia>example()7-elementArray{StackFrame,1}:inbad_function()atnone:1inexample()atnone:2...Notice that the stack trace now indicates the appropriate line number and the missing frame.
julia>@noinlinechild()=error("Whoops!")child(genericfunction with1method)julia>@noinlineparent()=child()parent(genericfunction with1method)julia>@noinlinefunction grandparent()tryparent()catcherrprintln("ERROR: ",err.msg)catch_stacktrace()endendgrandparent(genericfunction with1method)julia>grandparent()ERROR:Whoops!8-elementArray{StackFrame,1}:inchild()atnone:1inparent()atnone:1ingrandparent()atnone: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()20-elementArray{Ptr{Void},1}:Ptr{Void}@0x0000000100a26fc2Ptr{Void}@0x00000001029435dfPtr{Void}@0x0000000102943635Ptr{Void}@0x00000001009e9620Ptr{Void}@0x00000001009fe1e8Ptr{Void}@0x00000001009fc7b6Ptr{Void}@0x00000001009fdae3Ptr{Void}@0x00000001009fe0d2Ptr{Void}@0x0000000100a1321bPtr{Void}@0x00000001009f64e7Ptr{Void}@0x000000010265ac5dPtr{Void}@0x000000010265acc1Ptr{Void}@0x00000001009e9620Ptr{Void}@0x000000031007744bPtr{Void}@0x0000000310077537Ptr{Void}@0x00000001009e9620Ptr{Void}@0x000000031006feecPtr{Void}@0x00000003100701b0Ptr{Void}@0x00000001009e9635Ptr{Void}@0x0000000100a06418julia>stacktrace(trace)5-elementArray{StackFrame,1}:inbacktrace()aterror.jl:26ineval(::Module,::Any)atboot.jl:231ineval_user_input(::Any,::Base.REPL.REPLBackend)atREPL.jl:62inmacroexpansionatREPL.jl:92[inlined]in(::Base.REPL.##1#2{Base.REPL.REPLBackend})() at event.jl:46Notice that the vector returned by backtrace() had 15 pointers, while the vector returned by stacktrace() only has 4. 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)26-elementArray{StackFrame,1}:injl_backtrace_from_hereatstackwalk.c:104inbacktrace()aterror.jl:26inip:0x102943635injl_call_method_internalatjulia_internal.h:86[inlined]injl_apply_genericatgf.c:1805indo_callatinterpreter.c:65inevalatinterpreter.c:188ineval_bodyatinterpreter.c:469injl_interpret_callatinterpreter.c:573injl_toplevel_eval_flexattoplevel.c:543injl_toplevel_eval_in_warnatbuiltins.c:571ineval(::Module,::Any)atboot.jl:231inip:0x10265acc1injl_call_method_internalatjulia_internal.h:86[inlined]injl_apply_genericatgf.c:1805ineval_user_input(::Any,::Base.REPL.REPLBackend)atREPL.jl:62inip:0x310077537injl_call_method_internalatjulia_internal.h:86[inlined]injl_apply_genericatgf.c:1805inmacroexpansionatREPL.jl:92[inlined]in(::Base.REPL.##1#2{Base.REPL.REPLBackend})() at event.jl:46inip:0x3100701b0injl_call_method_internalatjulia_internal.h:86[inlined]injl_apply_genericatgf.c:1795injl_applyatjulia.h:1388[inlined]instart_taskattask.c:247Individual 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-elementArray{StackFrame,1}:injl_backtrace_from_hereatstackwalk.c:105julia>println("The top frame is from $(frame[1].func)!")Thetopframeisfromjl_backtrace_from_here!