Skip to content

Android App Optimization Stack-Trace Decoding Plan

Last updated: 2026-05-26 Reference: https://developer.android.com/topic/performance/app-optimization/enable-app-optimization#decode-stack-trace

Goal

Ensure obfuscated Android release crashes can be decoded quickly and reliably for every shipped build.

Scope

  • Android release builds only (Expo/EAS managed workflow with native Android output)
  • Obfuscated stack traces generated by R8/ProGuard optimization
  • Operational runbook for engineering and support

Out of Scope

  • iOS symbolication changes (separate flow with dSYM)
  • Full observability platform migration

Milestones

Milestone 1: Baseline and Build Metadata (Week 1)

  1. Confirm release optimization state in the Android build profile (minification/obfuscation enabled where applicable).
  2. Record immutable release identifiers for each build:
  3. app version name
  4. Android version code
  5. EAS build ID
  6. git commit SHA
  7. Define a canonical release key format:
  8. android:{versionName}+{versionCode}:{commitSha}

Milestone 2: Mapping Retention (Week 1-2)

  1. Persist mapping.txt for every release build as an artifact.
  2. Store mappings in durable storage with retention policy (minimum 18 months).
  3. Enforce naming convention:
  4. mapping-{versionName}-{versionCode}-{commitSha}.txt
  5. Add a build check that fails if the release mapping file is missing.

Milestone 3: Decode Workflow (Week 2)

  1. Add an internal runbook section for Retrace-based decoding.
  2. Standard decode command template:
retrace \
  --mapping mapping-{versionName}-{versionCode}-{commitSha}.txt \
  stacktrace.txt > stacktrace.decoded.txt
  1. Define intake process for crash logs:
  2. capture raw stack trace
  3. identify build version/code
  4. locate matching mapping file
  5. retrace and attach decoded output to incident/ticket

Milestone 4: Crash Platform Integration (Week 2-3)

  1. For the active crash backend (Sentry), automate upload of mapping/symbol artifacts per release.
  2. Verify decoded stack traces appear automatically in crash events for one staging and one production candidate build.
  3. Keep manual Retrace path as fallback if upload fails.

Milestone 5: Validation and Handoff (Week 3)

  1. Run a fire-drill with a known obfuscated test stack trace.
  2. Measure time-to-decode target: under 10 minutes from report to readable stack.
  3. Publish final runbook and assign ownership for release operations.

Acceptance Criteria

  • Every Android release has a stored mapping file with traceable release metadata.
  • On-call can decode any obfuscated Android stack trace without ad hoc steps.
  • Crash platform shows deobfuscated traces for new releases.
  • A documented fallback Retrace process is tested and available.

Risks and Mitigations

  • Missing mapping file for a release:
  • Mitigation: block release completion when artifact upload fails.
  • Incorrect build-to-mapping matching:
  • Mitigation: strict release key format and metadata checks in CI.
  • Crash platform ingestion mismatch:
  • Mitigation: run staging verification on every release candidate.

Deliverables

  • Roadmap entry in project planning.
  • Build artifact retention policy for Android mapping files.
  • Operational runbook for stack-trace decoding.
  • Automated mapping upload in release pipeline.
  • Verification checklist for staging/production release readiness.

iOS Equivalent Setup (Required)

Yes. iOS needs an equivalent symbolication pipeline, even though the artifact types differ.

iOS Artifacts and Correlation

  1. Persist dSYM artifacts for every App Store/TestFlight release build.
  2. Preserve JS sourcemaps and Hermes debug artifacts for the exact same build.
  3. Use a canonical iOS release key to correlate native and JS symbols:
  4. ios:{versionName}+{buildNumber}:{commitSha}

iOS Crash Decoding Workflow

  1. Ensure crash backend receives native dSYMs and JS sourcemaps for each release.
  2. Verify one staging and one production candidate build with a forced test crash.
  3. Document fallback manual symbolication flow for native crash logs when auto-symbolication fails.

iOS Acceptance Criteria

  • Every iOS release has retained dSYM and JS sourcemap artifacts.
  • New iOS crashes are symbolicated automatically in Sentry.
  • On-call can manually symbolicate from retained artifacts when automation fails.

iOS Operational Notes for This Repo

  • Sentry integration is already conditionally enabled via Expo config when error-reporting and build-time Sentry variables are present.
  • Keep these variables configured in EAS environments used for release builds:
  • EXPO_PUBLIC_ENABLE_ERROR_REPORTING=true
  • EXPO_PUBLIC_SENTRY_DSN
  • SENTRY_ORG
  • SENTRY_PROJECT
  • SENTRY_AUTH_TOKEN

Suggested Implementation Sequence

  1. Turn on Sentry env vars in EAS staging and production release environments.
  2. Run an iOS release build and confirm dSYM/sourcemap upload in Sentry release artifacts.
  3. Trigger a controlled test error in staging, verify symbolicated native and JS frames.
  4. Add a release checklist item requiring artifact presence verification before store submission.