165 lines
6.1 KiB
Markdown
165 lines
6.1 KiB
Markdown
# Crash reporting — Sentry SDK on GlitchTip
|
|
|
|
"Donemat - Breton d'Auray" reports crashes and handled errors with the
|
|
[Sentry Kotlin Multiplatform SDK](https://docs.sentry.io/platforms/kotlin/guides/kotlin-multiplatform/),
|
|
but sends them to [GlitchTip](https://glitchtip.com) instead of Sentry. GlitchTip is an
|
|
open-source, Sentry-API-compatible backend, so the Sentry SDKs and `glitchtip-cli` work against
|
|
it unchanged — only the DSN (and the CLI's `url`) point somewhere else.
|
|
|
|
Our instance is the hosted EU one: <https://eu.glitchtip.com>.
|
|
|
|
| | |
|
|
|-----------------------|------------------------------------------------------------------------------------------------------|
|
|
| SDK | `io.sentry.kotlin.multiplatform` (see `sentry` in `gradle/libs.versions.toml`) |
|
|
| Gradle plugin | `io.sentry.kotlin.multiplatform.gradle`, applied in `shared/build.gradle.kts` |
|
|
| iOS native dependency | `sentry-cocoa` via Swift Package Manager, declared in the Xcode project |
|
|
| Initialisation | `initializeSentry()` in `shared/src/commonMain/kotlin/bzh/ajaury/chombev/SentryHelper.kt` |
|
|
| Called from | `ChomBevApp.onCreate()` (Android), `AppDelegate.application(_:didFinishLaunchingWithOptions:)` (iOS) |
|
|
|
|
There are two distinct pieces of configuration, and they are easy to confuse:
|
|
|
|
1. **The DSN** — where the *app* sends events at runtime. Injected at build time from
|
|
`local.properties`. See [Runtime configuration](#1-runtime-configuration--the-dsn).
|
|
2. **The auth token** — how *your machine or CI* uploads debug symbols to GlitchTip.
|
|
Stored in `.sentryclirc`. See [CLI configuration](#2-cli-configuration--sentryclirc).
|
|
|
|
Neither is committed.
|
|
|
|
---
|
|
|
|
## 1. Runtime configuration — the DSN
|
|
|
|
The DSN is a write-only endpoint URL identifying the GlitchTip project. It is kept out of
|
|
version control by the `gwenedeg.secrets` convention plugin
|
|
(`build-logic/src/main/kotlin/gwenedeg.secrets.gradle.kts`), which reads it at build
|
|
time and generates an internal `BuildSecrets` object into `commonMain`.
|
|
|
|
### Setup
|
|
|
|
Add the DSN to `local.properties` at the repository root (this file is git-ignored):
|
|
|
|
```properties
|
|
glitchtip.dsn=https://<key>@eu.glitchtip.com/<project-id>
|
|
```
|
|
|
|
Find the value in GlitchTip under **Settings → Projects → _Donemat_ → Client Keys (DSN)**.
|
|
|
|
On CI, set the `GLITCHTIP_DSN` environment variable instead — it takes precedence over
|
|
`local.properties`.
|
|
|
|
### Behaviour when it is missing
|
|
|
|
`initializeSentry()` returns early when the DSN is blank, so a fresh clone builds and runs
|
|
with crash reporting simply disabled. No placeholder or dummy DSN is needed.
|
|
|
|
### Adding other secrets
|
|
|
|
Extend the `secret(environmentVariable, localPropertyKey)` helper in the convention plugin
|
|
rather than hardcoding values in Kotlin sources.
|
|
|
|
---
|
|
|
|
## 2. CLI configuration — `.sentryclirc`
|
|
|
|
`sentry-cli` needs an auth token to upload debug symbols. It reads its settings from a
|
|
`.sentryclirc` INI file in the current working directory (and from `~/.sentryclirc`),
|
|
or from environment variables.
|
|
|
|
> **`.sentryclirc` contains a credential and must never be committed.**
|
|
> It is listed in `.gitignore`. Only `.sentryclirc.example` is versioned.
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
cp .sentryclirc.example .sentryclirc
|
|
chmod 600 .sentryclirc
|
|
```
|
|
|
|
Then edit `.sentryclirc` and replace the token placeholder:
|
|
|
|
```ini
|
|
[auth]
|
|
token=<your-glitchtip-auth-token>
|
|
|
|
[defaults]
|
|
url=https://eu.glitchtip.com/
|
|
org=kerlenn-sten-kidna
|
|
project=chom-bev-e-brezhoneg
|
|
```
|
|
|
|
- `url` is mandatory: without it `glitchtip-cli` talks to sentry.io, not GlitchTip.
|
|
- `org` and `project` are the *slugs* shown in the GlitchTip URLs, not the display names.
|
|
|
|
### Creating the token
|
|
|
|
In GlitchTip: **user menu → Profile → Auth Tokens → Create New Token**. Grant it at least
|
|
`project:read`, `project:write` and `project:releases`. Copy the token immediately — it is
|
|
shown only once.
|
|
|
|
### On CI
|
|
|
|
Do not write the file. Export the equivalent environment variables, sourced from your CI
|
|
secret store:
|
|
|
|
```bash
|
|
export SENTRY_URL=https://eu.glitchtip.com/
|
|
export SENTRY_ORG=kerlenn-sten-kidna
|
|
export SENTRY_PROJECT=chom-bev-e-brezhoneg
|
|
export SENTRY_AUTH_TOKEN=***
|
|
```
|
|
|
|
### Installing glitchtip-cli
|
|
|
|
```bash
|
|
curl -fsSL https://glitchtip.com/install.sh | sh
|
|
```
|
|
|
|
Check that the configuration resolves:
|
|
|
|
```bash
|
|
glitchtip-cli info
|
|
```
|
|
|
|
It should print the GlitchTip URL and report the token as valid.
|
|
|
|
---
|
|
|
|
## 3. iOS Archive — uploading dSYM files
|
|
|
|
### Why this is needed
|
|
|
|
A release iOS binary ships without symbol names. Without the matching dSYM, GlitchTip shows
|
|
crash frames as raw memory addresses. Uploading the dSYM lets it resolve them back to
|
|
function names and line numbers.
|
|
|
|
The shared Kotlin framework is linked **statically** (`isStatic = true` in
|
|
`shared/build.gradle.kts`), so Kotlin/Native frames end up in the app's own dSYM — there is
|
|
no separate framework dSYM to upload.
|
|
|
|
### Prerequisites
|
|
|
|
You need `glitchtip-cli` installed and `.sentryclirc` filled in ([section 2](#2-cli-configuration--sentryclirc)).
|
|
|
|
### Upload after an archive
|
|
|
|
1. **Product → Archive** in Xcode.
|
|
2. In the Organizer, right-click the archive → **Show in Finder**.
|
|
3. Right-click the `.xcarchive` → **Show Package Contents**.
|
|
4. Upload the `dSYMs` folder:
|
|
|
|
```bash
|
|
cd /path/to/Gwenedeg
|
|
glitchtip-cli debug-files upload /path/to/Gwenedeg.xcarchive/dSYMs
|
|
```
|
|
|
|
Add `--include-sources` if you also want source context attached to native frames.
|
|
|
|
## 4. References
|
|
|
|
- [Sentry — Kotlin Multiplatform SDK](https://docs.sentry.io/platforms/kotlin/guides/kotlin-multiplatform/)
|
|
- [Sentry — Uploading debug symbols for Apple platforms](https://docs.sentry.io/platforms/apple/guides/ios/dsym/)
|
|
- [Sentry — data collected by the SDK](https://docs.sentry.io/platforms/kotlin/guides/kotlin-multiplatform/data-management/data-collected/)
|
|
- [GlitchTip documentation](https://glitchtip.com/documentation)
|
|
- [GlitchTip CLI documentation](https://glitchtip.com/documentation/cli)
|
|
- [Kotlin — symbolicating iOS crash reports](https://kotlinlang.org/docs/native-ios-symbolication.html)
|