https://github.com/getsentry/symbolicator
Native Symbolication as a Service
https://github.com/getsentry/symbolicator
tag-production
Last synced: 28 days ago
JSON representation
Native Symbolication as a Service
- Host: GitHub
- URL: https://github.com/getsentry/symbolicator
- Owner: getsentry
- License: mit
- Created: 2019-02-26T12:16:43.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-05-12T10:39:44.000Z (about 1 month ago)
- Last Synced: 2025-05-15T16:05:32.808Z (29 days ago)
- Topics: tag-production
- Language: Rust
- Homepage: https://getsentry.github.io/symbolicator/
- Size: 13.9 MB
- Stars: 387
- Watchers: 51
- Forks: 61
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
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 `:
- `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](./crates/symbolicli/README.md).
## Compiling
Symbolicator is written in [Rust] and requires the latest stable Rust
compiler.
To compile, run:
```sh
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`:
```python
# Allow Symbolicator's request IP to fetch debug files from Sentry.
INTERNAL_SYSTEM_IPS = ["127.0.0.1"]
```
- In your `~/.sentry/config.yml`:
```yaml
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.
```bash
# 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`:
```bash
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:
```bash
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:
```bash
# 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:
```bash
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:
```bash
# Format the entire codebase
make format
# Run clippy on the entire codebase
make lint
```
[documentation]: https://getsentry.github.io/symbolicator/
[sentry]: https://github.com/getsentry/sentry
[minidumps]: https://docs.sentry.io/platforms/minidump/
[symbol server]: https://en.wikipedia.org/wiki/Microsoft_Symbol_Server
[symbolic]: https://github.com/getsentry/symbolic
[rust]: https://www.rust-lang.org/