Skip to content

docs(error-tracking): document android ndk native symbol upload #19035

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
cat-ph wants to merge 1 commit into
base: master
Choose a base branch
from
+27 −2
Draft

docs(error-tracking): document android ndk native symbol upload #19035

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions contents/docs/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ For broad agent workflows, create a [personal API key](https://app.posthog.com/s
| `posthog-cli hermes` | Upload Hermes source maps |
| `posthog-cli proguard` | Upload ProGuard mapping files |
| `posthog-cli symbol-sets` | Manage uploaded symbol sets |
| `posthog-cli symbol-sets upload` | Upload native debug symbols (ELF and Mach-O binaries, Android `.so` files) |
| `posthog-cli exp` | Run experimental commands |
| `posthog-cli help` | Print CLI help or help for a subcommand |

Expand Down
28 changes: 26 additions & 2 deletions contents/docs/error-tracking/upload-mappings/android.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,10 +33,10 @@ Automatic mappings uploading is handled through the Gradle build process on Andr
Install the [PostHog Android Gradle Plugin](https://github.com/PostHog/posthog-android/blob/main/posthog-android-gradle-plugin/CHANGELOG.md) on your app's `build.gradle.kts` file.

```kotlin
// Available through mavenCentral()
// Available through mavenCentral(), use the latest version
plugins {
id("com.android.application")
id("com.posthog.android") version "$version"
id("com.posthog.android") version "1.5.0"
...
}
```
Expand All @@ -57,6 +57,30 @@ You can also set `postHogExecutable` if you want to use a custom `posthog-cli` p

</Step>

<Step title="Upload native debug symbols (NDK)" badge="optional">

> Requires [PostHog Android SDK 3.57.0](https://github.com/PostHog/posthog-android/blob/main/posthog-android/CHANGELOG.md) or later with `errorTrackingConfig.captureNativeCrashes` enabled, [Gradle plugin 1.5.0](https://github.com/PostHog/posthog-android/blob/main/posthog-android-gradle-plugin/CHANGELOG.md) or later, and [CLI 0.7.32](https://github.com/PostHog/posthog/releases/tag/posthog-cli%2Fv0.7.32) or later.

If your app includes native C or C++ code built with the NDK, upload the `.so` debug symbols so native crash stack traces resolve to function names, files, and line numbers.

The Gradle plugin registers an `uploadPostHogNativeSymbols<Variant>` task that reads the variant's unstripped native libraries and uploads every one carrying debug info and a build ID. When your app module builds native code (CMake or ndk-build), the task runs automatically after `assemble`, `install`, or `bundle`, for minified and non-minified builds alike.

If your app only bundles prebuilt `.so` files from dependencies, run the task explicitly:

```bash
./gradlew uploadPostHogNativeSymbolsRelease
```

You can also upload a directory of `.so` files directly, without the Gradle plugin:

```bash
posthog-cli symbol-sets upload --directory app/build/intermediates/merged_native_libs/release
```

PostHog matches crash frames to uploaded symbols by each library's GNU build ID, which the NDK emits by default. Each build has its own build ID, so symbols must be re-uploaded for every build you ship.

</Step>

<StepVerifySymbolSetsUpload symbolType="mappings" />

</Steps>
Loading