meta: More readme
-# symbolicator
+# Symbolicator
-> The symbolication service to end them all.
+A symbolication service for native stacktraces and minidumps with symbol server
+support.
## Setup
Write this to a file (config.yml):
```yaml
-cache_dir: null
+cache_dir: /tmp/symbolicator
bind: 127.0.0.1:3021
+logging:
+ level: debug
+ format: pretty
+ enable_backtraces: true
+metrics:
+ statsd: 127.0.0.1:8125
+ prefix: symbolicator
+sentry_dsn: https://mykey@sentry.io/4711
```
-- `cache_dir`: Path to a directory, to cache symbols. If it is `null`, there is
- no caching. You really want caching in production. See
- [Caching](#ref-caching).
+- `cache_dir`: Path to a directory to cache downloaded files and symbolication
+ caches. Defaults to `null`, which disables caching. **It is strictly
+ recommended to configure caches in production!** See [Caching](#ref-caching)
+ for more information.
- `bind`: Host and port for HTTP interface.
-- `metrics`: If set, symbolicator will send metrics to a statsd service. See [Metrics](#ref-metrics)
-- `sentry_dsn`: DSN to sentry project to report internal errors to.
+- `logging`: Command line logging behavior.
+ - `level`: Log level, defaults to `info`. Can be one of `off`, `error`,
+ `warn`, `info`, `debug`, or `trace`.
+ - `format`: The format with which to print logs. Defaults to `auto`. Can be
+ one of: `json`, `simplified`, `pretty`, or `auto` (pretty on console,
+ simplified on tty).
+ - `enable_backtraces`: Whether backtraces for errors should be computed. This
+ causes a slight performance hit but improves debuggability. Defaults to
+ `true`.
+- `metrics`: Configure a statsd server to send metrics to. See
+ [Metrics](#ref-metrics) for more information.
+ - `statsd`: The host and port to send metrics to. Defaults to `null`, which
+ disables metric submission.
+ - `prefix`: A prefix for every metric, defaults to `symbolicator`.
+- `sentry_dsn`: DSN to a Sentry project for internal error reporting. Defaults
+ to `null`, which disables reporting to Sentry.
### Starting
-Start the server with: `symbolicator -c ./config.yml run`
+Start the server with:
+
+```bash
+$ symbolicator run -c config.yml
+```
+
+The configuration file can be omitted. Symbolicator will run with default
+settings in this case.
## Caching
@@ -41,7 +72,7 @@ Effectively implementing a LRU cache from the outside of the process. You
should be able to `unlink` files while the server is running without it causing
issues (assuming a POSIX filesystem).
-## Resource usage
+## Resource Usage
`symbolicator` spawns at least two threads per core: one for downloading from
external sources and one for symbolication. Requests are both CPU and IO
