getsentry/symbolicator

A symbolication service for native stacktraces and minidumps with symbol server support. It's a flexible frontend for parts of the symbolic library.

Documentation

Contained Binaries

This repository contains several binary crates that can be run with cargo run -p <PACKAGE>:

• symbolicator: Runs a symbolicator server. Calling cargo run without a package will run this binary.
• symsorter: Sorts debug files into a structure usable by symbolicator.
• wasm-split: Adds build IDs to wasm files.
• symbolicli: Performs symbolication on the CLI. See the readme.

Compiling

Symbolicator is written in Rust and requires the latest stable Rust compiler.

To compile, run:

cargo build --release

The resulting binaries ends up in target/release/ along with debug information files. On Linux, debug information is part of the executable and might need to be stripped using objcopy.

Usage with Sentry

The following requires a recent git version of Sentry.

While Symbolicator aims to not be tied to Sentry's usecases, Sentry has a hard dependency on Symbolicator to process native stacktraces. To get it running for local development:

• In your ~/.sentry/sentry.conf.py:

  # Allow Symbolicator's request IP to fetch debug files from Sentry.
  INTERNAL_SYSTEM_IPS = ["127.0.0.1"]

• In your ~/.sentry/config.yml:

  symbolicator.enabled: true

Then run sentry devservices up to download and start Symbolicator.

Development

To build Symbolicator, we require the latest stable Rust.

We use VSCode for development. This repository contains settings files configuring code style, linters, and useful features. When opening the project for the first time, make sure to install the Recommended Extensions, as they will allow editor assist during coding.

The root of the repository contains a Makefile with useful commands for development:

• make check: Runs code formatting checks and linters. This is useful before opening a pull request.
• make test: Runs unit tests, integration tests and Python package tests (see below for more information).
• make all: Runs all checks and tests. This runs most of the tasks that are also performed in CI.
• make clean: Removes all build artifacts, the virtualenv and cached files.

Building and Running

The easiest way to rebuild and run Symbolicator is using cargo. Depending on the configuration, you may need to have a local instance of Sentry running.

# Rebuild and run with all features
cargo run -- run

For quickly verifying that Symbolicator compiles after making some changes, you can also use cargo check:

cargo check

Local configuration

By default, Symbolicator listens on port 3021. To override this and other configuration values, create a file local.yml in the project root folder. It is excluded from version control by default. Then, start Symbolicator and point to the configuration file:

cargo run -- run --config local.yml

Tests

The test suite comprises unit tests, and integration tests, both of which are implemented as part of the Rust crates and can be run via:

# Tests for default features
make test

Note: On macOS, the default file descriptor limit of 256 is too low and causes test failures. Before running tests, consider to increase is to a higher value:

ulimit -n 4096

Linting

We use rustfmt and clippy from the latest stable channel for code formatting and linting. To make sure that these tools are set up correctly and running with the right configuration, use the following make targets:

# Format the entire codebase
make format

# Run clippy on the entire codebase
make lint