diff --git a/docs/cli/configuration.mdx b/docs/cli/configuration.mdx index 20b49ec389ffc..d2dac2fa0aa4b 100644 --- a/docs/cli/configuration.mdx +++ b/docs/cli/configuration.mdx @@ -27,7 +27,7 @@ You can manually create an [Organization Token](https://sentry.io/orgredirect/or You can also sign in to your Sentry account (if you're not already) and create an Auth Token directly from this page. -Some CLI functionality, such as [Crons Monitoring](/product/crons/getting-started/cli/), is dependent on [Data Source Name (DSN)](/concepts/key-terms/dsn-explainer/) authentication. +Some CLI functionality, such as [Crons Monitoring](/product/monitors/crons/getting-started/cli/), is dependent on [Data Source Name (DSN)](/concepts/key-terms/dsn-explainer/) authentication. You can create an Auth Token from this page in one of the following three ways: diff --git a/docs/cli/crons.mdx b/docs/cli/crons.mdx index eba6b12d8c246..761f58b0d8c4a 100644 --- a/docs/cli/crons.mdx +++ b/docs/cli/crons.mdx @@ -84,7 +84,7 @@ sentry-cli monitors run -s "0 * * * *" --check-in-margin 10 --max-runtime 5 --ti ### Specifying Monitor Environments (Optional) -If your cron monitor runs in multiple environments you can use the `-e` flag to specify which [Monitor Environment](/product/crons/job-monitoring/#multiple-environments) to send check-ins to. +If your cron monitor runs in multiple environments you can use the `-e` flag to specify which [Monitor Environment](/product/monitors/crons/job-monitoring/#multiple-environments) to send check-ins to. ```bash {tabTitle: Node.JS} sentry-cli monitors run -e dev my-monitor-slug -- node path/to/file.js diff --git a/docs/platforms/dotnet/common/crons/hangfire/index.mdx b/docs/platforms/dotnet/common/crons/hangfire/index.mdx index 32b874fe98a31..b29ca00e8e3fe 100644 --- a/docs/platforms/dotnet/common/crons/hangfire/index.mdx +++ b/docs/platforms/dotnet/common/crons/hangfire/index.mdx @@ -4,7 +4,7 @@ description: "Learn more about how to monitor your Hangfire jobs." sidebar_order: 5001 --- -The .NET SDK provides an integration with [Hangfire](https://www.hangfire.io/) to monitor your jobs by automatically [creating check-ins for them](/product/crons/job-monitoring/). The SDK relies on job filters that are set up when you call `UseSentry`. For example: +The .NET SDK provides an integration with [Hangfire](https://www.hangfire.io/) to monitor your jobs by automatically [creating check-ins for them](/product/monitors/crons/job-monitoring/). The SDK relies on job filters that are set up when you call `UseSentry`. For example: ```csharp using Hangfire; diff --git a/docs/platforms/java/common/crons/troubleshooting.mdx b/docs/platforms/java/common/crons/troubleshooting.mdx index ba79cba0ba2d8..f5e6ef10c7667 100644 --- a/docs/platforms/java/common/crons/troubleshooting.mdx +++ b/docs/platforms/java/common/crons/troubleshooting.mdx @@ -6,7 +6,7 @@ sidebar_order: 9000 -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). +Attachments aren't supported by our Java SDK yet. For now, you can use the [check-in attachments API](/product/monitors/crons/getting-started/http/#check-in-attachment-optional). diff --git a/docs/platforms/javascript/common/configuration/integrations/denocron.mdx b/docs/platforms/javascript/common/configuration/integrations/denocron.mdx index 74d7875ac43c3..6b6050db80afe 100644 --- a/docs/platforms/javascript/common/configuration/integrations/denocron.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/denocron.mdx @@ -13,7 +13,7 @@ This integration only works in the Deno runtime. _Import name: `Sentry.denoCronIntegration`_ -[Sentry Crons](/product/crons/) allows you to monitor the uptime and performance of any scheduled, recurring job in your application. +[Sentry Crons](/product/monitors/crons/) allows you to monitor the uptime and performance of any scheduled, recurring job in your application. The DenoCron integration sets up automatic monitoring for your cron jobs created by [`Deno.cron`](https://docs.deno.com/deploy/kv/manual/cron). It captures check-ins and sends them to Sentry. diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup.mdx index 092f6597dacb2..440e0071cc507 100644 --- a/docs/platforms/javascript/guides/nextjs/manual-setup.mdx +++ b/docs/platforms/javascript/guides/nextjs/manual-setup.mdx @@ -492,7 +492,7 @@ module.exports = withSentryConfig(nextConfig, { ## Step 6: Instrument Vercel Cron Jobs (Optional) -You can automatically create [Cron Monitors](/product/crons/) in Sentry if you have configured [Vercel cron jobs](https://vercel.com/docs/cron-jobs). +You can automatically create [Cron Monitors](/product/monitors/crons/) in Sentry if you have configured [Vercel cron jobs](https://vercel.com/docs/cron-jobs). Update `withSentryConfig` in your `next.config.(js|mjs)` file with the following option: diff --git a/docs/product/index.mdx b/docs/product/index.mdx index 3dced685a84ac..730cc143ab6ac 100644 --- a/docs/product/index.mdx +++ b/docs/product/index.mdx @@ -50,11 +50,11 @@ Our [**AI Agents Monitoring**](/product/insights/ai/agents/) feature gives you i ### Uptime Monitoring -Sentry's [**Uptime Monitoring**](/product/uptime-monitoring/) helps you maintain uptime for your web services by monitoring relevant URLs. It continuously tracks configured URLs, delivering alerts and insights to quickly identify downtime and troubleshoot issues. By leveraging [distributed tracing](/product/uptime-monitoring/uptime-tracing/), Sentry enables you to pinpoint any errors that occur during an uptime check, simplifying triage and accelerating root cause analysis. Uptime monitoring includes [uptime request spans](/product/uptime-monitoring/#uptime-request-spans) by default. These act as the root of any uptime issue's trace, giving you better context for faster debugging. +Sentry's [**Uptime Monitoring**](/product/monitors/uptime-monitoring/) helps you maintain uptime for your web services by monitoring relevant URLs. It continuously tracks configured URLs, delivering alerts and insights to quickly identify downtime and troubleshoot issues. By leveraging [distributed tracing](/product/monitors/uptime-monitoring/uptime-tracing/), Sentry enables you to pinpoint any errors that occur during an uptime check, simplifying triage and accelerating root cause analysis. Uptime monitoring includes [uptime request spans](/product/monitors/uptime-monitoring/#uptime-request-spans) by default. These act as the root of any uptime issue's trace, giving you better context for faster debugging. ### Recurring Job Monitoring -[**Cron Monitors**](/product/crons/) allows you to monitor the uptime and performance of any scheduled, recurring job in Sentry. Once implemented, it'll allow you to get alerts and metrics to help you solve errors, detect timeouts, and prevent disruptions to your service. +[**Cron Monitors**](/product/monitors/crons/) allows you to monitor the uptime and performance of any scheduled, recurring job in Sentry. Once implemented, it'll allow you to get alerts and metrics to help you solve errors, detect timeouts, and prevent disruptions to your service. ### Visibility Into Your Data Across Environments diff --git a/docs/product/issues/issue-details/uptime-issues/index.mdx b/docs/product/issues/issue-details/uptime-issues/index.mdx index dd92ff837a4fd..d658708309be8 100644 --- a/docs/product/issues/issue-details/uptime-issues/index.mdx +++ b/docs/product/issues/issue-details/uptime-issues/index.mdx @@ -9,7 +9,7 @@ og_image: /og-images/product-issues-issue-details-uptime-issues.png An uptime issue is a grouping of detected downtime events for a specific URL. A downtime event is generated by active uptime alerts when HTTP requests fail to meet our -[uptime check criteria](/product/uptime-monitoring/#uptime-check-criteria). +[uptime check criteria](/product/monitors/uptime-monitoring/#uptime-check-criteria). ![Uptime issue details](./img/uptime-issue-details.png) @@ -20,4 +20,4 @@ Uptime checks made against web services configured with one of Sentry's supporte ## Issue Lifecycle -Uptime issues are grouped by the monitored URL and created upon the first detected downtime. Sentry automatically resolves an ongoing uptime issue when the monitored URL returns to a healthy status and meets our [uptime check criteria](/product/uptime-monitoring/#uptime-check-criteria). If the URL experiences subsequent downtime, the issue's status will change to regressed. +Uptime issues are grouped by the monitored URL and created upon the first detected downtime. Sentry automatically resolves an ongoing uptime issue when the monitored URL returns to a healthy status and meets our [uptime check criteria](/product/monitors/uptime-monitoring/#uptime-check-criteria). If the URL experiences subsequent downtime, the issue's status will change to regressed. diff --git a/docs/product/issues/monitors-and-alerts/index.mdx b/docs/product/issues/monitors-and-alerts/index.mdx new file mode 100644 index 0000000000000..2bf917954b680 --- /dev/null +++ b/docs/product/issues/monitors-and-alerts/index.mdx @@ -0,0 +1,55 @@ +--- +title: Monitors and Alerts +sidebar_order: 10 +description: "Learn how Monitors and Alerts help you customize your issue management process." +--- + +[Monitors](/product/monitors/) and [Alerts](/product/alerts/) work together to help you create issues and take action when problems occur in your project. While they serve different purposes, they're designed to work as a team. + +## How They Work Together + +**Monitors** are the "detectors" - they watch for specific conditions and create issues when those conditions are met. **Alerts** are the "responders" - they take action when issues are created or change state and meet the filter criteria of the Alert. + +Here's the typical flow: + +1. **Monitor detects a problem** → Creates an issue +2. **Issue triggers Alert** → Takes external action (sends notifications, creates tickets, calls webhooks) + +[!monitors-and-alerts-flow-chart](./img/monitors-and-alerts-flow-chart.png) + +## Monitors: Creating Issues + +Monitors customize when errors and performance problems become issues. They can track: + +- **Custom metrics** and span attributes +- **Scheduled jobs** (cron monitors) +- **HTTP endpoints** (uptime monitors) +- **Default behaviors** (errors, replays, traces, profiles) + +[See all Monitor types](/product/monitors/#types-of-monitors) + +When a monitor's conditions are met, it automatically creates an issue with the specified priority, assignee, and other attributes. + +## Alerts: Taking Action + +Alerts respond to issue state changes by performing external actions like: + +- Sending notifications to Slack, email, or other channels +- Creating tickets in JIRA or other project management tools +- Calling webhooks or integrations + +## The Connection + +Alerts must be connected to Monitors to run. This connection ensures that: + +- Issues created by Monitors can trigger appropriate responses +- You have full control over both detection and response +- Actions are taken only for the issues you care about + +## Getting Started + +1. **Create a Monitor** to define when issues should be created +2. **Create an Alert** to define what actions to take +3. **Connect them** so the Alert responds to issues from that Monitor + +Using Monitors and Alerts gives you a complete workflow from problem detection to team notification, ticket creation, and more. \ No newline at end of file diff --git a/docs/product/new-monitors-and-alerts/alerts/best-practices.mdx b/docs/product/new-monitors-and-alerts/alerts/best-practices.mdx new file mode 100644 index 0000000000000..0332466f425d6 --- /dev/null +++ b/docs/product/new-monitors-and-alerts/alerts/best-practices.mdx @@ -0,0 +1,93 @@ +--- +title: Alerts Best Practices +keywords: ["best practice", "alerting", "manage noise"] +sidebar_order: 30 +description: "Learn best practices for creating alerts." +--- + + + New Monitors and Alerts is currently in beta. Beta features are still a work in progress and may have bugs. We recognize the irony. Help improve this feature by providing feedback on our [GitHub discussion](https://github.com/getsentry/sentry/discussions/101960). + + +Alerts should notify you when there's an important problem with your application. But they shouldn't be too noisy, because that can lead to alert fatigue. The following best practices will help you create relevant alerts that notify the right people — that is, the people equipped to fix the problem. + +There are two types of alerts: [issue alerts](/product/alerts/alert-types/#issue-alerts) and [metric alerts](/product/alerts/alert-types/#metric-alerts). Most of our alerting best practices are specific to issue alerts, however, the [alert conditions best practices](#alert-conditions-best-practices) apply to both issue and metric alerts. + +## Issue Alerts Best Practices + +An issue alert is triggered when an individual issue meets some criteria. These criteria (or "triggers") can be based on state-changes or frequency. The best practices that follow cover alerts based on state and frequency changes, as well as reducing noise, and effective routing. + +### State-Change Alerts + +The following triggers, or “when” conditions, capture state changes in issues: + +- A new issue is created +- The issue changes state from resolved to unresolved, or a regression occurs +- The issue changes state from archived to escalating + +Your first instinct might be to set an alert for every state change. However, this is likely to result in too many alerts if you're running an app with a significant number of users. In particular, regressions will be more common than you expect because Sentry auto-resolves issues after 14 days of silence (configurable), and many issues keep coming back after the 14-day window. + +To deal with this, the **Issues** page includes the [**Review List**](/product/issues/states-triage/#mark-reviewed) (in the "For Review" tab), containing only issues that have had a state change in the last seven days. We recommended that you review this list once a day. If you need real-time notifications for particular types of issues, such as those affecting your enterprise customers, you can always create alerts with those filters. + +### Frequency-Based Alerts + +Below, we describe best practices for setting alerts using the following frequency-based triggers: + +- **Number of events in an issue**: This is a very commonly used trigger, but remember that frequency isn't everything: a low-frequency error can be more important than a high-frequency one if it's in a more important part of your app. +- **Number of users affected by an issue**: Sometimes a very small number of users create a lot of errors, so in some cases alerting on users affected can be more important than error frequency. However, remember that not all errors that have user counts in Sentry may be actually user-facing, and vice versa. +- **Percent of sessions affected by an issue**: Error counts and users affected require constant manual adjustments as your traffic patterns change and are not well suited to deal with seasonality (for example, fewer errors on the weekend). Also, it can be hard to assess the impact of an issue from error counts or counts of users affected. In such cases, if you've configured your project to capture session data, you can opt for alerting when an issue affects a certain percentage of user sessions. + +### Reducing Noise + +One way to keep alerts from becoming too noisy is to use filters, or “if” conditions, as part of your alert configuration. Below, we describe best practices for setting alerts using the following noise-reducing filtering options: + +- **Prioritize high priority issues**: If you're getting too many notifications about non-error or low priority issues, add the 'high priority' condition to your alert configuration. That way, you'll only get alerts for high-priority issues. +- **Prioritize using tags**: Filter issue alerts based on important tags, such as `customer_type=enterprise` or `url=/very/important/page`. You can find the list of tags available in your project under **[Project] > Settings > Tags**. The list is an aggregation of all tag keys (default and custom) encountered in events for that project. +- **Prioritize new issues**: If you're frequently getting alerted about old issues, filter your alerts to issues created in the last few days using the `The issue is older or newer than...` filter. +- **Filter transient issues**: Many issues exhibit a short burst of events that can trip your frequency-based alerts. To filter out these issues, use the `Issue has happened at least {X} times` filter. +- **Prioritize the latest release**: Use the `The event is from the latest release` filter to make your issue alert only apply to the latest release. +- **Archive noisy issues**: If you're seeing alerts from the same issue repeatedly, [archive the issue](/product/issues/states-triage/#archive). (This is not an alert configuration setting.) + +### Routing + +These routing best practices ensure that you alert the right people about a problem in your application. + +- **Ownership Rules**: Use [ownership rules and code owners](/product/issues/ownership-rules/) to let Sentry automatically send alerts to the right people, as well as to ease configuration burden. You can configure ownership in **[Project] > Settings > Ownership Rules**. In the case of ownership rules, when there are no matching owners, the alert goes to all project members by default. If this is too broad, and you'd like a specific owner to be the fallback, end your ownership rules with a rule like `*:`. +- **Delivery methods for different priorities**: Use different delivery methods to separate alerts of different priorities. For example, you might route from highest to lowest priority like so: + - High priority: Page (for example, PagerDuty or OpsGenie) + - Medium priority: Notification (for example, Slack) + - Low priority: Email +- **Review List**: Found in the "For Review" tab of **Issues**, the [**Review List**](/product/issues/states-triage/#mark-reviewed) is where you can check on your lowest priority issues without receiving any alerts. +- **Build an integration**: If you would like to route alert notifications to solutions with which Sentry doesn't yet have an out-of-the-box integration, you can use our [integration platform](/organization/integrations/integration-platform/). When you create an integration, it will be available in the alert actions menu. You might want use your own integration for: + - Sending alerts to integrations not supported natively + - Aggregating alerts from your different monitoring systems + - Writing custom rules in the webhook handler to route alerts more intelligently + +## Alert Conditions Best Practices + +Both frequency-based issue alerts and metric alerts can notify you in two ways: + +- When they cross a [fixed threshold](#fixed-thresholds) +- When they deviate from their historical behavior, based on a [dynamic threshold](#dynamic-thresholds-change-alerts), or what we call a _change alert_ + +### Fixed Thresholds + +Fixed thresholds are most effective when you have a clear idea of what constitutes good or bad performance. Typically, they’re the type of threshold you’ll use most often when setting up alerts. Some examples of fixed thresholds are: + +- When your app's crash rate exceeds 1% +- When your app's transaction volume drops to zero +- When any issue affects more than 100 enterprise users in a day +- When the response time of a key transaction exceeds 500 ms + +### Dynamic Thresholds: Change Alerts + +Dynamic thresholds help you detect when a metric deviates significantly from its “normal” range. For example, the percentage of sessions affected by an issue in the last 24 hours is _20% greater than one week ago_ (dynamic), rather than the percentage of sessions affected is simply _greater than 20%_ (fixed). + +Dynamic thresholds are good for when it’s cumbersome to create fixed thresholds for every metric of interest, or when you don’t have an expected value for a metric, such as in the following scenarios: + +- **Seasonal fluctuations**: Seasonal metrics, such as number of transactions (which fluctuates daily), are more accurately monitored by comparing them to the previous day or week, rather than a fixed value. +- **Unpredictable growth**: Fixed-threshold alerts may require continuous manual adjustment as traffic patterns change, such as with a fast-growing app. Dynamic thresholds work regardless of changing traffic patterns. + +You may want to **complement** (more common) rather than **replace** (less common) fixed thresholds with dynamic thresholds. + +Learn more about [change alerts for issue alerts](/product/alerts/create-alerts/issue-alert-config/#change-alerts) and [change alerts for metric alerts](/product/alerts/create-alerts/metric-alert-config/#change-alerts-percent-change) in the full documentation. diff --git a/docs/product/new-monitors-and-alerts/alerts/index.mdx b/docs/product/new-monitors-and-alerts/alerts/index.mdx new file mode 100644 index 0000000000000..0e57a431f7420 --- /dev/null +++ b/docs/product/new-monitors-and-alerts/alerts/index.mdx @@ -0,0 +1,68 @@ +--- +title: Alerts +description: Create custom Alerts to pair with Monitors. +sidebar_order: 60 +og_image: /og-images/product-alerts.png +--- + + + New Monitors and Alerts is currently in beta. Beta features are still a work in progress and may have bugs. We recognize the irony. Help improve this feature by providing feedback on our [GitHub discussion](https://github.com/getsentry/sentry/discussions/101960). + + +Sentry's Alerts help you take action when issues occur in your project. When an issue changes state, is created, or passes a threshold, an alert is triggered to perform external actions like sending notifications, creating tickets, or calling webhooks and integrations. Alerts must be paired with [Monitors](/product/new-monitors-and-alerts/monitors/) to run. + +### Some examples of when you could use an Alert +- Send a notification to your team's Slack channel when a new error occurs in an existing issue +- Create a ticket in JIRA when an issue is created and a team member is assigned +- Call a webhook or integration when an issue is created + +[!alert-config](./img/alert-config.png) + +## Creating an Alert + +To create an Alert, navigate to the [Alerts](https://sentry.io/issues/alerts/new/) page and click **Create Alert**. + +{/* */} + +### Set Triggers + +A trigger is an action that must occur for the Alert to run. All trigger actions are issue state based. For example, you may want to send a notification to your team's Slack channel _when an issue is created_. You can select multiple triggers in a single Alert. They will run under an `ANY` condition, meaning that if any one of the triggers happen, the Alert will run. + +### Set Filters + +Filters are conditions that must be met for the Alert to run. For example, you may want to create a ticket _only for issues that are assigned to a specific team_ and _at a certain severity_. You can create multiple filters in a single Alert, and group them under either `ANY` or `ALL` conditions. For `ANY` conditions, if any one of the filters are true, the Alert will run. For `ALL` conditions, only if all of the filters are true, the Alert will run. + +### Add Actions + +Actions are the events that will be executed when the Alert is run. You can send notifications on any channel you're integrated with, create tickets, for example, in JIRA, or call a webhook or integration. You can set multiple actions in a single Alert. Learn more about Sentry's [integrations](/organization/integrations/). + +**Note:** Some Monitors can only alert on certain integrations. See Sentry's [integrations](/organization/integrations/) for more information. + +## Connecting Alerts to Monitors + +In order for Alerts to run, you need to connect them to at least one [Monitor](/product/new-monitors-and-alerts/monitors/). To do so, select **Add Monitor** in the alert configuration page. You can add multiple monitors to an Alert. + +**Note**: If you set particular Environments as a filter in your Alert, it will only run for issues in those Environments, even if the Alert is connected to a Monitor that is filtered to different environments. + + +[!monitor-alerts](./img/monitor-alerts.png) + +## Managing Alerts + +You can see a list of all your Alerts on the [Alerts](https://sentry.io/issues/alerts/) page. By default, Alerts are filtered down to your projects. + + + +Alerts are an Organization-level feature. By default, all team members can create and edit Alerts. You can update this setting in [Organization Membership settings](https://sentry.io/settings/organization/). + + + +By clicking on an Alert, you can view the details, edit the Alert, or turn it on or off. + +The details page will show a high level chart of how often the Alert has run, a list of the most recent runs, the configuration, and connected monitors. + +[!alert-details](./img/alert-details.png) + +## Notifications + +Besides Alerts, Sentry sends you notifications about various things like [issue state changes](/product/issues/states-triage/), [release deploys](/product/releases/), and [quota usage](/pricing/quotas/). You can fine-tune these notifications, as well as your personal alert settings, in **User Settings > Notifications**. Learn more about notifications and adjusting their associated settings in [the full documentation](/product/new-monitors-and-alerts/alerts/notifications/). \ No newline at end of file diff --git a/docs/product/new-monitors-and-alerts/alerts/notifications/img/deploy-emails.png b/docs/product/new-monitors-and-alerts/alerts/notifications/img/deploy-emails.png new file mode 100644 index 0000000000000..cadd95e3de6d1 Binary files /dev/null and b/docs/product/new-monitors-and-alerts/alerts/notifications/img/deploy-emails.png differ diff --git a/docs/product/new-monitors-and-alerts/alerts/notifications/img/issue-alert-notification-detail.png b/docs/product/new-monitors-and-alerts/alerts/notifications/img/issue-alert-notification-detail.png new file mode 100644 index 0000000000000..e5279a1f649ea Binary files /dev/null and b/docs/product/new-monitors-and-alerts/alerts/notifications/img/issue-alert-notification-detail.png differ diff --git a/docs/product/new-monitors-and-alerts/alerts/notifications/img/issue-alert-notification.png b/docs/product/new-monitors-and-alerts/alerts/notifications/img/issue-alert-notification.png new file mode 100644 index 0000000000000..28699ec379ad4 Binary files /dev/null and b/docs/product/new-monitors-and-alerts/alerts/notifications/img/issue-alert-notification.png differ diff --git a/docs/product/new-monitors-and-alerts/alerts/notifications/img/subscription_notifications_settings.png b/docs/product/new-monitors-and-alerts/alerts/notifications/img/subscription_notifications_settings.png new file mode 100644 index 0000000000000..ebfe3932cb96b Binary files /dev/null and b/docs/product/new-monitors-and-alerts/alerts/notifications/img/subscription_notifications_settings.png differ diff --git a/docs/product/new-monitors-and-alerts/alerts/notifications/img/us-ereport.png b/docs/product/new-monitors-and-alerts/alerts/notifications/img/us-ereport.png new file mode 100644 index 0000000000000..a33b17dc1e957 Binary files /dev/null and b/docs/product/new-monitors-and-alerts/alerts/notifications/img/us-ereport.png differ diff --git a/docs/product/new-monitors-and-alerts/alerts/notifications/index.mdx b/docs/product/new-monitors-and-alerts/alerts/notifications/index.mdx new file mode 100644 index 0000000000000..66a7b6a689220 --- /dev/null +++ b/docs/product/new-monitors-and-alerts/alerts/notifications/index.mdx @@ -0,0 +1,86 @@ +--- +title: Sentry Notifications +sidebar_order: 40 +description: >- + Learn about the types of notifications that Sentry sends you, and how to + manage them. +og_image: /og-images/product-alerts-notifications.png +--- + +Sentry sends you notifications regarding workflow activities, [release deploys](/product/releases/), and [quota usage](/pricing/quotas/), as well as weekly reports. These notifications let you know about: + +- [Workflow](#workflow-notifications): Activity involving user actions and state changes on issues. This includes activities such as issue resolution, assignment, comments, and regressions. +- [Deploy](#deploy-notifications): When a release you have commits on is deployed. +- [Spend](#spend-notifications): When you're getting close to spending your reserved volume, your quotas are depleted, and/or your pay-as-you-go budget is being put to use. +- [Weekly Reports](#weekly-reports): A summary of your organization's Sentry activity. + +You can manage these notifications in **User Settings > Notifications**. + +## Workflow Notifications + +Sentry sends workflow notifications to let you know about [issue state](/product/issues/states-triage/) changes. Workflow relates to actions that help you manage your issues, such as changing an issue’s state or commenting on it. By default, Sentry sends these notifications by email to members who are subscribed to the issue (see below for how subscription is determined). Workflow notifications are sent for: + +- **Issue Resolved**: When a new issue is spotted in your code, it's in the Unresolved state. The issue state changes to Resolved when a project team member resolves it, either by manually changing its state in [sentry.io](https://sentry.io)) or by submitting a fix, or because of the project’s auto-resolve feature (if configured). +- **Regressions**: A regression happens when the state of an issue changes from Resolved back to Unresolved. An email is sent to all project team members. +- **Comments**: When a team member adds a new comment in the “Activity” tab of the detail page for the issue. +- **Assignment**: When an issue is assigned or unassigned. +- **Event Processing Problems**: When there's a problem with processing error events you've sent to Sentry. + +You receive workflow notifications when you subscribe to an issue in one of the following ways by: + +- You or your team being assigned to the issue +- Clicking the bell icon to subscribe to an issue +- Commenting on an issue +- Bookmarking an issue +- Resolving, unresolving, or archiving an issue +- Resolving an unassigned issue with the ["Claim Unassigned Issues I've Resolved"](/product/alerts/notifications/notification-settings/#my-activity) option turned on + +You or your team will become participants once you're subscribed to an issue. Participants can be viewed from the right hand sidebar at the bottom of the issue details page. Note that participant notifications may have some overlap with alerts that are configured on a per-project basis. + +You'll be unsubscribed from an issue if you: + +- Are unassigned from the issue +- Delete the only comment you left on an issue +- Remove a bookmark from an issue + +## Deploy Notifications + +Sentry sends deploy notifications to users who have committed to the release that was deployed. Learn more in the [deploy documentation](/product/releases/setup/#notify-sentry). + +![An example of an email describing deployed features](./img/deploy-emails.png) + +## Spend Notifications + +By default, Sentry sends spend notifications to all owners and billing members of an organization when: + +- 80% of the organization's reserved volume (such as errors, spans, and/or attachments) has been depleted. +- The entire reserved volume and any pay-as-you-go budget for a category (such as errors, spans, and/or attachments) has been depleted. +- 80% of the organization's pay-as-you-go budget has been used. + +Learn more in the [Pricing & Billing docs](/pricing/quotas/). + +### Spend Notifications for Your Organization + +Billing or owner members can set up their notification thresholds by going to: **Settings > Subscriptions > Notifications**. + +![Notifications tab of Subscription settings page](./img/subscription_notifications_settings.png) + +From here, you can customize the notification thresholds for your organization for when you're close to reaching one or both of the below: + +- **Subscription Consumption**: Set the percentage of the quota usage threshold(s) that will trigger a notification. + +- **Pay-as-you-go Consumption**: Set the percentage of the Pay-as-you-go usage threshold(s) that will trigger a notification. + +### Personal Spend Notifications + +Owner and billing members of an organization can also customize how they personally receive spend notifications. This can be done from the user's notification settings page: + +1. Go to the [**Notifications**](https://sentry.io/settings/account/notifications/) page (in your **User Settings**). +2. Scroll to the **Spend** row and click on the cog wheel. +3. From the [**Spend Notifications**](https://sentry.io/settings/account/notifications/quota/) page, you'll be able to select the types of notifications you get as well as how you'd like to get them (via Slack, email, and so on). + +## Weekly Reports + +Sentry sends weekly reports every Saturday, by email. Reports contain a summary of your organization's Sentry activity over the last week. + +![Weekly Report email sample.](./img/us-ereport.png) diff --git a/docs/product/new-monitors-and-alerts/alerts/notifications/notification-settings.mdx b/docs/product/new-monitors-and-alerts/alerts/notifications/notification-settings.mdx new file mode 100644 index 0000000000000..c44a515d03445 --- /dev/null +++ b/docs/product/new-monitors-and-alerts/alerts/notifications/notification-settings.mdx @@ -0,0 +1,42 @@ +--- +title: Personal Notification Settings +sidebar_order: null +description: Learn how to manage your personal notifications settings. +og_image: /og-images/product-alerts-notifications-notification-settings.png +--- + +You can update your personal notification settings for things like [workflow](/product/new-monitors-and-alerts/alerts/notifications/), deploy, issue alert, and [spike protection](/pricing/quotas/spike-protection/) by turning them on or off, specifying how you'd like to be notified (via email, Slack, or both), and more. Users who **aren't** on an [Enterprise](https://sentry.io/pricing/) plan can also configure their quota notifications. + +![Issue alert notification page](./img/issue-alert-notification.png) + +To make updates, go to your [user settings](https://sentry.io/settings/account/notifications/), select "Notifications", then click on the notification type you want to update. + +![Issue alert notification detail page](./img/issue-alert-notification-detail.png) + +## How to Subscribe to an Issue + +You receive workflow notifications once you’ve subscribed to an issue in one of the ways described below: + +- By clicking the subscribe "bell icon" on an issue +- By taking part in a commit that's related to the issue +- By commenting on or bookmarking the issue +- By archiving an issue until it escalates +- If you or your team is mentioned in the issue +- If you or your team is assigned to the issue + +These notifications may have some overlap with [alerts](/product/new-monitors-and-alerts/alerts/) that are configured for a project. + +## Notification Types + +Here's a list of all the personal notification types you can update: + +- **Issue Alerts:** Notifications sent from alert rules that your team's set up. (You'll still get any notifications that have been set up to be sent directly to you.) +- **Issue Workflow:** Changes in issue assignment, resolution status, and comments. +- **Deploys:** Release, environment, and commit overviews. +- **Nudges:** Notifications that require review or approval. +- **Spend:** Notifications alerting you about your organization's spend and billing quota. +- **Weekly Reports:** A summary of the past week for an organization. +- **Email Routing:** Changes to the email address that receives notifications. +- **Spike Protection:** Notifications about spikes on a per project basis. +- **My Own Activity:** Notifications about your own actions on Sentry. +- **Resolve and Auto-Assign:** When you resolve an unassigned issue, we'll auto-assign it to you. diff --git a/docs/product/new-monitors-and-alerts/index.mdx b/docs/product/new-monitors-and-alerts/index.mdx new file mode 100644 index 0000000000000..69fbbf532bb3b --- /dev/null +++ b/docs/product/new-monitors-and-alerts/index.mdx @@ -0,0 +1,15 @@ +--- +title: New Monitors and Alerts +description: "Learn more about new Monitors and Alerts features in Sentry." +sidebar_order: 8000 +--- + + + New Monitors and Alerts is currently in beta. Beta features are still a work in progress and may have bugs. We recognize the irony. Help improve this feature by providing feedback on our [GitHub discussion](https://github.com/getsentry/sentry/discussions/101960). + + +Sentry's Monitors and Alerts help you proactively track and respond to issues in your application. Use [**Monitors**](/product/new-monitors-and-alerts/monitors/) to track cron jobs, scheduled tasks, and uptime for your services. Set up [**Alerts**](/product/new-monitors-and-alerts/alerts/) to get notified when errors occur, performance degrades, or monitors fail, so you can quickly identify and resolve problems before they impact your users. + +## Learn More + + diff --git a/docs/product/new-monitors-and-alerts/monitors/crons/alerts-backend-insights-migration.mdx b/docs/product/new-monitors-and-alerts/monitors/crons/alerts-backend-insights-migration.mdx new file mode 100644 index 0000000000000..45ab3258daad7 --- /dev/null +++ b/docs/product/new-monitors-and-alerts/monitors/crons/alerts-backend-insights-migration.mdx @@ -0,0 +1,22 @@ +--- +title: Cron Monitoring Updates for Developers +noindex: true +draft: true +sidebar_hidden: true +og_image: /og-images/product-crons-alerts-backend-insights-migration.png +--- + +The **Cron Monitoring** feature has been relocated and restructured to improve accessibility and functionality. Previously, it was found in the sidebar under **"Crons"**, but it has now been split into two different locations: + +## Timeline View (Overview of Cron Jobs) + +- The timeline view that provided an overview of all cron jobs has moved. +- You can now find it under **Insights > Backend > Cron Monitors (Tab)**. + ![Screenshot showing new location](img/crons-as-backend-insights.png) + +## Managing Cron Monitors + +- The section for managing all of your cron monitors is now under **Alerts**. +- **Cron Monitors are now a new type of Sentry Alert**, allowing for better integration and management within the Alerts system. +- To filter and view all cron monitors easily, use the **Alert Type** filter for "Cron Monitors". + ![Screenshot showing Alerts menu and filter](img/crons-as-alerts-guide.png) diff --git a/docs/product/new-monitors-and-alerts/monitors/crons/getting-started/http/index.mdx b/docs/product/new-monitors-and-alerts/monitors/crons/getting-started/http/index.mdx new file mode 100644 index 0000000000000..7fcf32ac93de0 --- /dev/null +++ b/docs/product/new-monitors-and-alerts/monitors/crons/getting-started/http/index.mdx @@ -0,0 +1,248 @@ +--- +title: HTTP +sidebar_order: 100 +description: "Follow this guide to set up and manage monitors using the Sentry API." +--- + +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 + +To begin monitoring your recurring, scheduled job: + +1. [Create a new monitor](https://sentry.io/issues/alerts/new/crons/) in Sentry. +2. Configure check-ins or a heartbeat for your job. + +Optionally, you can skip the first step and [create or update (upsert) a monitor through a check-in](#creating-or-updating-a-monitor-through-a-check-in-optional). See more below. + +## 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). + + +```bash {tabTitle: cURL} +SENTRY_INGEST="https://___ORG_INGEST_DOMAIN___" +SENTRY_CRONS="${SENTRY_INGEST}/api/___PROJECT_ID___/cron//___PUBLIC_KEY___/" + +# 🟡 Notify Sentry your job is running: +curl "${SENTRY_CRONS}?status=in_progress" + +# Execute your scheduled task here... + +# 🟢 Notify Sentry your job has completed successfully: +curl "${SENTRY_CRONS}?status=ok" +``` + +```http {tabTitle: HTTP} +GET /api/___PROJECT_ID___/cron//___PUBLIC_KEY___/?status=in_progress HTTP/1.1 +Host: ___ORG_INGEST_DOMAIN___ + +GET /api/___PROJECT_ID___/cron//___PUBLIC_KEY___/?status=ok HTTP/1.1 +Host: ___ORG_INGEST_DOMAIN___ +``` + +If your job execution fails: + + +```bash {tabTitle: cURL} +# 🔴 Notify Sentry your job has failed: +curl "${SENTRY_CRONS}?status=error" +``` + +```http {tabTitle: HTTP} +GET /api/___PROJECT_ID___/cron//___PUBLIC_KEY___/?status=error HTTP/1.1 +Host: ___ORG_INGEST_DOMAIN___ +``` + + + +If you expect your scheduled jobs to overlap, read about [Overlapping Jobs](#overlapping-jobs-optional) below. + + + +### Specifying monitor environments (Optional) + +When sending check-ins to your monitor you may specify the `environment` of the +check-in. This allows you to monitor a single schedule across multiple +environments. + +If you don't specify an environment with your check-ins the default is `production`. + + + +Monitor environments are still early in development. Currently, after a check-in +occurs for a specific environment, you must continue sending check-ins on +schedule or delete the monitor environment; otherwise, it will be marked as missed. + + + + +```bash {tabTitle: cURL} +SENTRY_INGEST="https://___ORG_INGEST_DOMAIN___" +SENTRY_CRONS="${SENTRY_INGEST}/api/___PROJECT_ID___/cron//___PUBLIC_KEY___/" + +# 🟡 Notify Sentry your job is running in the dev environment: +curl "${SENTRY_CRONS}?environment=dev&status=in_progress" + +# Execute your scheduled task here... + +# 🟢 Notify Sentry your dev environment job has completed successfully: +curl "${SENTRY_CRONS}?environment=dev&status=ok" +``` + +### Creating or Updating a Monitor Through a Check-In (Optional) + +Sentry enables the automatic creation or update of a monitor (upsert) through the check-in payload. This can be useful if you have many scheduled tasks or need to create them dynamically. + + +```bash {tabTitle: cURL} +SENTRY_INGEST="https://___ORG_INGEST_DOMAIN___" +SENTRY_CRONS="${SENTRY_INGEST}/api/___PROJECT_ID___/cron//___PUBLIC_KEY___/" + +# 🟡 Notify Sentry your job is running: +curl -X POST "${SENTRY_CRONS}" \ + --header 'Content-Type: application/json' \ + --data-raw '{"monitor_config": {"schedule": {"type": "crontab", "value": "0 * * * *"}}, "status": "in_progress"}' +``` + +```http {tabTitle: HTTP} +POST /api/___PROJECT_ID___/cron//___PUBLIC_KEY___/ HTTP/1.1 +Host: ___ORG_INGEST_DOMAIN___ +Content-Type: application/json + +{ + "monitor_config": { + "schedule": {"type": "crontab", "value": "0 * * * *"}, + "checkin_margin": 1, + "max_runtime": 20, + "timezone": "America/Los_Angeles" + "failure_issue_threshold": 1, + "recovery_threshold": 1, + }, + "status": "in_progress" +} +``` + +Monitor `monitor_config` parameters: + +`schedule_type`: + +The schedule representation for your monitor, either `crontab` or `interval`. + +`schedule`: + +The job's schedule : + +This is an object specifying a `schedule_type` of either `crontab` or `interval`. The structure will vary depending on the type: + +```json +{"type": "crontab", "value": "0 * * * *"} +{"type": "interval", "value": "2", "unit": "hour"} +``` + +`checkin_margin`: + +The amount of time (in minutes) Sentry should wait for your check-in before it's considered missed ("grace period"). Optional. + + + +We recommend that your check-in margin be less than or equal to your interval. + + + +`max_runtime`: + +The amount of time (in minutes) your job is allowed to run before it's considered failed. Optional. + +`failure_issue_threshold`: + +: The number of consecutive failed check-ins it takes before an issue is created. Optional. + +`recovery_threshold`: + +: The number of consecutive OK check-ins it takes before an issue is resolved. Optional. + +`timezone` + +The `tz` where your job is running. This is usually your server's timezone, (such as `America/Los_Angeles`). See [list of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Optional. + + + +It's important to provide a timezone for non-repeating crontab schedules, such as `0 17 * * *` (every day at 5pm). + + + +### Overlapping Jobs (Optional) + +A job execution that begins before the previous job execution has been completed is called an overlapping job. This happens if you have a job with a runtime duration longer than your job's interval schedule. + +A simple example is if you have a job that runs every minute (1), but takes five (5) minutes to complete each execution. + +If this happens, you have to provide a stable check-in ID for your execution with each request to prevent unintended consequences. + +Usage example: + + +```bash {tabTitle: cURL} +CHECK_IN_ID="$(uuidgen)" + +SENTRY_INGEST="https://___ORG_INGEST_DOMAIN___" +SENTRY_CRONS="${SENTRY_INGEST}/api/___PROJECT_ID___/cron//___PUBLIC_KEY___/" + +# 🟡 Notify Sentry your job is running with a check-in ID: +curl "${SENTRY_CRONS}?check_in_id=${CHECK_IN_ID}&status=in_progress" + +# Execute your scheduled task here... + +# 🟢 Notify Sentry your job has completed successfully with a check-in ID: +curl "${SENTRY_CRONS}?check_in_id=${CHECK_IN_ID}&status=ok" +``` + +## 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. + + +```bash {tabTitle: cURL} +SENTRY_INGEST="https://___ORG_INGEST_DOMAIN___" +SENTRY_CRONS="${SENTRY_INGEST}/api/___PROJECT_ID___/cron//___PUBLIC_KEY___/" + +# 🟢 Notify Sentry your job has completed successfully: +curl "${SENTRY_CRONS}?status=ok" +``` + +```http {tabTitle: HTTP} +GET /api/___PROJECT_ID___/cron//___PUBLIC_KEY___/?status=ok HTTP/1.1 +Host: ___ORG_INGEST_DOMAIN___ +``` + +If your job execution fails: + + +```bash {tabTitle: cURL} +# 🔴 Notify Sentry your job has failed: +curl "${SENTRY_CRONS}?status=error" +``` + +```http {tabTitle: HTTP} +GET /api/___PROJECT_ID___/cron//___PUBLIC_KEY___/?status=error HTTP/1.1 +Host: ___ORG_INGEST_DOMAIN___ +``` + +## Alerts + +When your recurring job fails to check in (missed), runs beyond its configured maximum runtime (failed), or manually reports a failure, Sentry will create an error event with a tag to your monitor. + +To receive alerts about these events: + +1. Navigate to **Alerts** in the sidebar. +2. Create a new alert and select "Issues" under "Errors" as the alert type. +3. Configure your alert and define a filter match to use: `The event's tags match {key} {match} {value}`. + +Example: `The event's tags match monitor.slug equals my-monitor-slug-here` + + + +Learn more in [Issue Alert Configuration](/product/alerts/create-alerts/issue-alert-config/). + + diff --git a/docs/product/new-monitors-and-alerts/monitors/crons/getting-started/index.mdx b/docs/product/new-monitors-and-alerts/monitors/crons/getting-started/index.mdx new file mode 100644 index 0000000000000..532cca9e4ca40 --- /dev/null +++ b/docs/product/new-monitors-and-alerts/monitors/crons/getting-started/index.mdx @@ -0,0 +1,35 @@ +--- +title: Set Up +sidebar_order: 0 +description: "Learn how to set up Sentry's Cron Monitoring using our CLI, HTTP, and supported SDKs." +--- + +To set up Sentry Crons, use the links below for supported SDKs or the Sentry CLI. After it's been set up, you'll be able to receive alerts if your job fails to run at its scheduled time or doesn't execute successfully. + +## Supported SDKs + +- [PHP](/platforms/php/crons/) + - [Laravel](/platforms/php/guides/laravel/crons/) +- [Python](/platforms/python/crons/) + - [Celery](/platforms/python/integrations/celery/crons/) +- [Node](/platforms/javascript/guides/node/crons/) + - [Next.js](/platforms/javascript/guides/nextjs/crons/) + - [SvelteKit](/platforms/javascript/guides/sveltekit/crons/) + - [Remix](/platforms/javascript/guides/remix/crons/) + - [NestJS](/platforms/javascript/guides/nestjs/crons/) +- [Go](/platforms/go/crons/) +- [Java](/platforms/java/crons/) + - [Spring Boot](/platforms/java/guides/spring-boot/crons/) +- [Ruby](/platforms/ruby/crons/) +- [Elixir](/platforms/elixir/crons/) + + + +We're working on enabling additional platforms for Crons. In the meantime, you can use the Sentry CLI or HTTP to set up monitoring for your jobs. + + + +## Others + +- [HTTP](/product/new-monitors-and-alerts/monitors/crons/getting-started/http/) +- [Sentry CLI](/cli/crons/) diff --git a/docs/product/new-monitors-and-alerts/monitors/crons/img/crons-as-alerts-guide.png b/docs/product/new-monitors-and-alerts/monitors/crons/img/crons-as-alerts-guide.png new file mode 100644 index 0000000000000..655da1d7eae35 Binary files /dev/null and b/docs/product/new-monitors-and-alerts/monitors/crons/img/crons-as-alerts-guide.png differ diff --git a/docs/product/new-monitors-and-alerts/monitors/crons/img/crons-as-backend-insights.png b/docs/product/new-monitors-and-alerts/monitors/crons/img/crons-as-backend-insights.png new file mode 100644 index 0000000000000..d4323cee0f30c Binary files /dev/null and b/docs/product/new-monitors-and-alerts/monitors/crons/img/crons-as-backend-insights.png differ diff --git a/docs/product/new-monitors-and-alerts/monitors/crons/index.mdx b/docs/product/new-monitors-and-alerts/monitors/crons/index.mdx new file mode 100644 index 0000000000000..9a0eaecbdb69b --- /dev/null +++ b/docs/product/new-monitors-and-alerts/monitors/crons/index.mdx @@ -0,0 +1,24 @@ +--- +title: "Cron Monitoring" +sidebar_order: 40 +description: "Monitor your recurring jobs with Sentry to help maintain uptime and performance." +--- + +Sentry's Cron Monitoring allows you to monitor the uptime and performance of any scheduled, recurring job in Sentry. Once implemented, it'll allow you to get alerts and metrics to help you solve errors, detect timeouts, and prevent disruptions to your service. + +## Example Cron Monitoring Use Cases + +- An invoice generation job, where it's critical for each job run to be completed successfully and in a timely manner with a predefined, scheduled, interval and frequency. +- A server cleanup tool, where each job execution must not exceed a pre-defined runtime threshold. +- Any other standalone unit of execution with a finite input. + +To use Cron Monitoring, you must have an existing Sentry account and project set up. If you don't have one, [create an account here](https://sentry.io/signup/). + +## Learn More About Cron Monitoring + +- [Set Up](/product/new-monitors-and-alerts/monitors/crons/getting-started/) +Learn how to set up Sentry's job monitoring feature using our CLI, HTTP, and supported SDKs. +- [Job Monitoring](/product/new-monitors-and-alerts/monitors/crons/job-monitoring/) +Get a product walkthrough of our Job Monitoring feature. +- [Troubleshooting](/product/new-monitors-and-alerts/monitors/crons/troubleshooting/) +Get troubleshooting help. diff --git a/docs/product/new-monitors-and-alerts/monitors/crons/job-monitoring.mdx b/docs/product/new-monitors-and-alerts/monitors/crons/job-monitoring.mdx new file mode 100644 index 0000000000000..1808ff28f6dac --- /dev/null +++ b/docs/product/new-monitors-and-alerts/monitors/crons/job-monitoring.mdx @@ -0,0 +1,61 @@ +--- +title: Job Monitoring +sidebar_order: 1 +description: "Learn how to set up monitor notifications, monitor the same job in multiple environments, and manage your monitor in the Sentry UI." +--- + +Sentry's Cron Monitoring service can notify you and store a timeline of the following check-in events: + +- **Missed check-in:** The job didn't execute in the predicted timeframe or frequency. This can happen for various reasons, such as: + - The job scheduler is misconfigured, skipped, or failed to initiate your job. + - A timeout failure event when a job sent an initial check-in but failed to send a final check-in. + - Network issues, such as an outbound firewall or an unstable connection. + - An invalid request format. +- **Failed check-in:** The job has reported its execution as unsuccessful. +- **Successful check-in:** The job has reported its execution as successful. + +To see information about your cron monitor, select "Crons" from the sidebar menu and click on your cron monitor's name. + +## Cron Monitor Details + +This is where you'll find a daily historical bar chart showing successful, failed, and missed check-ins and a line chart of the runtime average for the job execution. + +The "Issues" section shows the issues created from this Cron Monitor. Issues are created when a cron monitor job execution is missed or failed. If you have configured the Sentry SDK for your job, any errors thrown during the job runtime will be shown here as well. + +The table of recent check-ins lists previously scheduled jobs and their statuses. + + + +## Multiple Environments + +To monitor the same job in different environments, use a shared schedule to send check-ins for multiple environments to one monitor. Each environment will have its own status and set of check-ins. + +### Alerting on Specific Environments + +To only receive failing or missed monitor alerts for a specific environment or set of environments, [configure the +environment](/product/alerts/create-alerts/issue-alert-config/#environment) for +your monitor alert. + +### Existing Limitations: + +- It's not currently possible to pause an individual monitor environment. + +- It's not currently possible to see an aggregate view of a monitors' status + across all environments. Each environment will appear as its own row in the + monitor list. + +## Ownership + +Cron monitors can be assigned an owner as either a Team or specific Organization Member. When an owner is assigned to a monitor, new issues produced by failures of that monitor will be assigned to that owner. + +Monitor owners also receive notifications when a monitor becomes broken. Learn more about [broken monitor notifications](/product/new-monitors-and-alerts/monitors/crons/troubleshooting/#why-was-my-monitor-environment-marked-as-broken-or-automatically-muted). + +## Pausing Your Cron Monitor + +You can pause job monitoring in the header of your cron monitor. When you pause, your monitor will stop recording check-ins and will no longer notify you of any failed or missed check-ins. + +Note: Pausing your cron monitor won't pause the execution of your job or change the configuration of your job scheduler. + +### Automatic Muting + +If a monitor environment has been consistently broken for an extended period, Sentry may automatically mute it to reduce notification noise. Unlike pausing, muting does not stop billing. Learn more about [automatic muting and broken monitors](/product/new-monitors-and-alerts/monitors/crons/troubleshooting/#why-was-my-monitor-environment-marked-as-broken-or-automatically-muted). diff --git a/docs/product/new-monitors-and-alerts/monitors/crons/legacy-endpoint-migration.mdx b/docs/product/new-monitors-and-alerts/monitors/crons/legacy-endpoint-migration.mdx new file mode 100644 index 0000000000000..f61a57b330e76 --- /dev/null +++ b/docs/product/new-monitors-and-alerts/monitors/crons/legacy-endpoint-migration.mdx @@ -0,0 +1,148 @@ +# Legacy Endpoint Migration + +In the early beta of the Crons product, Check-In endpoints existed under the +`sentry.io/api/0/` API namespace. This namespace is not designed for +ingestion-level traffic, so we have since moved Check-In APIs to use +[Relay](/product/relay/) for ingestion of Check-In events. + +If you're using legacy endpoints for Crons, migrate to the new endpoints to avoid issues. + + + +The Legacy endpoints **are deprecated** and will be removed in the future, +however a date has not yet been set for their removal. We will communicate a +date when one is set. + + + +## Am I Using Legacy Endpoints? + +The SDKs do not utilize our legacy endpoints. + + + +Versions of the `sentry-cli` **before v2.19.0** are using the legacy API endpoints. [Please upgrade](/cli/installation/#updating-and-uninstalling) to the latest version. + +If your CLI is configured with an auth token, it will use the legacy API endpoints. Please update your CLI configuration to utilize your project's DSN instead. Refer to the [configuration guide](/cli/crons/#configuration) for more information. + + + +When using the HTTP endpoints, you can differentiate them like so: + +``` +# ❌ Legacy endpoints +https://sentry.io/api/0/organizations/___ORG_SLUG___/monitors// + +# ✅ Relay Check-In ingestion endpoint +https://___ORG_INGEST_DOMAIN___/api/___PROJECT_ID___/cron//___PUBLIC_KEY___/ +``` + +### What Changed? + +There are a few backward incompatible changes to be aware of. + +- There is now only a single Check-In endpoint. The "Check-In details" + endpoint has been removed. + +- The API endpoint supports both `POST` with a JSON body, as well as now + supporting `GET`. You can use query parameters to specify `status`, + `environment`, etc. + + The API endpoint will always respond with a `202` with no body (unless there + is an error). + +- Because there is no "details" endpoint, the `PUT` method for a Check-In has + also been removed. You will always use `POST` or `GET` for Check-Ins. + +- For [overlapping + jobs](/product/new-monitors-and-alerts/monitors/crons/getting-started/http/#overlapping-jobs-optional), it is + still possible to specify a `check_in_id` via the query parameters or JSON + body. However, the API no longer responds with an auto-generated Check-In ID. + If you need a stable Check-In ID, you must generate it + client-side yourself. + +- The `monitor_config` structure has changed slightly. `schedule` is now an + object of varying shape, depending on the schedule type. + + ```json + {"type": "crontab", "value": "0 * * * *"} + {"type": "interval", "value": "2", "unit": "hour"} + ``` + +## Migration examples + +See the code samples below to help you migrate from the legacy endpoints to the current ones. + +### Simple HTTP Check-Ins + +```sh +# ❌ Legacy simple `in_progress` -> `ok` check-in +curl -X POST \ + 'https://sentry.io/api/0/organizations/___ORG_SLUG___/monitors//checkins/' \ + --header 'Authorization: DSN ___PUBLIC_DSN___' \ + --header 'Content-Type: application/json' \ + --data-raw '{"status": "in_progress"}' + +curl -X POST \ + 'https://sentry.io/api/0/organizations/___ORG_SLUG___/monitors//checkins/' \ + --header 'Authorization: DSN ___PUBLIC_DSN___' \ + --header 'Content-Type: application/json' \ + --data-raw '{"status": "ok"}' + + +# ✅ New style `in_progress` -> `ok` check-in +SENTRY_INGEST="https://___ORG_INGEST_DOMAIN___" +SENTRY_CRONS="${SENTRY_INGEST}/api/___PROJECT_ID___/cron//___PUBLIC_KEY___/" + +curl "${SENTRY_CRONS}?status=in_progress" + +curl "${SENTRY_CRONS}?status=ok" +``` + +### Monitor Upsert Check-In + +```sh +# ❌ Legacy upsert monitor with a check-in +curl -X POST \ + 'https://sentry.io/api/0/organizations/___ORG_SLUG___/monitors//checkins/' \ + --header 'Authorization: DSN ___PUBLIC_DSN___' \ + --header 'Content-Type: application/json' \ + --data-raw '{"monitor_config": {"schedule": "0 * * * *", "schedule_type": "crontab"}, "status": "in_progress"}' + +# ✅ New style upsert monitor with a check-in +SENTRY_INGEST="https://___ORG_INGEST_DOMAIN___" +SENTRY_CRONS="${SENTRY_INGEST}/api/___PROJECT_ID___/cron//___PUBLIC_KEY___/" + +curl -X POST "${SENTRY_CRONS}?status=in_progress" \ + --header 'Content-Type: application/json' \ + --data-raw '{"monitor_config": {"schedule": {"type": "crontab", "value": "0 * * * *"}}, "status": "in_progress"}' + # 👉 Note that schedule is now an object ---^ +``` + +### Overlapping Job Check-Ins (specifying `check_in_id`) + +```sh +# ❌ Legacy Check-In with ID +curl -X POST \ + 'https://sentry.io/api/0/organizations/___ORG_SLUG___/monitors//checkins/' \ + --header 'Authorization: DSN ___PUBLIC_DSN___' \ + --header 'Content-Type: application/json' \ + --data-raw '{"status": "in_progress"}' +# Response { "id": "2bc1a871-a1b7-4577-82fc-fa6d2468aabc" } + +# ✅ New style upsert monitor with a check-in +CHECK_IN_ID="$(uuidgen)" +# 👉 Note that you now need to generate the Check-In UUID + +SENTRY_INGEST="https://___ORG_INGEST_DOMAIN___" +SENTRY_CRONS="${SENTRY_INGEST}/api/___PROJECT_ID___/cron//___PUBLIC_KEY___/" + +curl "${SENTRY_CRONS}?check_in_id=${CHECK_IN_ID}&status=in_progress" +# 👉 Note that no Check-In ID is returned +``` diff --git a/docs/product/new-monitors-and-alerts/monitors/crons/troubleshooting.mdx b/docs/product/new-monitors-and-alerts/monitors/crons/troubleshooting.mdx new file mode 100644 index 0000000000000..f84366661da0b --- /dev/null +++ b/docs/product/new-monitors-and-alerts/monitors/crons/troubleshooting.mdx @@ -0,0 +1,54 @@ +--- +title: Troubleshooting +sidebar_order: 3 +description: "Troubleshoot common issues with cron monitoring." +--- + + + +All monitors are automatically deactivated at the start of a new billing period if there's not enough [on-demand spend](/pricing/#on-demand-capacity) to cover all active monitors. Monitors can be manually activated based on on-demand availability. See [Manage Your Cron Monitors](/pricing/quotas/manage-cron-monitors) for more details. + + + + + +If your monitor environment has been consistently broken for 14 days or more (with only missed, timed out, or failed check-ins), we will automatically mark it as broken and notify you of this escalated failure state via email. + +If the monitor environment continues to be broken after an additional 14 days, we will automatically mute it to stop it from generating additional noise through notifications or issue events. + +**Who Receives the Notification:** + +- If the monitor has an owner who is a user, that user will receive the email +- If the monitor has an owner who is a team, all team members will receive the email +- If the monitor has no owner, everyone in the project team will receive the email + +**Important Notes:** + +- You can disable these notifications in your [personal notification settings](/product/new-monitors-and-alerts/alerts/notifications/notification-settings/) +- Muting a monitor does **not** stop billing. You will continue to be charged for muted monitors. To stop billing, you must deactivate or delete the monitor. See [Manage Your Cron Monitors](/pricing/quotas/manage-cron-monitors) for more details. + + + + + +You may not have [linked errors to your monitor](/product/new-monitors-and-alerts/monitors/crons/getting-started/http/#connecting-errors-to-cron-monitors). + + + + + +You may not have [set up alerts for your monitor](/product/new-monitors-and-alerts/monitors/crons/getting-started/http/#alerts). + + + + + +Our current data retention policy is 90 days. + + + + + +Currently, we only support crontab expressions with five fields. + + diff --git a/docs/product/new-monitors-and-alerts/monitors/index.mdx b/docs/product/new-monitors-and-alerts/monitors/index.mdx new file mode 100644 index 0000000000000..6df1366114115 --- /dev/null +++ b/docs/product/new-monitors-and-alerts/monitors/index.mdx @@ -0,0 +1,94 @@ +--- +title: Monitors +description: Generate issues and trigger alerts by creating custom monitors to track errors, performance, and metrics. +sidebar_order: 70 +--- + + + New Monitors and Alerts is currently in beta. Beta features are still a work in progress and may have bugs. We recognize the irony. Help improve this feature by providing feedback on our [GitHub discussion](https://github.com/getsentry/sentry/discussions/101960). + + +Sentry's Monitors are used to customize when to turn errors and performance problems into issues. They can be configured using conditional rules to create issues when specific criteria are met. For example, you could monitor when the duration of a transaction takes longer than 3 seconds on a particular browser. Further automate your issue creation experience using Monitors to automatically add assignees and set different priorities based on severity. + +## Types of Monitors + +### Custom Monitors + +You can use Custom Monitors to track errors based on span attributes and custom metrics, the uptime and performance of any scheduled, recurring job, or the uptime and performance of any HTTP request. + +- [Metric Monitors](#metric-monitor-settings): Track for errors based on span attributes and custom metrics. +- [Cron Monitors](/product/new-monitors-and-alerts/monitors/crons/): Track the uptime and performance of any scheduled, recurring job. +- [Uptime Monitors](/product/new-monitors-and-alerts/monitors/uptime-monitoring/): Track the uptime and performance of any HTTP request. + +### Default Monitors + +Sentry also provides default monitors that are automatically created for you when you create a new project. + +- **Error Monitor**: The default monitor based on [issue grouping/fingerprint rules](/concepts/data-management/event-grouping/) +- **Replay Monitor**: Once you've configured [Session Replay](/product/explore/session-replay/), issues will be created via the Replay Monitor +- **Trace Monitor**: Once you've configured [Tracing](/product/tracing/), issues will be created via the Trace Monitor +- **Profile Monitor**: Once you've configured [Profiling](/product/explore/profiling/), issues will be created via the Profile Monitor + +## Creating a Monitor +To create a Monitor, navigate to the [Monitors](https://sentry.io/issues/monitors/new/) page and click **Create Monitor**. You can choose between the three types of Monitors (metric, cron, and uptime). Each one will have a separate configuration process. + +### General Settings + +Monitors are made of attributes that define when to create an issue, and actions that define what to do when an issue is created. + +- Name the Monitor +- Select the project, and in some cases, the environment +- Select attributes based on the Monitor type +- Set priority based on attributes +- Set the assignee +- Set auto-resolve based on attributes +- Connect [Custom Alerts](/product/automations/custom-automations/) like notifications and ticket creation +to pair with your Monitor + + + +Assignees set by [ownership rules](/product/issues/ownership-rules/) will override assignees set by Monitors. + + + +{/* */} + +### Metric Monitor Settings + +Metric Monitors are used to track errors based on span attributes and custom metrics. + +[!metric-monitor-config](./img/metric-monitor-config.png) + +Choose the metric, the interval for how often to check, and the way you want to monitor for changes. You can choose an absolute number threshold, a percentage change, or dynamic anomaly detection. + +### Cron Monitor Settings + +Cron Monitors are used to track the uptime and performance of any scheduled, recurring job. + +[!cron-monitor-config](./img/cron-monitor-config.png) + +Choose the schedule for how often to check, set the check-in margin, the max runtime, and failure tolerance. + +### Uptime Monitor Settings + +Uptime Monitors are used to track the uptime and performance of any HTTP request. + +[!uptime-monitor-config](./img/uptime-monitor-config.png) + +Choose the URL and HTTP request you wish to monitor. Set the interval, timeout, and any headers you wish to include. + +## Managing Monitors + +You can see a list of all your Monitors on the [Monitors](https://sentry.io/issues/monitors/) page. Select a Monitor type at the top of the page to narrow down the list. By default, Monitors are filtered down to your projects. + + + +Monitors are a Project-level feature, but the permission set is organization-level. By default, all members can create and edit Monitors. You can update this setting in [Organization Membership settings](https://sentry.io/settings/organization/). + + + +By clicking on a Monitor, you can view the details, edit the Monitor, or disable it. + +The details page will show a high level chart of the Monitor's performance, the configuration, created issue, and connected automations. + +[!monitor-details](./img/monitor-details.png) \ No newline at end of file diff --git a/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/automatic-detection.mdx b/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/automatic-detection.mdx new file mode 100644 index 0000000000000..965888a016e52 --- /dev/null +++ b/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/automatic-detection.mdx @@ -0,0 +1,26 @@ +--- +title: Automatic Detection +sidebar_order: 51 +description: "Learn how automatic detection of uptime monitoring works." +--- + +In order to be able to automatically detect uptime alerts, we analyze all the URLs detected in your project's captured error data to find the hostname that appears most frequently. This helps ensure that your most critical hostname is continuously monitored, enhancing the reliability and availability of your web services. We then create an uptime alert if it passes our [uptime check criteria](/product/new-monitors-and-alerts/monitors/uptime-monitoring/#uptime-check-criteria). Automatic uptime checks are configured to run once a minute as GET requests. + +The automatic creation of Uptime Monitors only happens if there are no other existing uptime monitors configured. + +To avoid creating flaky alerts, the hostname undergoes an "onboarding period" of three days. During this period, we send HTTP requests to the hostname every hour. If the request fails three times or more, the hostname will be dropped and re-evaluated after seven days. + + + Sentry will execute uptime checks against the hostname root path of the most + frequently-seen URLs. For example, if the most frequently-seen URL in your + events is `GET https://www.example.com/docs/introduction`, the check will be + `GET https://www.example.com/`. + + +Once an automatically detected uptime alert has been created, you'll be able to [customize its configuration](/product/alerts/create-alerts/uptime-alert-config/), including the HTTP request method, headers, and request body. + +## Disabling Automatic Detection + +If you prefer not to use automatically detected uptime alerts, you can delete them directly from your [Alerts page](https://sentry.io/orgredirect/organizations/:orgslug/alerts/rules). + +**Once deleted, these automatically detected uptime alerts will not be re-created in the future.** diff --git a/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/img/allow-sampling-new.png b/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/img/allow-sampling-new.png new file mode 100644 index 0000000000000..3f28a3d3e4b99 Binary files /dev/null and b/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/img/allow-sampling-new.png differ diff --git a/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/img/uptime-issue-alert-rule.png b/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/img/uptime-issue-alert-rule.png new file mode 100644 index 0000000000000..e5a2bc92d4419 Binary files /dev/null and b/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/img/uptime-issue-alert-rule.png differ diff --git a/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/img/uptime-request-span.png b/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/img/uptime-request-span.png new file mode 100644 index 0000000000000..b103e7671c207 Binary files /dev/null and b/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/img/uptime-request-span.png differ diff --git a/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/index.mdx b/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/index.mdx new file mode 100644 index 0000000000000..9fab7c4cc1e2e --- /dev/null +++ b/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/index.mdx @@ -0,0 +1,67 @@ +--- +title: Uptime Monitoring +sidebar_order: 50 +description: >- + Learn how to help maintain uptime for your web services by monitoring relevant + URLs with Sentry's Uptime Monitoring. +og_image: /og-images/product-uptime-monitoring.png +--- + +Sentry's Uptime Monitoring lets you monitor the availability and reliability of your web services effortlessly. Once enabled, it continuously tracks configured URLs, delivering instant alerts and insights to quickly identify downtime and troubleshoot issues. + +By leveraging [distributed tracing](/concepts/key-terms/tracing/distributed-tracing/), Sentry enables you to pinpoint any errors that occur during an uptime check, simplifying triage and accelerating root cause analysis. This helps you enhance both the reliability and uptime of your web services. + +## Set Up + +Uptime is [automatically configured](/product/new-monitors-and-alerts/monitors/uptime-monitoring/automatic-detection/) as a new alert for the most frequently encountered hostname in all URLs of your error data, ensuring continuous monitoring of your most critical hostname right out of the box. + +You can also [create uptime monitoring alerts](/product/alerts/create-alerts/) for specific URLs. They're fully customizable with request details such as the HTTP method, headers, and body. + +## Uptime Check Criteria + +Our uptime monitoring system verifies the availability of your URLs by performing HTTP requests at regular, pre-configured intervals. For a URL to be considered up and running, the response must meet the following criteria: + +1. **Successful Response (2xx Status Codes):** + The URL must return an HTTP status code in the 200–299 range, indicating a successful request. +2. **Automatic Handling of Redirects (3xx Status Codes):** Sentry will follow redirects for URLs returning an HTTP status code in the 300–399 range and verify that the final destination URL returns a successful response. This ensures that redirects won't falsely trigger downtime alerts. +3. **Timeout Setting:** Each request has a timeout threshold of 10 seconds. + If the server doesn't respond within this period, the check will be marked as a failure, + indicating a potential downtime or performance issues. +4. **DNS Issue Detection:** Our monitoring also includes the detection of DNS resolution issues. + If a DNS issue is detected, the check will be marked as a failure, + allowing you to address the underlying connectivity problems. + +### Uptime Check Failures + +An uptime alert continuously monitors the configured URL with the criteria defined above. If a failure occurs, +a new [uptime issue](/product/issues/issue-details/uptime-issues/) is created, including details about the failed check and related errors. + +To prevent false alerts caused by temporary network issues, **an issue is only generated after three consecutive failures** following the initial detection of downtime. Additionally, uptime checks are performed from a variety of geographical locations in a round-robin fashion. This ensures that each failed check comes from a different region, reducing the likelihood of false positives due to localized network failures. + +_In rare cases where Sentry is unable to perform a scheduled uptime check—such as during outages—the check status will be marked as "Unknown"._ + +## Uptime Request Spans + +Uptime checks include spans called _uptime request spans_ that Sentry automatically creates for the request. The `uptime.request` span acts as a root span for traces related to uptime checks. + +![Uptime request span](./img/uptime-request-span.png) + +**Key Benefits:** + +- Context: You instantly know a trace was generated by an uptime check vs user traffic +- Request lifecycle: You can see the full journey from the initial uptime check through your application's response +- Enhanced debugging: You can see more details about exactly where and why the failure occurred to distinguish between uptime-related issues and other application problems + + +Uptime request spans are free and will not count against your [span quota](/pricing/quotas/manage-transaction-quota/). These spans are always created, even if you have sampling disabled. + + +## Notifications + +To start getting notifications for a new downtime issue, [configure an issue alert](/product/alerts/create-alerts/issue-alert-config/) and choose the issue category "outage". Then choose how you'd like to be notified (via email, Slack, and so on). + +![Uptime issue alert rule configuration](./img/uptime-issue-alert-rule.png) + +## Learn More About Uptime Monitoring + + diff --git a/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/troubleshooting.mdx b/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/troubleshooting.mdx new file mode 100644 index 0000000000000..cddd7009dd8c1 --- /dev/null +++ b/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/troubleshooting.mdx @@ -0,0 +1,27 @@ +--- +title: Troubleshooting +sidebar_order: 53 +description: "Learn how to troubleshoot potential Uptime Monitoring problems." +--- + +## Verify Firewall Configuration + +Some hosting platforms can block incoming requests from Sentry's Uptime Bot, falsely triggering uptime alerts. We recommend verifying your firewall configuration to ensure incoming requests from Sentry are allowed. + +If you need to configure your firewall allowlist to include Sentry's Uptime Bot, we recommend checking against our `User-Agent`, given that our IP addresses can change without notice. + +### User Agent + +Our uptime check requests use the following `User-Agent`: + +``` +SentryUptimeBot/1.0 (+http://docs.sentry.io/product/monitors/uptime-monitoring/) +``` + +### IP Addresses + +See [IP Ranges](/security-legal-pii/security/ip-ranges/#uptime-monitoring) for a complete list of IP addresses used for uptime checks. + +## Verify That Issue Alerts Match Downtime Issues + +Uptime alerts create downtime issues. If you're not receiving notifications when downtimes are detected, make sure you've properly [configured an issue alert](/product/alerts/create-alerts/issue-alert-config/) with the issue category "uptime". diff --git a/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/uptime-tracing.mdx b/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/uptime-tracing.mdx new file mode 100644 index 0000000000000..f2044d9ccecbd --- /dev/null +++ b/docs/product/new-monitors-and-alerts/monitors/uptime-monitoring/uptime-tracing.mdx @@ -0,0 +1,113 @@ +--- +title: Distributed Tracing with Uptime +sidebar_order: 52 +description: Learn how to use distributed tracing to troubleshoot downtime. +og_image: /og-images/product-uptime-monitoring-uptime-tracing.png +--- + +Sentry's Uptime Monitoring uses [distributed tracing](/product/tracing/#whats-distributed-tracing) to track the flow and timing of requests and operations during uptime checks. This helps you quickly find the root cause of downtime by connecting related errors and performance data. + +When uptime checks are performed, Sentry creates a **trace** that shows the complete request lifecycle. This trace contains: + +- **Uptime request spans**: A [default set of root spans](/product/new-monitors-and-alerts/monitors/uptime-monitoring/#uptime-request-spans) that identifies this as an uptime check +- **Application spans**: Individual operations like database queries, API calls, and cache operations, configured through distributed tracing +- **Error events**: Any exceptions or failures that occur during the request + +**Error tracing** captures when things go wrong, while **span tracing** shows the performance and flow of operations. Together, they provide complete visibility into why an uptime check failed. Span tracing is disabled by default for uptime checks, but can be enabled by allowing sampling in your [Uptime Alert settings](/product/alerts/create-alerts/uptime-alert-config/). Errors plus spans focus on problems, while uptime monitoring plus spans focus on performance. + +## How Uptime Tracing Works + +Sentry Uptime Tracing automatically appends a `sentry-trace` header to every outgoing request made to the configured URL in your Uptime Alert settings. This header propagates a trace identifier. + +If one of Sentry's supported backend SDKs is configured for the application handling the incoming uptime check request, the trace will continue through your application. Learn more about [how distributed tracing works](/product/tracing/). + +Example Uptime check request: + +```HTTP +GET /example-uptime-endpoint HTTP/1.1 +Host: sentry.io +User-Agent: SentryUptimeBot/1.0 (+http://docs.sentry.io/product/monitors/uptime-monitoring/) +Sentry-Trace: 32d4011600324838afcd666edadc1d09-8d5ca7419a02ca36 +``` + +## Tracing Errors + +Error tracing is enabled by default for uptime checks. When downtime is detected, an [Uptime Issue](/product/issues/issue-details/uptime-issues/) is created. You can then go to Sentry's [**Trace Explorer**](/product/explore/traces/) page to view any related errors. + +Because uptime requests won't override your SDK’s error sampling rate, some errors may not appear in traces if that rate is set to below 1. + + + To disable error tracing for uptime checks, configure a [before send](/platform-redirect/?next=/configuration/filtering/) filter in your SDK to ignore errors from Sentry's `User-Agent`. Here's an example: + +```typescript {tabTitle: Node.js Express} {filename: instrument.mjs} +import * as Sentry from "@sentry/node"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Filtering example for a Node.js Express app + beforeSend(event) { + const userAgent = event.request?.headers?.["user-agent"]; + + // Ignore events captured in a request from SentryUptimeBot + if (userAgent && userAgent.includes("SentryUptimeBot")) { + return null; + } + + // Process other events + return event; + }, +}); +``` + + + +## Tracing Spans + +There are two sets of spans available for uptime checks: +1. **Uptime request spans**. These are automatically created by Sentry for every uptime check request. You can find them as the root of any uptime issue's trace. +2. **Application spans**. These are spans that are configured through distributed tracing. You can find them as the children of uptime request spans. + +Unlike error tracing, span tracing that you configure is **disabled** by default for uptime checks, but can be enabled by allowing sampling in your [Uptime Alert settings](/product/alerts/create-alerts/uptime-alert-config/). Enabling span tracing can be helpful because it provides a detailed view of the timing and flow of requests and operations during uptime checks, which is especially useful for diagnosing timeouts or performance issues. + +### Enabling Uptime Tracing for Spans + +To enable span tracing, modify your Uptime Alert settings with the "Allow Sampling" option. This will ensure that Sentry defers the sampling decision to your SDK, which will follow the trace sample rate you've configured. + +Because uptime requests won't override your SDK’s error sampling rate, some errors may not appear in traces if that rate is set to below 1. + +![Uptime Alert Allow Sampling Configuration](./img/allow-sampling-new.png) + + + Uptime request spans will always be on, even if sampling is disabled. Uptime request spans are free and will not count against your [span quota](/pricing/quotas/manage-transaction-quota/). + + +### Custom Sampling + +To ensure that all spans from uptime checks are sampled, even if your SDK's trace sampling rate is below 1, you can configure a [sampling function](/platform-redirect/?next=/configuration/sampling/). Here's an example: + +```typescript {tabTitle: Node.js Express} {filename: instrument.mjs} +import * as Sentry from "@sentry/node"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Custom tracer function for a Node.js Express app + tracesSampler: ({ name, attributes, parentSampled }) => { + const userAgent = attributes?.["http.user_agent"]; + + if ( + typeof userAgent === "string" && + userAgent.includes("SentryUptimeBot") + ) { + // Sample 100% of spans from SentryUptimeBot + return 1; + } + + // Sample 50% of other spans + return 0.5; + }, +}); +``` + +## Billing Considerations + +Errors and spans captured during uptime checks are [billed as regular events](https://sentry.io/pricing/) in Sentry. Configure sampling thoughtfully to manage costs. diff --git a/docs/security-legal-pii/security/data-retention-periods.mdx b/docs/security-legal-pii/security/data-retention-periods.mdx index de3e9b0b513cd..be385504a4afc 100644 --- a/docs/security-legal-pii/security/data-retention-periods.mdx +++ b/docs/security-legal-pii/security/data-retention-periods.mdx @@ -14,14 +14,14 @@ By default, new account trials have Team plan retention. If you are trialing fro | Data Type | Developer | Team | Business / Enterprise | |-----------|-----------|------|----------| -| Errors | 30 days | 90 days | 90 days | -| Logs | 30 days | 30 days | 30 days | -| Spans/Transactions | 30 days | 30 days* | 30 days + 13 months sampled* | -| Session Replays | 30 days | 90 days | 90 days | -| Profiles | 30 days | 30 days | 30 days | -| Crons | 30 days | 30 days | 30 days | -| Uptime | 30 days | 90 days | 90 days | -| Attachments | 30 days | 90 days | 90 days | +| [Errors](/concepts/key-terms/enrich-data/) | 30 days | 90 days | 90 days | +| [Logs](/product/explore/logs/) | 30 days | 30 days | 30 days | +| [Spans/Transactions](/concepts/key-terms/tracing/distributed-tracing/) | 30 days | 30 days* | 30 days + 13 months sampled* | +| [Session Replays](/product/explore/session-replay/web/) | 30 days | 90 days | 90 days | +| [Profiles](/product/explore/profiling/) | 30 days | 30 days | 30 days | +| [Crons](/product/monitors/crons/) | 30 days | 30 days | 30 days | +| [Uptime](/product/monitors/uptime-monitoring/) | 30 days | 90 days | 90 days | +| [Attachments](/product/issues/issue-details/attachments/) | 30 days | 90 days | 90 days | **Exception\*:** If you are on a[Team or Business plan](https://sentry.io/settings/billing/overview/) that uses [transaction-based billing](https://docs.sentry.io/pricing/), transactions retention will be 90 days and sampled retention of spans data will not apply. diff --git a/docs/security-legal-pii/security/ip-ranges.mdx b/docs/security-legal-pii/security/ip-ranges.mdx index 48b50cd008829..d4da394eaacf4 100644 --- a/docs/security-legal-pii/security/ip-ranges.mdx +++ b/docs/security-legal-pii/security/ip-ranges.mdx @@ -158,7 +158,7 @@ This endpoint returns a newline-separated list of all current Uptime Monitoring -Uptime Monitoring IP addresses may change over time. If you need to programmatically verify whether a visitor is a Sentry bot, we recommend checking the [user agent](/product/uptime-monitoring/troubleshooting/#user-agent) instead. +Uptime Monitoring IP addresses may change over time. If you need to programmatically verify whether a visitor is a Sentry bot, we recommend checking the [user agent](/product/monitors/uptime-monitoring/troubleshooting/#user-agent) instead.