Skip to main content
emisar

Symbolicator native symbolication

v0.2.5

Debug native crashes with Symbolicator and keep the host it runs on healthy. Symbolicate a stack trace, a minidump, or an Apple crash report against the debug files the operator's configured sources hold, follow a request that runs long, and manage what that costs: liveness, build version, the cache footprint filling the disk, and the cleanup — previewed before it runs. Nothing here can publish or alter a symbol; Symbolicator has no ingest path. For the Sentry API itself, see the sentry pack.

9 allowed by default 1 need approval by default
Pack ID
symbolicator
Vendor
emisar
OS
linux
Actions
10
Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.
symbolicator curl jq

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host 
sudo emisar pack install symbolicator --hash sha256:aa251c4a3bd5b0c78bc98725e0c8d470706b28ca98c9183f87ce2d70d83e2452

Setup

The HTTP reads call Symbolicator's own unauthenticated API on the host (127.0.0.1:3021 by default); the CLI actions run the symbolicator binary against the configuration the service uses. Neither takes credentials — Symbolicator has no auth of its own, so restrict reachability at the host.

Environment

Set these on the runner host, then add each name to execution.inherit_env so the value reaches the action.

  • SYMBOLICATOR_URL default http://127.0.0.1:3021

    Base URL of the local Symbolicator HTTP API.

  • SYMBOLICATOR_CONFIG default /etc/symbolicator/config.yml

    Configuration file the CLI actions read.

  • SYMBOLICATOR_CACHE_DIR

    Cache root, when it should not be read from the configuration's cache_dir. Falls back to /data, the image and self-hosted default.

Host access

Run these commands yourself on the runner host. Emisar shows and copies setup recipes; it never runs them.

Read protected crash inputs, configuration, and cache, and delete expired cache entries.

symbolicator.symbolicate_minidumpsymbolicator.symbolicate_apple_crashsymbolicator.cache_usagesymbolicator.cleanup_previewsymbolicator.cleanupsymbolicator.config_show

Run the Emisar service as root

Grant access 
sudo install -d -m 0755 /etc/systemd/system/emisar.service.d
printf '%s\n' '[Service]' 'User=root' 'Group=root' | sudo tee /etc/systemd/system/emisar.service.d/10-symbolicator-host-access.conf >/dev/null
sudo systemctl daemon-reload
sudo systemctl restart emisar
Verify access 
test "$(systemctl show emisar --property=User --value)" = root

Impact: Every Emisar action on this runner executes as root. The configuration may contain source credentials, and cleanup can delete every cache entry Symbolicator deems expired.

Notes

  • Any of these you set must also be allowlisted in the runner's execution.inherit_env — the action env is scrubbed to PATH/LANG/LC_ALL/TERM by default, so a variable present on the host but not allowlisted is silently dropped and the action falls back to its default.
  • Symbolicator's API is unauthenticated by design; it expects to be reachable only from Sentry's own network. These actions do not add authentication, they inherit whatever the host allows.

Verify it works

Runs symbolicator.health, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host 
sudo emisar pack verify symbolicator

Install and configure a pack walks through the whole sequence on a host.

Actions 10 total

View on GitHub
  • symbolicator.cache_usage script low Low — read-only or trivially reversible

    Symbolicator cache footprint

    Show how much disk each Symbolicator cache holds, largest first, with the filesystem underneath it. The caches — objects, symcaches, cficaches and the rest — are what fills a symbolication host, and they grow at very different rates, so this is the read to take before deciding whether a cleanup is the answer.

    View source on GitHub
  • symbolicator.cleanup exec medium Medium — changes state, easily reversible

    symbolicator cleanup

    Delete the cache entries that have gone unused past their configured retention, reclaiming disk. This is Symbolicator's own routine maintenance, bounded by the retention windows in its configuration — not a wipe. Preview it with symbolicator.cleanup_preview first.

    View source on GitHub
  • symbolicator.cleanup_preview exec low Low — read-only or trivially reversible

    symbolicator cleanup --dry-run

    Show what a cache cleanup would remove and what it would keep, per cache, without deleting anything. Symbolicator prints retained and removed byte counts for each cache, so this is the read that decides whether symbolicator.cleanup is worth running.

    View source on GitHub
  • symbolicator.config_show exec high High — service-affecting

    Show symbolicator config.yml

    Dump the Symbolicator configuration this host runs — cache root, retention windows, bind address, and the symbol sources. Reading it is how you explain why a cleanup reclaimed nothing or why a symbol never resolves. High risk on purpose: the sources block is operator-authored and routinely holds S3, GCS, or HTTP credentials, so the whole file is treated as secret-bearing rather than trusted to a pattern.

    View source on GitHub
  • symbolicator.health exec low Low — read-only or trivially reversible

    GET /healthcheck

    Check whether Symbolicator is serving on this host. Answers "ok" while the HTTP server is up; a connection error means the service is down or bound somewhere other than SYMBOLICATOR_URL.

    View source on GitHub
  • symbolicator.request_status exec low Low — read-only or trivially reversible

    GET /requests/<id>

    Show the status of one symbolication request by its id — whether it is still pending or has completed, and its result when it has. Use it when Sentry reports a symbolication that never came back. An unknown or expired id answers 404.

    View source on GitHub
  • symbolicator.symbolicate exec low Low — read-only or trivially reversible

    POST /symbolicate

    Symbolicate a native stack trace — turn instruction addresses into function names, files, and line numbers using the debug files this Symbolicator already has access to. Send the crash's modules and frames; the symbols come from the sources the operator configured, never from the request.

    View source on GitHub
  • symbolicator.symbolicate_apple_crash exec low Low — read-only or trivially reversible

    POST /applecrashreport

    Symbolicate an Apple crash report already on this host — the iOS or macOS .crash text a device produced — against the debug files this Symbolicator has access to. Answers with the symbolicated result, or with a request id to follow using symbolicator.request_status when the work runs long.

    View source on GitHub
  • symbolicator.symbolicate_minidump exec low Low — read-only or trivially reversible

    POST /minidump

    Symbolicate a minidump already on this host — the crashing thread, its stack, and the loaded modules, resolved against the debug files this Symbolicator has access to. Answers with the symbolicated result, or with a request id to follow using symbolicator.request_status when the work runs long.

    View source on GitHub
  • symbolicator.version exec low Low — read-only or trivially reversible

    symbolicator --version

    Show the Symbolicator build installed on this host — release version and git commit. Reports the binary on disk, which is what a restart would start.

    View source on GitHub
← Back to registry
Pack reference  Publish your own