: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
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.tsxindex 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/onboardiimport { 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.tsxindex 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_VERSIONreturn [{@@ -20,7 +26,7 @@ export const getFlutterInstallSteps = (ctx: OnboardingComponentsContext): StepDelanguage: '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)