From fe0eac8371b8537826a58cc854990512831729e4 Mon Sep 17 00:00:00 2001 From: Catalin Irimie Date: Tue, 28 Jul 2026 19:44:05 +0300 Subject: [PATCH] docs(error-tracking): document android ndk native symbol upload --- contents/docs/cli.mdx | 1 + .../upload-mappings/android.mdx | 28 +++++++++++++++++-- 2 files changed, 27 insertions(+), 2 deletions(-) diff --git a/contents/docs/cli.mdx b/contents/docs/cli.mdx index 163897c69bbf..d63492dfe06f 100644 --- a/contents/docs/cli.mdx +++ b/contents/docs/cli.mdx @@ -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 | diff --git a/contents/docs/error-tracking/upload-mappings/android.mdx b/contents/docs/error-tracking/upload-mappings/android.mdx index 5945c926a0b4..6a809d950a6e 100644 --- a/contents/docs/error-tracking/upload-mappings/android.mdx +++ b/contents/docs/error-tracking/upload-mappings/android.mdx @@ -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" ... } ``` @@ -57,6 +57,30 @@ You can also set `postHogExecutable` if you want to use a custom `posthog-cli` p + + +> 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` 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. + + +