From 85dee4ea4eb371125d87313adcb744cdb682cc0e Mon Sep 17 00:00:00 2001 From: Alexander Dinauer Date: Wed, 27 Sep 2023 07:26:45 +0200 Subject: [PATCH 1/5] docs for java crons --- .../product/crons/getting-started/index.mdx | 2 + .../crons/requirements/java.mdx | 2 + src/platform-includes/crons/setup/java.mdx | 136 ++++++++++++++++++ .../crons/setup/java.spring-boot.mdx | 65 +++++++++ .../crons/troubleshooting/java.mdx | 3 + src/platforms/common/crons/index.mdx | 5 +- .../common/crons/troubleshooting.mdx | 1 + .../configuration/integrations/quartz.mdx | 69 +++++++++ 8 files changed, 281 insertions(+), 2 deletions(-) create mode 100644 src/platform-includes/crons/requirements/java.mdx create mode 100644 src/platform-includes/crons/setup/java.mdx create mode 100644 src/platform-includes/crons/setup/java.spring-boot.mdx create mode 100644 src/platform-includes/crons/troubleshooting/java.mdx create mode 100644 src/platforms/java/common/configuration/integrations/quartz.mdx diff --git a/src/docs/product/crons/getting-started/index.mdx b/src/docs/product/crons/getting-started/index.mdx index 68e07593fbf21..25900c138b93f 100644 --- a/src/docs/product/crons/getting-started/index.mdx +++ b/src/docs/product/crons/getting-started/index.mdx @@ -19,6 +19,8 @@ To set up Sentry Crons, use the links below for supported SDKs or the Sentry CLI - [SvelteKit](/platforms/javascript/guides/sveltekit/crons/) - [Remix](/platforms/javascript/guides/remix/crons/) - [Go](/platforms/go/crons/) +- [Java](/platforms/java/crons/) + - [Spring Boot](/platforms/java/guides/spring-boot/crons/) diff --git a/src/platform-includes/crons/requirements/java.mdx b/src/platform-includes/crons/requirements/java.mdx new file mode 100644 index 0000000000000..7fdec8fe5ce09 --- /dev/null +++ b/src/platform-includes/crons/requirements/java.mdx @@ -0,0 +1,2 @@ +- Use our getting started guide to install and configure the Sentry Java SDK (min 6.30.0) for your recurring job. +- [Create and configure](https://sentry.io/crons/create/) your first Monitor. diff --git a/src/platform-includes/crons/setup/java.mdx b/src/platform-includes/crons/setup/java.mdx new file mode 100644 index 0000000000000..ada858807025d --- /dev/null +++ b/src/platform-includes/crons/setup/java.mdx @@ -0,0 +1,136 @@ +If you are using [Quartz](http://www.quartz-scheduler.org/), please see our Quartz integration. If you are using Spring Boot with `@Scheduled` tasks, see [our Spring Boot integration](/platforms/java/guides/spring-boot/crons/). + +## Check-Ins (Recommended) + +Check-in monitoring allows you to track a job's progress by completing two check-ins: one at the start of your job and another at the end of your job. This two-step process allows Sentry to notify you if your job didn't start when expected (missed) or if it exceeded its maximum runtime (failed). + +```java +import io.sentry.CheckIn; +import io.sentry.CheckInStatus; +import io.sentry.Sentry; +import io.sentry.protocol.SentryId; + +// 🟡 Notify Sentry your job is running: +SentryId checkInId = Sentry.captureCheckIn( + new CheckIn( + "", + CheckInStatus.IN_PROGRESS + ) +); + +// Execute your scheduled task here... + +// 🟢 Notify Sentry your job has completed successfully: +Sentry.captureCheckIn( + new CheckIn( + checkInId, + "", + CheckInStatus.OK + ) +); +``` + +If your job execution fails, you can notify Sentry about the failure: + +```java +// 🔴 Notify Sentry your job has failed: +Sentry.captureCheckIn( + new CheckIn( + checkInId, + "", + CheckInStatus.ERROR + ) +); +``` + +## Heartbeat + +Heartbeat monitoring notifies Sentry of a job's status through one check-in. This setup will only notify you if your job didn't start when expected (missed). If you need to track a job to see if it exceeded its maximum runtime (failed), use check-ins instead. + +```java +import io.sentry.CheckIn; +import io.sentry.CheckInStatus; +import io.sentry.Sentry; +import io.sentry.protocol.SentryId; + +// Execute your scheduled task... + +// 🟢 Notify Sentry your job completed successfully: +CheckIn checkIn = new CheckIn( + "", + CheckInStatus.OK +); +checkIn.setDuration(10.0); +Sentry.captureCheckIn(checkIn); +``` + +If your job execution fails, you can: + +```java +import io.sentry.CheckIn; +import io.sentry.CheckInStatus; +import io.sentry.Sentry; +import io.sentry.protocol.SentryId; + +// 🔴 Notify Sentry your job has failed: +CheckIn checkIn = new CheckIn( + "", + CheckInStatus.ERROR +); +checkIn.setDuration(10.0); +Sentry.captureCheckIn(checkIn); +``` + +## Upserting Cron Monitors + +You can create and update your Monitors programmatically with code +rather than [creating and configuring them in Sentry.io](https://sentry.io/crons/create/). + +```java +import io.sentry.MonitorSchedule; +import io.sentry.MonitorScheduleUnit; + +// Create a crontab schedule object (every 10 minutes) +MonitorSchedule monitorSchedule = MonitorSchedule.crontab("*/10 * * * *"); + +// Or create an interval schedule object (every 10 minutes) +MonitorSchedule monitorSchedule = MonitorSchedule.interval(10, MonitorScheduleUnit.MINUTE); +``` + +Supported units are: + +- `MonitorScheduleUnit.MINUTE` +- `MonitorScheduleUnit.HOUR` +- `MonitorScheduleUnit.DAY` +- `MonitorScheduleUnit.WEEK` +- `MonitorScheduleUnit.MONTH` +- `MonitorScheduleUnit.YEAR` + +```java +import io.sentry.MonitorConfig; + +// Create a config object +MonitorConfig monitorConfig = new MonitorConfig(monitorSchedule); +monitorConfig.setTimezone("Europe/Vienna"); // Optional timezone +monitorConfig.setCheckinMargin(5L); // Optional check-in margin in minutes +monitorConfig.setMaxRuntime(15L); // Optional max runtime in minutes + +// 🟡 Notify Sentry your job is running: +CheckIn checkIn = new CheckIn( + "", + CheckInStatus.IN_PROGRESS +); +checkIn.setMonitorConfig(monitorConfig); +SentryId checkInId = Sentry.captureCheckIn(checkIn); + +// Execute your scheduled task here... + +// 🟢 Notify Sentry your job has completed successfully: +Sentry.captureCheckIn( + new CheckIn( + checkInId, + "", + CheckInStatus.OK + ) +); +``` diff --git a/src/platform-includes/crons/setup/java.spring-boot.mdx b/src/platform-includes/crons/setup/java.spring-boot.mdx new file mode 100644 index 0000000000000..437534f029a60 --- /dev/null +++ b/src/platform-includes/crons/setup/java.spring-boot.mdx @@ -0,0 +1,65 @@ +If you are using [Quartz](http://www.quartz-scheduler.org/), please see our Quartz integration. You may also [send check-ins manually](/platforms/java/crons/). + +## Check-Ins (Recommended) + +Check-in monitoring allows you to track a job's progress by completing two check-ins: one at the start of your job and another at the end of your job. This two-step process allows Sentry to notify you if your job didn't start when expected (missed) or if it exceeded its maximum runtime (failed). + +```java {tabTitle:Java (Spring Boot 3)} +import io.sentry.spring.jakarta.checkin.SentryCheckIn; + +@Component +public class CustomJob { + + @Scheduled(fixedRate = 3 * 60 * 1000L) + @SentryCheckIn("") // 👈 + void execute() throws InterruptedException { + // your task code + } +} +``` + +```java {tabTitle:Java (Spring Boot 2)} +import io.sentry.spring.checkin.SentryCheckIn; + +@Component +public class CustomJob { + + @Scheduled(fixedRate = 3 * 60 * 1000L) + @SentryCheckIn("") // 👈 + void execute() throws InterruptedException { + // your task code + } +} +``` + +## Heartbeat + +Heartbeat monitoring notifies Sentry of a job's status through one check-in. This setup will only notify you if your job didn't start when expected (missed). If you need to track a job to see if it exceeded its maximum runtime (failed), use check-ins instead. + +```java {tabTitle:Java (Spring Boot 3)} +import io.sentry.spring.jakarta.checkin.SentryCheckIn; + +@Component +public class CustomJob { + + @Scheduled(fixedRate = 3 * 60 * 1000L) + @SentryCheckIn(monitorSlug = "", heartbeat = true) // 👈 + void execute() throws InterruptedException { + // your task code + } +} +``` + +```java {tabTitle:Java (Spring Boot 2)} +import io.sentry.spring.checkin.SentryCheckIn; + +@Component +public class CustomJob { + + @Scheduled(fixedRate = 3 * 60 * 1000L) + @SentryCheckIn(monitorSlug = "", heartbeat = true) // 👈 + void execute() throws InterruptedException { + // your task code + } +} +``` diff --git a/src/platform-includes/crons/troubleshooting/java.mdx b/src/platform-includes/crons/troubleshooting/java.mdx new file mode 100644 index 0000000000000..5930a7b00af98 --- /dev/null +++ b/src/platform-includes/crons/troubleshooting/java.mdx @@ -0,0 +1,3 @@ +### How Do I Send an Attachment With a Check-in (Such as a Log Output)? + +Attachments aren't supported by our Java SDK yet. For now, you can use the [check-in attachments API](/product/crons/getting-started/http/#check-in-attachment-optional). diff --git a/src/platforms/common/crons/index.mdx b/src/platforms/common/crons/index.mdx index 51701ea694ddc..710a01a1b7219 100644 --- a/src/platforms/common/crons/index.mdx +++ b/src/platforms/common/crons/index.mdx @@ -5,6 +5,7 @@ supported: - python - php - node + - java - javascript.nextjs - javascript.sveltekit - javascript.remix @@ -16,7 +17,7 @@ description: "Learn how to enable Cron Monitoring in your app" Sentry Crons allows you to monitor the uptime and performance of any scheduled, recurring job. Once implemented, it'll allow you to get alerts and metrics to help you solve errors, detect timeouts, and prevent disruptions to your service. - + ## Requirements @@ -36,7 +37,7 @@ To link any exceptions captured during your job's lifecycle, use - + ## Requirements diff --git a/src/platforms/common/crons/troubleshooting.mdx b/src/platforms/common/crons/troubleshooting.mdx index 445cd8b00e446..8d3346b1f9abc 100644 --- a/src/platforms/common/crons/troubleshooting.mdx +++ b/src/platforms/common/crons/troubleshooting.mdx @@ -5,6 +5,7 @@ supported: - python - php - node + - java - javascript.nextjs - javascript.sveltekit - javascript.remix diff --git a/src/platforms/java/common/configuration/integrations/quartz.mdx b/src/platforms/java/common/configuration/integrations/quartz.mdx new file mode 100644 index 0000000000000..5c1168ba853af --- /dev/null +++ b/src/platforms/java/common/configuration/integrations/quartz.mdx @@ -0,0 +1,69 @@ +--- +title: Quartz Integration +sidebar_order: 7 +description: "Learn how to send check-ins for your Quartz jobs." +notSupported: + - java.logback + - java.log4j2 + - java.jul +--- + +Sentry's [Quartz](http://www.quartz-scheduler.org/) integration is provided through `SenryJobListener` which you have to add to your scheduler instance. + +Our Quartz integration can be configured automatically if you're using `spring-boot-starter-quartz` with either the `sentry-spring-boot-starter` or the `sentry-spring-boot-jakarta-starter` integration. However you still have to specify the monitor slug as shown below. + +Check-ins may also be [sent manually](/platforms/java/crons/) or by using our [`@SentryCheckIn` annotation](/platforms/java/guides/spring-boot/crons/), in case you are using our Spring Boot integration and would like to send check-ins for your `@Scheduled` tasks. + +## Install + +To install use: + +```groovy {tabTitle:Gradle Plugin} +plugins { + id "io.sentry.jvm.gradle" version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.13.0') }}" +} +``` + +```groovy {tabTitle:Gradle} +implementation 'io.sentry:sentry-quartz:{{@inject packages.version('sentry.java.quartz', '6.30.0') }}' +``` + +```xml {tabTitle:Maven} + + io.sentry + sentry-quartz + {{@inject packages.version('sentry.java.quartz', '6.30.0') }} + +``` + +```scala {tabTitle: SBT} +libraryDependencies += "io.sentry" % "sentry-quartz" % "{{@inject packages.version('sentry.java.quartz', '6.30.0') }}" +``` + +For other dependency managers, check out the [central Maven repository](https://search.maven.org/artifact/io.sentry/sentry-quartz). + +## Set Up + +You have to provide the monitor slug either +- when building a Quartz `JobDetail` instance +- or when building a Quartz `Trigger` instance + +To do so, you have to add an entry to the jobs data map: + +```java +import io.sentry.quartz.SentryJobListener; + +// you can set the monitor slug on the job detail +JobDetailFactoryBean jobDetailFactory = new JobDetailFactoryBean(); +jobDetailFactory.setJobDataAsMap(Collections.singletonMap(SentryJobListener.SENTRY_SLUG_KEY, "")); + +// you can also set the monitor slug on the trigger +SimpleTriggerFactoryBean trigger = new SimpleTriggerFactoryBean(); +trigger.setJobDataAsMap(Collections.singletonMap(SENTRY_SLUG_KEY, "monitor_slug_simple_trigger")); +``` + + + +Setting the monitor slug on the `Trigger` will override what is set on the `JobDetail`. This also means you can set up a separate monitor per `Trigger`. + + From 0e4ee24e300300d94985763a2fe4520327cd44cd Mon Sep 17 00:00:00 2001 From: "getsantry[bot]" <66042841+getsantry[bot]@users.noreply.github.com> Date: Wed, 27 Sep 2023 05:37:01 +0000 Subject: [PATCH 2/5] style(lint): Auto commit lint changes --- src/platforms/java/common/configuration/integrations/quartz.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/src/platforms/java/common/configuration/integrations/quartz.mdx b/src/platforms/java/common/configuration/integrations/quartz.mdx index 5c1168ba853af..84a2c2497ebd1 100644 --- a/src/platforms/java/common/configuration/integrations/quartz.mdx +++ b/src/platforms/java/common/configuration/integrations/quartz.mdx @@ -45,6 +45,7 @@ For other dependency managers, check out the [central Maven repository](https:// ## Set Up You have to provide the monitor slug either + - when building a Quartz `JobDetail` instance - or when building a Quartz `Trigger` instance From edf5af00bdce696235e54da73199440c98275c53 Mon Sep 17 00:00:00 2001 From: Alexander Dinauer Date: Wed, 27 Sep 2023 15:37:05 +0200 Subject: [PATCH 3/5] enable quartz for logging frameworks as well --- .../java/common/configuration/integrations/index.mdx | 4 ---- .../java/common/configuration/integrations/quartz.mdx | 4 ---- 2 files changed, 8 deletions(-) diff --git a/src/platforms/java/common/configuration/integrations/index.mdx b/src/platforms/java/common/configuration/integrations/index.mdx index 9bddb5783dc2e..4a45bccee779d 100644 --- a/src/platforms/java/common/configuration/integrations/index.mdx +++ b/src/platforms/java/common/configuration/integrations/index.mdx @@ -2,10 +2,6 @@ title: Integrations sidebar_order: 200 description: "Learn more about how integrations extend the functionality of our SDK to cover common libraries and environments automatically." -notSupported: - - java.logback - - java.log4j2 - - java.jul --- diff --git a/src/platforms/java/common/configuration/integrations/quartz.mdx b/src/platforms/java/common/configuration/integrations/quartz.mdx index 84a2c2497ebd1..5df5e4478b6d5 100644 --- a/src/platforms/java/common/configuration/integrations/quartz.mdx +++ b/src/platforms/java/common/configuration/integrations/quartz.mdx @@ -2,10 +2,6 @@ title: Quartz Integration sidebar_order: 7 description: "Learn how to send check-ins for your Quartz jobs." -notSupported: - - java.logback - - java.log4j2 - - java.jul --- Sentry's [Quartz](http://www.quartz-scheduler.org/) integration is provided through `SenryJobListener` which you have to add to your scheduler instance. From c671482eb65bedbcd840f3926d5045c35d72ddc2 Mon Sep 17 00:00:00 2001 From: Alexander Dinauer Date: Thu, 28 Sep 2023 06:46:40 +0200 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Shana Matthews --- .../java/common/configuration/integrations/quartz.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/platforms/java/common/configuration/integrations/quartz.mdx b/src/platforms/java/common/configuration/integrations/quartz.mdx index 5df5e4478b6d5..1d610eb75df2d 100644 --- a/src/platforms/java/common/configuration/integrations/quartz.mdx +++ b/src/platforms/java/common/configuration/integrations/quartz.mdx @@ -1,14 +1,14 @@ --- title: Quartz Integration -sidebar_order: 7 +sidebar_order: 10 description: "Learn how to send check-ins for your Quartz jobs." --- Sentry's [Quartz](http://www.quartz-scheduler.org/) integration is provided through `SenryJobListener` which you have to add to your scheduler instance. -Our Quartz integration can be configured automatically if you're using `spring-boot-starter-quartz` with either the `sentry-spring-boot-starter` or the `sentry-spring-boot-jakarta-starter` integration. However you still have to specify the monitor slug as shown below. +The Quartz integration will be configured automatically if you're using `spring-boot-starter-quartz` with either the `sentry-spring-boot-starter` or the `sentry-spring-boot-jakarta-starter` integration. However, you still have to specify the monitor slug as shown below. -Check-ins may also be [sent manually](/platforms/java/crons/) or by using our [`@SentryCheckIn` annotation](/platforms/java/guides/spring-boot/crons/), in case you are using our Spring Boot integration and would like to send check-ins for your `@Scheduled` tasks. +Check-ins may also be [sent manually](/platforms/java/crons/) or if you're using Sentry's Spring Boot integration you can send send check-ins for your `@Scheduled` tasks by using our [`@SentryCheckIn` annotation](/platforms/java/guides/spring-boot/crons/). ## Install From c7dcec07a4e150f12f0fe7cc4e5b709770b55ba2 Mon Sep 17 00:00:00 2001 From: Alexander Dinauer Date: Thu, 28 Sep 2023 06:51:53 +0200 Subject: [PATCH 5/5] code review changes --- src/platform-includes/crons/setup/java.spring-boot.mdx | 4 ++-- src/platforms/common/crons/troubleshooting.mdx | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/src/platform-includes/crons/setup/java.spring-boot.mdx b/src/platform-includes/crons/setup/java.spring-boot.mdx index 437534f029a60..f0b05f1974c6f 100644 --- a/src/platform-includes/crons/setup/java.spring-boot.mdx +++ b/src/platform-includes/crons/setup/java.spring-boot.mdx @@ -2,7 +2,7 @@ If you are using [Quartz](http://www.quartz-scheduler.org/), please see ")` annotation to the method you want to send check-ins for. ```java {tabTitle:Java (Spring Boot 3)} import io.sentry.spring.jakarta.checkin.SentryCheckIn; @@ -34,7 +34,7 @@ public class CustomJob { ## Heartbeat -Heartbeat monitoring notifies Sentry of a job's status through one check-in. This setup will only notify you if your job didn't start when expected (missed). If you need to track a job to see if it exceeded its maximum runtime (failed), use check-ins instead. +Heartbeat monitoring notifies Sentry of a job's status through one check-in. This setup will only notify you if your job didn't start when expected (missed). If you need to track a job to see if it exceeded its maximum runtime (failed), use check-ins instead. To start sending heartbeats simply add the `@SentryCheckIn(monitorSlug = "", heartbeat = true)` annotation to the method you want to send heartbeats for. ```java {tabTitle:Java (Spring Boot 3)} import io.sentry.spring.jakarta.checkin.SentryCheckIn; diff --git a/src/platforms/common/crons/troubleshooting.mdx b/src/platforms/common/crons/troubleshooting.mdx index 8d3346b1f9abc..a350a0cc314ba 100644 --- a/src/platforms/common/crons/troubleshooting.mdx +++ b/src/platforms/common/crons/troubleshooting.mdx @@ -17,6 +17,7 @@ description: "Learn how to troubleshoot your Cron Monitoring setup." "python", "php", "node", + "java", "javascript.nextjs", "javascript.sveltekit", "javascript.remix"