spring.tsx 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379
  1. import {Fragment} from 'react';
  2. import ExternalLink from 'sentry/components/links/externalLink';
  3. import Link from 'sentry/components/links/link';
  4. import {StepType} from 'sentry/components/onboarding/gettingStartedDoc/step';
  5. import type {
  6. BasePlatformOptions,
  7. Docs,
  8. DocsParams,
  9. OnboardingConfig,
  10. } from 'sentry/components/onboarding/gettingStartedDoc/types';
  11. import replayOnboardingJsLoader from 'sentry/gettingStartedDocs/javascript/jsLoader/jsLoader';
  12. import {t, tct} from 'sentry/locale';
  13. import {getPackageVersion} from 'sentry/utils/gettingStartedDocs/getPackageVersion';
  14. export enum SpringVersion {
  15. V5 = 'v5',
  16. V6 = 'v6',
  17. }
  18. export enum PackageManager {
  19. GRADLE = 'gradle',
  20. MAVEN = 'maven',
  21. }
  22. const platformOptions = {
  23. springVersion: {
  24. label: t('Spring Version'),
  25. items: [
  26. {
  27. label: t('Spring 6'),
  28. value: SpringVersion.V6,
  29. },
  30. {
  31. label: t('Spring 5'),
  32. value: SpringVersion.V5,
  33. },
  34. ],
  35. },
  36. packageManager: {
  37. label: t('Package Manager'),
  38. items: [
  39. {
  40. label: t('Gradle'),
  41. value: PackageManager.GRADLE,
  42. },
  43. {
  44. label: t('Maven'),
  45. value: PackageManager.MAVEN,
  46. },
  47. ],
  48. },
  49. } satisfies BasePlatformOptions;
  50. type PlatformOptions = typeof platformOptions;
  51. type Params = DocsParams<PlatformOptions>;
  52. const getGradleInstallSnippet = (params: Params) => `
  53. buildscript {
  54. repositories {
  55. mavenCentral()
  56. }
  57. }
  58. plugins {
  59. id "io.sentry.jvm.gradle" version "${getPackageVersion(
  60. params,
  61. 'sentry.java.android.gradle-plugin',
  62. '3.12.0'
  63. )}"
  64. }
  65. sentry {
  66. // Generates a JVM (Java, Kotlin, etc.) source bundle and uploads your source code to Sentry.
  67. // This enables source context, allowing you to see your source
  68. // code as part of your stack traces in Sentry.
  69. includeSourceContext = true
  70. org = "${params.organization.slug}"
  71. projectName = "${params.projectSlug}"
  72. authToken = System.getenv("SENTRY_AUTH_TOKEN")
  73. }`;
  74. const getMavenInstallSnippet = (params: Params) => `
  75. <build>
  76. <plugins>
  77. <plugin>
  78. <groupId>io.sentry</groupId>
  79. <artifactId>sentry-maven-plugin</artifactId>
  80. <version>${
  81. params.sourcePackageRegistries?.isLoading
  82. ? t('\u2026loading')
  83. : params.sourcePackageRegistries?.data?.['sentry.java.maven-plugin']?.version ??
  84. '0.0.4'
  85. }</version>
  86. <extensions>true</extensions>
  87. <configuration>
  88. <!-- for showing output of sentry-cli -->
  89. <debugSentryCli>true</debugSentryCli>
  90. <org>${params.organization.slug}</org>
  91. <project>${params.projectSlug}</project>
  92. <!-- in case you're self hosting, provide the URL here -->
  93. <!--<url>http://localhost:8000/</url>-->
  94. <!-- provide your auth token via SENTRY_AUTH_TOKEN environment variable -->
  95. <authToken>\${env.SENTRY_AUTH_TOKEN}</authToken>
  96. </configuration>
  97. <executions>
  98. <execution>
  99. <goals>
  100. <!--
  101. Generates a JVM (Java, Kotlin, etc.) source bundle and uploads your source code to Sentry.
  102. This enables source context, allowing you to see your source
  103. code as part of your stack traces in Sentry.
  104. -->
  105. <goal>uploadSourceBundle</goal>
  106. </goals>
  107. </execution>
  108. </executions>
  109. </plugin>
  110. </plugins>
  111. ...
  112. </build>`;
  113. const getJavaConfigSnippet = (params: Params) => `
  114. import io.sentry.spring${
  115. params.platformOptions.springVersion === SpringVersion.V6 ? '.jakarta' : ''
  116. }.EnableSentry;
  117. @EnableSentry(dsn = "${params.dsn}")
  118. @Configuration
  119. class SentryConfiguration {
  120. }`;
  121. const getKotlinConfigSnippet = (params: Params) => `
  122. import io.sentry.spring${
  123. params.platformOptions.springVersion === SpringVersion.V6 ? '.jakarta' : ''
  124. }.EnableSentry
  125. import org.springframework.core.Ordered
  126. @EnableSentry(
  127. dsn = "${params.dsn}",
  128. exceptionResolverOrder = Ordered.LOWEST_PRECEDENCE
  129. )`;
  130. const getJavaVerifySnippet = () => `
  131. import java.lang.Exception;
  132. import io.sentry.Sentry;
  133. try {
  134. throw new Exception("This is a test.");
  135. } catch (Exception e) {
  136. Sentry.captureException(e);
  137. }`;
  138. const getKotlinVerifySnippet = () => `
  139. import java.lang.Exception
  140. import io.sentry.Sentry
  141. try {
  142. throw Exception("This is a test.")
  143. } catch (e: Exception) {
  144. Sentry.captureException(e)
  145. }`;
  146. const onboarding: OnboardingConfig<PlatformOptions> = {
  147. introduction: () =>
  148. tct(
  149. "Sentry's integration with Spring supports Spring Framework 5.1.2 and above. If you're on an older version, use [legacyIntegrationLink:our legacy integration].",
  150. {
  151. legacyIntegrationLink: (
  152. <ExternalLink href="https://docs.sentry.io/platforms/java/guides/spring/legacy/" />
  153. ),
  154. }
  155. ),
  156. install: (params: Params) => [
  157. {
  158. type: StepType.INSTALL,
  159. description: t(
  160. "Install Sentry's integration with Spring using %s:",
  161. params.platformOptions.packageManager === PackageManager.GRADLE
  162. ? 'Gradle'
  163. : 'Maven'
  164. ),
  165. configurations: [
  166. {
  167. description: (
  168. <p>
  169. {tct(
  170. 'To see source context in Sentry, you have to generate an auth token by visiting the [link:Organization Auth Tokens] settings. You can then set the token as an environment variable that is used by the build plugins.',
  171. {
  172. link: <Link to="/settings/auth-tokens/" />,
  173. }
  174. )}
  175. </p>
  176. ),
  177. language: 'bash',
  178. code: 'SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___',
  179. },
  180. ...(params.platformOptions.packageManager === PackageManager.GRADLE
  181. ? [
  182. {
  183. description: (
  184. <p>
  185. {tct(
  186. 'The [link:Sentry Gradle Plugin] automatically installs the Sentry SDK as well as available integrations for your dependencies. Add the following to your [code:build.gradle] file:',
  187. {
  188. code: <code />,
  189. link: (
  190. <ExternalLink href="https://github.com/getsentry/sentry-android-gradle-plugin" />
  191. ),
  192. }
  193. )}
  194. </p>
  195. ),
  196. language: 'groovy',
  197. code: getGradleInstallSnippet(params),
  198. },
  199. ]
  200. : []),
  201. ...(params.platformOptions.packageManager === PackageManager.MAVEN
  202. ? [
  203. {
  204. language: 'xml',
  205. description: (
  206. <p>
  207. {tct(
  208. 'The [link:Sentry Maven Plugin] automatically installs the Sentry SDK as well as available integrations for your dependencies. Add the following to your [code:pom.xml] file:',
  209. {
  210. code: <code />,
  211. link: (
  212. <ExternalLink href="https://github.com/getsentry/sentry-maven-plugin" />
  213. ),
  214. }
  215. )}
  216. </p>
  217. ),
  218. code: getMavenInstallSnippet(params),
  219. },
  220. ]
  221. : []),
  222. ],
  223. additionalInfo: (
  224. <p>
  225. {tct(
  226. 'If you prefer to manually upload your source code to Sentry, please refer to [link:Manually Uploading Source Context].',
  227. {
  228. link: (
  229. <ExternalLink href="https://docs.sentry.io/platforms/java/source-context/#manually-uploading-source-context" />
  230. ),
  231. }
  232. )}
  233. </p>
  234. ),
  235. },
  236. ],
  237. configure: (params: Params) => [
  238. {
  239. type: StepType.CONFIGURE,
  240. description: (
  241. <Fragment>
  242. {t("Configure Sentry as soon as possible in your application's lifecycle:")}
  243. <p>
  244. {tct(
  245. 'The [libraryName] library provides an [codeEnableSentry:@EnableSentry] annotation that registers all required Spring beans. [codeEnableSentry:@EnableSentry] can be placed on any class annotated with [configurationLink:@Configuration] including the main entry class in Spring Boot applications annotated with [springBootApplicationLink:@SpringBootApplication].',
  246. {
  247. libraryName: (
  248. <code>
  249. {params.platformOptions.springVersion === SpringVersion.V5
  250. ? 'sentry-spring'
  251. : 'sentry-spring-jakarta'}
  252. </code>
  253. ),
  254. codeEnableSentry: <code />,
  255. configurationLink: (
  256. <ExternalLink href="https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/Configuration.html" />
  257. ),
  258. springBootApplicationLink: (
  259. <ExternalLink href="https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/autoconfigure/SpringBootApplication.html" />
  260. ),
  261. }
  262. )}
  263. </p>
  264. </Fragment>
  265. ),
  266. configurations: [
  267. {
  268. description: <h5>{t('Java')}</h5>,
  269. configurations: [
  270. {
  271. language: 'java',
  272. code: [
  273. {
  274. language: 'java',
  275. label: 'Java',
  276. value: 'java',
  277. code: getJavaConfigSnippet(params),
  278. },
  279. {
  280. language: 'java',
  281. label: 'Kotlin',
  282. value: 'kotlin',
  283. code: getKotlinConfigSnippet(params),
  284. },
  285. ],
  286. },
  287. ],
  288. },
  289. ],
  290. },
  291. ],
  292. verify: () => [
  293. {
  294. type: StepType.VERIFY,
  295. description: t(
  296. 'Last, create an intentional error, so you can test that everything is working:'
  297. ),
  298. configurations: [
  299. {
  300. code: [
  301. {
  302. language: 'java',
  303. label: 'Java',
  304. value: 'java',
  305. code: getJavaVerifySnippet(),
  306. },
  307. {
  308. language: 'java',
  309. label: 'Kotlin',
  310. value: 'kotlin',
  311. code: getKotlinVerifySnippet(),
  312. },
  313. ],
  314. },
  315. ],
  316. additionalInfo: (
  317. <Fragment>
  318. <p>
  319. {t(
  320. "If you're new to Sentry, use the email alert to access your account and complete a product tour."
  321. )}
  322. </p>
  323. <p>
  324. {t(
  325. "If you're an existing user and have disabled alerts, you won't receive this email."
  326. )}
  327. </p>
  328. </Fragment>
  329. ),
  330. },
  331. ],
  332. nextSteps: () => [
  333. {
  334. id: 'examples',
  335. name: t('Examples'),
  336. description: t('Check out our sample applications.'),
  337. link: 'https://github.com/getsentry/sentry-java/tree/main/sentry-samples',
  338. },
  339. {
  340. id: 'performance-monitoring',
  341. name: t('Performance Monitoring'),
  342. description: t(
  343. 'Stay ahead of latency issues and trace every slow transaction to a poor-performing API call or database query.'
  344. ),
  345. link: 'https://docs.sentry.io/platforms/java/guides/spring/performance/',
  346. },
  347. ],
  348. };
  349. const docs: Docs<PlatformOptions> = {
  350. onboarding,
  351. platformOptions,
  352. replayOnboardingJsLoader,
  353. };
  354. export default docs;