flutter.tsx 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445
  1. import {Fragment} from 'react';
  2. import {Alert} from 'sentry/components/core/alert';
  3. import ExternalLink from 'sentry/components/links/externalLink';
  4. import List from 'sentry/components/list';
  5. import ListItem from 'sentry/components/list/listItem';
  6. import {StepType} from 'sentry/components/onboarding/gettingStartedDoc/step';
  7. import type {
  8. BasePlatformOptions,
  9. Docs,
  10. DocsParams,
  11. OnboardingConfig,
  12. } from 'sentry/components/onboarding/gettingStartedDoc/types';
  13. import {
  14. getReplayMobileConfigureDescription,
  15. getReplayVerifyStep,
  16. } from 'sentry/components/onboarding/gettingStartedDoc/utils/replayOnboarding';
  17. import {feedbackOnboardingCrashApiDart} from 'sentry/gettingStartedDocs/dart/dart';
  18. import {t, tct} from 'sentry/locale';
  19. import {getPackageVersion} from 'sentry/utils/gettingStartedDocs/getPackageVersion';
  20. import {getWizardInstallSnippet} from 'sentry/utils/gettingStartedDocs/mobileWizard';
  21. export enum InstallationMode {
  22. AUTO = 'auto',
  23. MANUAL = 'manual',
  24. }
  25. const platformOptions = {
  26. installationMode: {
  27. label: t('Installation Mode'),
  28. items: [
  29. {
  30. label: t('Auto'),
  31. value: InstallationMode.AUTO,
  32. },
  33. {
  34. label: t('Manual'),
  35. value: InstallationMode.MANUAL,
  36. },
  37. ],
  38. defaultValue:
  39. navigator.userAgent.indexOf('Win') === -1
  40. ? InstallationMode.AUTO
  41. : InstallationMode.MANUAL,
  42. },
  43. } satisfies BasePlatformOptions;
  44. type PlatformOptions = typeof platformOptions;
  45. type Params = DocsParams<PlatformOptions>;
  46. const isAutoInstall = (params: Params) =>
  47. params.platformOptions?.installationMode === InstallationMode.AUTO;
  48. const getManualInstallSnippet = (params: Params) => {
  49. const version = getPackageVersion(params, 'sentry.dart.flutter', '8.13.2');
  50. return `dependencies:
  51. sentry_flutter: ^${version}`;
  52. };
  53. const getConfigureSnippet = (params: Params) => `
  54. import 'package:sentry_flutter/sentry_flutter.dart';
  55. Future<void> main() async {
  56. await SentryFlutter.init(
  57. (options) {
  58. options.dsn = '${params.dsn.public}';
  59. // Adds request headers and IP for users,
  60. // visit: https://docs.sentry.io/platforms/dart/data-management/data-collected/ for more info
  61. options.sendDefaultPii = true;${
  62. params.isPerformanceSelected
  63. ? `
  64. // Set tracesSampleRate to 1.0 to capture 100% of transactions for tracing.
  65. // We recommend adjusting this value in production.
  66. options.tracesSampleRate = 1.0;`
  67. : ''
  68. }${
  69. params.isProfilingSelected
  70. ? `
  71. // The sampling rate for profiling is relative to tracesSampleRate
  72. // Setting to 1.0 will profile 100% of sampled transactions:
  73. options.profilesSampleRate = 1.0;`
  74. : ''
  75. }
  76. },
  77. appRunner: () => runApp(
  78. SentryWidget(
  79. child: MyApp(),
  80. ),
  81. ),
  82. );
  83. // or define SENTRY_DSN via Dart environment variable (--dart-define)
  84. }`;
  85. const configureAdditionalInfo = tct(
  86. 'You can configure the [code: SENTRY_DSN], [code: SENTRY_RELEASE], [code: SENTRY_DIST], and [code: SENTRY_ENVIRONMENT] via the Dart environment variables passing the [code: --dart-define] flag to the compiler, as noted in the code sample.',
  87. {
  88. code: <code />,
  89. }
  90. );
  91. const getVerifySnippet = () => `
  92. child: ElevatedButton(
  93. onPressed: () {
  94. throw Exception('This is test exception');
  95. },
  96. child: const Text('Verify Sentry Setup'),
  97. )
  98. `;
  99. const getPerformanceSnippet = () => `
  100. import 'package:sentry/sentry.dart';
  101. void execute() async {
  102. final transaction = Sentry.startTransaction('processOrderBatch()', 'task');
  103. try {
  104. await processOrderBatch(transaction);
  105. } catch (exception) {
  106. transaction.throwable = exception;
  107. transaction.status = const SpanStatus.internalError();
  108. } finally {
  109. await transaction.finish();
  110. }
  111. }
  112. Future<void> processOrderBatch(ISentrySpan span) async {
  113. // span operation: task, span description: operation
  114. final innerSpan = span.startChild('task', description: 'operation');
  115. try {
  116. // omitted code
  117. } catch (exception) {
  118. innerSpan.throwable = exception;
  119. innerSpan.status = const SpanStatus.notFound();
  120. } finally {
  121. await innerSpan.finish();
  122. }
  123. }`;
  124. const getInstallReplaySnippet = () => `
  125. await SentryFlutter.init(
  126. (options) {
  127. ...
  128. options.experimental.replay.sessionSampleRate = 1.0;
  129. options.experimental.replay.onErrorSampleRate = 1.0;
  130. },
  131. appRunner: () => runApp(
  132. SentryWidget(
  133. child: MyApp(),
  134. ),
  135. ),
  136. );
  137. `;
  138. const getConfigureReplaySnippet = () => `
  139. options.experimental.replay.maskAllText = true;
  140. options.experimental.replay.maskAllImages = true;`;
  141. const onboarding: OnboardingConfig<PlatformOptions> = {
  142. install: params =>
  143. isAutoInstall(params)
  144. ? [
  145. {
  146. type: StepType.INSTALL,
  147. description: tct(
  148. 'Add Sentry automatically to your app with the [wizardLink:Sentry wizard] (call this inside your project directory).',
  149. {
  150. wizardLink: (
  151. <ExternalLink href="https://docs.sentry.io/platforms/flutter/#install" />
  152. ),
  153. }
  154. ),
  155. configurations: [
  156. {
  157. code: getWizardInstallSnippet({
  158. platform: 'flutter',
  159. params,
  160. }),
  161. },
  162. {
  163. description: (
  164. <Fragment>
  165. <p>
  166. {t(
  167. 'The Sentry wizard will automatically patch your project with the following:'
  168. )}
  169. </p>
  170. <List symbol="bullet">
  171. <ListItem>
  172. {tct(
  173. 'Configure the SDK with your DSN and performance monitoring options in your [main:main.dart] file.',
  174. {
  175. main: <code />,
  176. }
  177. )}
  178. </ListItem>
  179. <ListItem>
  180. {tct(
  181. 'Update your [pubspec:pubspec.yaml] with the Sentry package',
  182. {
  183. pubspec: <code />,
  184. }
  185. )}
  186. </ListItem>
  187. <ListItem>
  188. {t('Add an example error to verify your setup')}
  189. </ListItem>
  190. </List>
  191. </Fragment>
  192. ),
  193. },
  194. ],
  195. },
  196. ]
  197. : [
  198. {
  199. type: StepType.INSTALL,
  200. description: tct(
  201. 'Sentry captures data by using an SDK within your application. Add the following to your [pubspec:pubspec.yaml]',
  202. {
  203. pubspec: <code />,
  204. }
  205. ),
  206. configurations: [
  207. {
  208. code: [
  209. {
  210. label: 'YAML',
  211. value: 'yaml',
  212. language: 'yaml',
  213. filename: 'pubspec.yaml',
  214. partialLoading: params.sourcePackageRegistries?.isLoading,
  215. code: getManualInstallSnippet(params),
  216. },
  217. ],
  218. },
  219. ],
  220. },
  221. ],
  222. configure: params =>
  223. isAutoInstall(params)
  224. ? []
  225. : [
  226. {
  227. type: StepType.CONFIGURE,
  228. description: tct(
  229. 'Import [sentryFlutter: sentry_flutter] and initialize it in your [main:main.dart]',
  230. {
  231. sentryFlutter: <code />,
  232. main: <code />,
  233. }
  234. ),
  235. configurations: [
  236. ...(params.isProfilingSelected
  237. ? [
  238. {
  239. description: t(
  240. 'Flutter Profiling alpha is available for iOS and macOS since SDK version 7.12.0.'
  241. ),
  242. },
  243. ]
  244. : []),
  245. {
  246. code: [
  247. {
  248. label: 'Dart',
  249. value: 'dart',
  250. language: 'dart',
  251. filename: 'main.dart',
  252. code: getConfigureSnippet(params),
  253. },
  254. ],
  255. additionalInfo: params.isPerformanceSelected ? (
  256. <Fragment>
  257. <p>{configureAdditionalInfo}</p>
  258. <Alert type="info">
  259. {t(
  260. 'To monitor performance, you need to add extra instrumentation as described in the Tracing section below.'
  261. )}
  262. </Alert>
  263. </Fragment>
  264. ) : (
  265. configureAdditionalInfo
  266. ),
  267. },
  268. ],
  269. },
  270. ],
  271. verify: params =>
  272. isAutoInstall(params)
  273. ? []
  274. : [
  275. {
  276. type: StepType.VERIFY,
  277. description: t(
  278. 'Create an intentional error, so you can test that everything is working. In the example below, pressing the button will throw an exception:'
  279. ),
  280. configurations: [
  281. {
  282. code: [
  283. {
  284. label: 'Dart',
  285. value: 'dart',
  286. language: 'dart',
  287. code: getVerifySnippet(),
  288. },
  289. ],
  290. },
  291. ],
  292. },
  293. ...(params.isPerformanceSelected
  294. ? [
  295. {
  296. title: t('Tracing'),
  297. description: t(
  298. "You'll be able to monitor the performance of your app using the SDK. For example:"
  299. ),
  300. configurations: [
  301. {
  302. code: [
  303. {
  304. label: 'Dart',
  305. value: 'dart',
  306. language: 'dart',
  307. code: getPerformanceSnippet(),
  308. },
  309. ],
  310. additionalInfo: tct(
  311. 'To learn more about the API and automatic instrumentations, check out the [perfDocs: tracing documentation].',
  312. {
  313. perfDocs: (
  314. <ExternalLink href="https://docs.sentry.io/platforms/flutter/tracing/instrumentation/" />
  315. ),
  316. }
  317. ),
  318. },
  319. ],
  320. },
  321. ]
  322. : []),
  323. ],
  324. nextSteps: () => [
  325. {
  326. name: t('Upload Debug Symbols'),
  327. description: t(
  328. 'We offer a range of methods to provide Sentry with debug symbols so that you can see symbolicated stack traces and find the cause of your errors faster.'
  329. ),
  330. link: 'https://docs.sentry.io/platforms/flutter/upload-debug/',
  331. },
  332. {
  333. name: t('Distributed Tracing'),
  334. description: t(
  335. 'Connect all your services by configuring your endpoints in the Sentry init.'
  336. ),
  337. link: 'https://docs.sentry.io/platforms/flutter/tracing/trace-propagation/limiting-trace-propagation/',
  338. },
  339. {
  340. name: t('Connect your Git Repo'),
  341. description: t(
  342. 'Adding our Git integrations will allow us determine suspect commits, comment on PRs, and create links directly to your source code from Sentry issues.'
  343. ),
  344. link: 'https://docs.sentry.io/organization/integrations/source-code-mgmt/',
  345. },
  346. ],
  347. };
  348. const replayOnboarding: OnboardingConfig<PlatformOptions> = {
  349. install: params => [
  350. {
  351. type: StepType.INSTALL,
  352. description: tct(
  353. 'Make sure your Sentry Flutter SDK version is at least 8.9.0, which is required for Session Replay. You can update your [code:pubspec.yaml] to the matching version:',
  354. {code: <code />}
  355. ),
  356. configurations: [
  357. {
  358. code: [
  359. {
  360. label: 'YAML',
  361. value: 'yaml',
  362. language: 'yaml',
  363. code: getManualInstallSnippet(params),
  364. },
  365. ],
  366. },
  367. {
  368. description: t(
  369. 'To set up the integration, add the following to your Sentry initialization:'
  370. ),
  371. },
  372. {
  373. code: [
  374. {
  375. label: 'Dart',
  376. value: 'dart',
  377. language: 'dart',
  378. code: getInstallReplaySnippet(),
  379. },
  380. ],
  381. },
  382. ],
  383. },
  384. ],
  385. configure: () => [
  386. {
  387. type: StepType.CONFIGURE,
  388. description: getReplayMobileConfigureDescription({
  389. link: 'https://docs.sentry.io/platforms/flutter/session-replay/#privacy',
  390. }),
  391. configurations: [
  392. {
  393. description: t(
  394. 'The following code is the default configuration, which masks and blocks everything.'
  395. ),
  396. code: [
  397. {
  398. label: 'Dart',
  399. value: 'dart',
  400. language: 'dart',
  401. code: getConfigureReplaySnippet(),
  402. },
  403. ],
  404. },
  405. ],
  406. },
  407. ],
  408. verify: getReplayVerifyStep({
  409. replayOnErrorSampleRateName:
  410. 'options\u200b.experimental\u200b.sessionReplay\u200b.onErrorSampleRate',
  411. replaySessionSampleRateName:
  412. 'options\u200b.experimental\u200b.sessionReplay\u200b.sessionSampleRate',
  413. }),
  414. nextSteps: () => [],
  415. };
  416. const docs: Docs<PlatformOptions> = {
  417. onboarding,
  418. feedbackOnboardingCrashApi: feedbackOnboardingCrashApiDart,
  419. crashReportOnboarding: feedbackOnboardingCrashApiDart,
  420. platformOptions,
  421. replayOnboarding,
  422. };
  423. export default docs;