Stack Trace Interface

A stack trace contains a list of frames, each with various bits (most optional) describing the context of that frame. Frames should be sorted from oldest to newest.

Stack traces are always part of an exception or a thread. They cannot be declared as a top-level event property. When adding a stack trace to an event, follow this rule of thumb:

frames
Required. A non-empty list of stack frames (see below). The list is
ordered from caller to callee, or oldest to youngest. The last frame is the
one creating the exception.
registers
Optional. A map of register names and their values. The values should
contain the actual register values of the thread, thus mapping to the last
frame in the list.

Each object should contain at least a filename, function or instruction_addr attribute. All values are optional, but recommended.

filename
The path to the source file relative to the project root directory.

The value should not make file names indistinguishable and should only change between releases for files that were actually renamed.

In some SDKs, this is implemented as the path relative to a certain entry point relevant to the language/platform. For example, in Python the filename is relative to PYTHONPATH or site-packages.

function
The name of the function being called.

This function name may be shortened or demangled. If not, Sentry will demangle and shorten it. The original function name will be stored in raw_function.

raw_function
The original function name, if the function name is shortened or demangled.
Sentry shows the raw function when clicking on the shortened one in the UI.
module
Platform-specific module path (e.g. sentry.interfaces.Stacktrace).
lineno
The line number of the call, starting at 1.
colno
The column number of the call, starting at 1.
abs_path
The absolute path to the source file.
context_line
Source code in filename at lineno.
pre_context
A list of source code lines before context_line (in order) – usually
[lineno - 5:lineno].
post_context
A list of source code lines after context_line (in order) – usually
[lineno + 1:lineno + 5].
source_link
A URL representing the source code, e.g. commit-specific GitHub raw source link:
https://raw.githubusercontent.com/getsentry/symbolicator/706d879a426a54230d91799a46a79376ffc86cf3/crates/symbolicator-service/src/types/mod.rs
in_app
Signals whether this frame is related to the execution of the relevant code
in this stack trace. For example, the frames that might power the framework’s
web server of your app are probably not relevant. However, calls to the
framework’s library once you start handling code likely are relevant.
stack_start
Marks this frame as the bottom of a chained stack trace. Stack traces from
asynchronous code consist of several sub traces that are chained together into
one large list. This flag indicates the root function of a chained stack trace.
Depending on the runtime and thread, this is either the main function or a
thread base stub. This field should only be specified when true.
vars
A mapping of variables which were available within this frame (usually
context-locals).

The following attributes are primarily used for C-based languages:

instruction_addr
An optional instruction address for symbolication. This should be a string
with a hexadecimal number that includes a 0x prefix. If this is set and a
known image is defined in the Debug Meta Interface, then
symbolication can take place. Note that the addr_mode attribute can
control the behavior of this address.
addr_mode
Optionally changes the addressing mode. The default value is the same as "abs"
which means absolute referencing. This can also be set to "rel:DEBUG_ID" or
"rel:IMAGE_INDEX" to make addresses relative to an object referenced by debug id
or index. This for instance is necessary for WASM processing as WASM does not use
a unified address space.
symbol_addr
An optional address that points to a symbol. We use the instruction
address for symbolication, but this can be used to calculate an instruction
offset automatically. Note that the addr_mode attribute can
control the behavior of this address.
image_addr
Optionally an address of the debug image to reference.
package
The "package" the frame was contained in. Depending on the platform, this can
be different things. For C#, it can be the name of the assembly. For native
code, it can be the path of the dynamic library, etc.
platform
This can override the platform for a single frame. Otherwise, the platform of
the event is assumed. This can be used for multi-platform stack traces, such
as in React Native.

For the given example program written in Python:

Copied
def foo():
  my_var = 'foo'
  raise ValueError()

def main():
  foo()

A minimalistic stack trace for the above program in the correct order:

Copied
{
  "frames": [{ "function": "main" }, { "function": "foo" }]
}

The top frame fully populated with five lines of source context:

Copied
{
  "frames": [
    {
      "in_app": true,
      "function": "myfunction",
      "abs_path": "/real/file/name.py",
      "filename": "file/name.py",
      "lineno": 3,
      "vars": {
        "my_var": "'value'"
      },
      "pre_context": ["def foo():", "  my_var = 'foo'"],
      "context_line": "  raise ValueError()",
      "post_context": ["", "def main():"]
    }
  ]
}

A minimal native stack trace with register values. Note that the package event attribute must be "native" for these frames to be symbolicated.

Copied
{
  "frames": [
    { "instruction_addr": "0x7fff5bf3456c" },
    { "instruction_addr": "0x7fff5bf346c0" }
  ],
  "registers": {
    "rip": "0x00007ff6eef54be2",
    "rsp": "0x0000003b710cd9e0"
  }
}
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").