Sentry support

ManiVault: Crash & Error Reporting with Sentry (Windows Release Builds)

ManiVault supports crash and error reporting via Sentry. When the application crashes, ManiVault lets users opt in to send crash information to our self-hosted Sentry: https://lkebsentry.nl/. On this portal, plugin developers can debug crash reports and trace where and why failures occur.

For best results, Sentry needs symbol files (PDBs). These make raw stack traces human-readable (function names, file/line) and can show source code context at failure locations.

Scope: Currently, Sentry upload is supported for Windows Release builds only.

---

Prerequisites

1. Sentry project exists on the self-hosted instance (https://lkebsentry.nl/):
   • A Project for your ManiVault plugin(s).
   • A Server DSN configured in your app so crashes are actually sent.
2. Sentry API token with permissions to upload debug files:
   • Typically project:write (or project:releases) and org:read.
3. GitHub Actions secrets available to the repo (or org):
   • LKEB_SENTRY_URL – e.g., https://lkebsentry.nl/
   • LKEB_SENTRY_ORG – Sentry organization slug (e.g., lkeb)
   • LKEB_SENTRY_PROJECT – project slug (e.g., manivault)
   • LKEB_SENTRY_AUTH_TOKEN – API token from step 2
     (Existing Conan/deploy secrets remain as in your current workflow.)
4. Windows build produces PDBs (symbols):
   • MSVC: compile with /Zi and link with /DEBUG.
   • CMake examples:
     • -DCMAKE_MSVC_DEBUG_INFORMATION_FORMAT=ProgramDatabase
     • or add to Release flags:
       CMAKE_CXX_FLAGS_RELEASE="/Zi" and CMAKE_EXE_LINKER_FLAGS_RELEASE="/DEBUG"
5. (Optional) Source context
   • Enable source upload if supported by the action; this shows code around failing lines in Sentry.

Where to define the secrets

• Prefer Organization secrets so all plugin repos can reuse them:
  GitHub → Organization → Settings → Secrets and variables → Actions → New organization secret.
• For forks or standalone repos, add them as Repository secrets.

---

Enabling Sentry Uploads in Your Workflow

Edit: <repo_name>/.github/workflows/build.yml
Add the sentry* inputs to the Windows job:

- if: startsWith(runner.os, 'Windows')
  uses: ManiVaultStudio/github-actions/conan_windows_build@main
  with:
    conan-visual-version: ${{ matrix.build-cversion }}
    conan-visual-runtime: ${{ matrix.build-runtime }}
    conan-build-type: ${{ matrix.build-config }}
    conan-user: ${{ secrets.LKEB_UPLOAD_USER }}
    conan-password: ${{ secrets.LKEB_UPLOAD_USER_PASSWORD }}
    conan-pem: ${{ secrets.LKEB_UPLOAD_CERT_CHAIN }}
    rs_ssh_key: ${{ secrets.RULESSUPPORT_DEPLOY_KEY }}

    # Upload symbols only from release branches:
    sentry-upload: ${{ startsWith(github.ref, 'refs/heads/release/') }}

    # Self-hosted Sentry connection:
    sentry-url: ${{ secrets.LKEB_SENTRY_URL }}
    sentry-org: ${{ secrets.LKEB_SENTRY_ORG }}
    sentry-project: ${{ secrets.LKEB_SENTRY_PROJECT }}
    sentry-auth-token: ${{ secrets.LKEB_SENTRY_AUTH_TOKEN }}

This ensures the correct PDBs (and, if configured, sources) are uploaded to Sentry alongside your artifacts.

Tip: Set your app’s SENTRY_RELEASE (or equivalent) to match CI (e.g., commit SHA or name@version+commit) to improve symbol matching.

---

Verifying Uploads (Symbols & Events)

1. Trigger a release build
   Push to a release branch (e.g., release/x.y.z) so sentry-upload evaluates to true.

2. Confirm debug files in Sentry
   In Sentry, open Project → Settings → Debug Files (or Releases → Artifacts/Debug Files) and verify new PDBs appear for your latest build.

3. Send a test crash
   Run a build that points to the same DSN and release; generate a known crash.

   • In Issues, open the event:
     • Stack frames should be symbolicated (function names, file:line).
     • If source upload is enabled, you’ll see source context around the failing line.

4. Check release matching
   Ensure the app’s release identifier equals the one used when uploading symbols.

---

Troubleshooting

• No symbolication / “unknown” frames

  • PDBs weren’t uploaded or don’t match the binary.
  • Confirm PDBs exist under Debug Files and that the event’s debug image UUID matches an uploaded file.

• Event arrives but no source code context

  • Sources weren’t uploaded. Enable source upload in your action (if supported) or verify paths aren’t stripped.

• Upload step skipped

  • sentry-upload condition evaluated to false. Check the branch name and that you are building Release.

• Release build has no PDBs

  • Confirm MSVC/CMake flags (/Zi, /DEBUG, or CMAKE_MSVC_DEBUG_INFORMATION_FORMAT=ProgramDatabase).

• Auth errors in CI logs

  • Verify LKEB_SENTRY_AUTH_TOKEN scope and that all sentry* secrets are available to the workflow (org vs repo).

---

FAQ

Q: Can I enable this for Debug or non-Windows builds?
A: The current pipeline supports Windows Release. Extending to other configs/platforms is possible but not covered here.

Q: Do I need to upload on every commit?
A: Upload on builds that produce binaries you ship/test and that may generate crash reports. The example gates uploads to release/* branches.