Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

chore(error-tracking): document Flutter Dart symbol uploads (#124824)

Hugues Pouillotba1e6509d0f9
diff --git a/docs/onboarding/error-tracking/flutter.tsx b/docs/onboarding/error-tracking/flutter.tsx
index 3e0f3779e481..e30d7c343c94 100644
--- a/docs/onboarding/error-tracking/flutter.tsx
+++ b/docs/onboarding/error-tracking/flutter.tsx
@@ -3,10 +3,12 @@ import { OnboardingComponentsContext, createInstallation } from 'scenes/onboardi
import { getFlutterSteps as getFlutterStepsPA } from '../product-analytics/flutter'
import { StepDefinition } from '../steps'
+const FLUTTER_ERROR_TRACKING_MIN_VERSION = '5.58.0'
+
export const getFlutterSteps = (ctx: OnboardingComponentsContext): StepDefinition[] => {
const { CodeBlock, Markdown, CalloutBox, dedent } = ctx
- const installSteps = getFlutterStepsPA(ctx)
+ const installSteps = getFlutterStepsPA(ctx, { minVersion: FLUTTER_ERROR_TRACKING_MIN_VERSION })
const exceptionAutocaptureStep: StepDefinition = {
title: 'Set up exception autocapture',
@@ -20,6 +22,11 @@ export const getFlutterSteps = (ctx: OnboardingComponentsContext): StepDefinitio
`}
</Markdown>
</CalloutBox>
+ <Markdown>
+ {dedent`
+ Dart AOT symbolication and background isolate listeners require \`posthog_flutter\` ${FLUTTER_ERROR_TRACKING_MIN_VERSION} or later. If your project uses an earlier version, set \`posthog_flutter: ^${FLUTTER_ERROR_TRACKING_MIN_VERSION}\` in \`pubspec.yaml\` and run \`flutter pub get\`.
+ `}
+ </Markdown>
<Markdown>
{dedent`
You can autocapture exceptions by configuring the \`errorTrackingConfig\` when setting up PostHog:
@@ -52,7 +59,7 @@ export const getFlutterSteps = (ctx: OnboardingComponentsContext): StepDefinitio
| --- | --- |
| \`captureFlutterErrors\` | Captures Flutter framework errors (\`FlutterError.onError\`) |
| \`capturePlatformDispatcherErrors\` | Captures Dart runtime errors (\`PlatformDispatcher.onError\`). Web not supported. |
- | \`captureIsolateErrors\` | Captures errors from main isolate. Web not supported. |
+ | \`captureIsolateErrors\` | Captures errors from the isolate where PostHog is set up. Spawn background isolates paused and call \`isolate.addPostHogErrorListener()\` before resuming them to capture their errors. Web not supported. |
| \`captureNativeExceptions\` | Captures native exceptions. Android (Java/Kotlin) and Apple platforms (iOS, macOS, tvOS). |
| \`captureSilentFlutterErrors\` | Captures Flutter errors that are marked as silent. Default: false. |
`}
@@ -161,29 +168,122 @@ export const getFlutterSteps = (ctx: OnboardingComponentsContext): StepDefinitio
),
}
+ const uploadSymbolsStep: StepDefinition = {
+ title: 'Upload Dart debug symbols',
+ badge: 'optional',
+ content: (
+ <>
+ <Markdown>
+ {dedent`
+ Flutter writes Dart debug symbols for release builds when you pass \`--split-debug-info\`. Upload the symbols for each build you ship so PostHog can show Dart function names and line numbers for Android and iOS exceptions. Add \`--obfuscate\` to the build command if you obfuscate your app.
+ `}
+ </Markdown>
+ <CodeBlock
+ blocks={[
+ {
+ language: 'bash',
+ file: 'Android',
+ code: dedent`
+ flutter build apk --release \\
+ --split-debug-info=build/posthog-symbols/android
+ `,
+ },
+ {
+ language: 'bash',
+ file: 'iOS',
+ code: dedent`
+ flutter build ipa --release \\
+ --split-debug-info=build/posthog-symbols/ios
+ `,
+ },
+ ]}
+ />
+ <Markdown>
+ {dedent`
+ Run these commands from your app's root directory to upload each build's \`.symbols\` files. Sign in with \`posthog-cli login\`, or set \`POSTHOG_CLI_API_KEY\` and \`POSTHOG_CLI_PROJECT_ID\` in CI. Keep each build's symbols in its own directory.
+ `}
+ </Markdown>
+ <CodeBlock
+ blocks={[
+ {
+ language: 'bash',
+ file: 'Android',
+ code: dedent`
+ posthog-cli symbol-sets upload \\
+ --directory build/posthog-symbols/android
+ `,
+ },
+ {
+ language: 'bash',
+ file: 'iOS',
+ code: dedent`
+ posthog-cli symbol-sets upload \\
+ --directory build/posthog-symbols/ios
+ `,
+ },
+ ]}
+ />
+ <Markdown>
+ {dedent`
+ To show [source code context](https://posthog.com/docs/error-tracking/stack-traces), use this command instead of the symbol-only upload. It includes your app's source files:
+ `}
+ </Markdown>
+ <CodeBlock
+ blocks={[
+ {
+ language: 'bash',
+ file: 'Android',
+ code: dedent`
+ posthog-cli symbol-sets upload \\
+ --directory build/posthog-symbols/android \\
+ --include-source --source-root ./lib
+ `,
+ },
+ {
+ language: 'bash',
+ file: 'iOS',
+ code: dedent`
+ posthog-cli symbol-sets upload \\
+ --directory build/posthog-symbols/ios \\
+ --include-source --source-root ./lib
+ `,
+ },
+ ]}
+ />
+ <Markdown>
+ {dedent`
+ \`--source-root ./lib\` limits source files, not symbol files. Run the upload on the build machine while your app source is available. Review your source files before uploading them. See the [CLI debug symbol guide](https://github.com/PostHog/posthog/blob/master/cli/README.md#uploading-native-debug-symbols) for more options.
+ `}
+ </Markdown>
+ </>
+ ),
+ }
+
const futureFeaturesStep: StepDefinition = {
title: 'Future features',
badge: 'optional',
content: (
<Markdown>
{dedent`
- We currently don't support the following features:
+ We currently don't support the following features:
- - No de-obfuscating stacktraces from obfuscated builds ([\\--obfuscate](https://docs.flutter.dev/deployment/obfuscate) and [\\--split-debug-info](https://docs.flutter.dev/deployment/obfuscate)) for Dart code
- - No [Source code context](https://posthog.com/docs/error-tracking/stack-traces) associated with an exception (native Android Java/Kotlin errors and Flutter web only)
- - No native C/C++ exception capture on Android (Java/Kotlin only)
- - No background isolate error capture
+ - Restoring obfuscated Dart exception class names
+ - Capturing native C/C++ exceptions on Android (Java/Kotlin only)
- For symbolicated stack traces on native platforms, see the [Flutter debug symbols guide](https://posthog.com/docs/error-tracking/upload-source-maps/flutter).
-
- These features will be added in future releases. We recommend you stay
- up to date with the latest version of the PostHog Flutter SDK.
- `}
+ For symbolicated native Android and iOS stack traces, see the [Flutter debug symbols guide](https://posthog.com/docs/error-tracking/upload-source-maps/flutter).
+ `}
</Markdown>
),
}
- return [...installSteps, exceptionAutocaptureStep, manualCaptureStep, verifyStep, futureFeaturesStep]
+ return [
+ ...installSteps,
+ exceptionAutocaptureStep,
+ manualCaptureStep,
+ verifyStep,
+ uploadSymbolsStep,
+ futureFeaturesStep,
+ ]
}
export const FlutterInstallation = createInstallation(getFlutterSteps)
diff --git a/docs/onboarding/product-analytics/flutter.tsx b/docs/onboarding/product-analytics/flutter.tsx
index 559a24a57b57..95bc5ba6300a 100644
--- a/docs/onboarding/product-analytics/flutter.tsx
+++ b/docs/onboarding/product-analytics/flutter.tsx
@@ -4,8 +4,14 @@ import { StepDefinition } from '../steps'
import { DEFAULT_SNIPPET_METHODS, snippetFunctions } from './_snippets/js-snippet-builder'
import { SDK_DEFAULTS_DATE } from './_snippets/sdkDefaults'
-export const getFlutterInstallSteps = (ctx: OnboardingComponentsContext): StepDefinition[] => {
+const DEFAULT_FLUTTER_SDK_VERSION = '5.24.0'
+
+export const getFlutterInstallSteps = (
+ ctx: OnboardingComponentsContext,
+ options?: { minVersion?: string }
+): StepDefinition[] => {
const { CodeBlock, Markdown, Tab, dedent } = ctx
+ const flutterSdkVersion = options?.minVersion ?? DEFAULT_FLUTTER_SDK_VERSION
return [
{
@@ -20,7 +26,7 @@ export const getFlutterInstallSteps = (ctx: OnboardingComponentsContext): StepDe
language: 'yaml',
file: 'pubspec.yaml',
code: dedent`
- posthog_flutter: ^5.24.0
+ posthog_flutter: ^${flutterSdkVersion}
`,
},
]}
@@ -181,9 +187,9 @@ export const getFlutterEventStep = (ctx: OnboardingComponentsContext): StepDefin
}
}
-export const getFlutterSteps = (ctx: OnboardingComponentsContext): StepDefinition[] => [
- ...getFlutterInstallSteps(ctx),
- getFlutterEventStep(ctx),
-]
+export const getFlutterSteps = (
+ ctx: OnboardingComponentsContext,
+ options?: { minVersion?: string }
+): StepDefinition[] => [...getFlutterInstallSteps(ctx, options), getFlutterEventStep(ctx)]
export const FlutterInstallation = createInstallation(getFlutterSteps)