Create a Metric Alert Rule for an Organization
Create a new metric alert rule for the given organization.
A metric alert rule is a configuration that defines the conditions for triggering an alert. It specifies the metric type, function, time interval, and threshold values that determine when an alert should be triggered. Metric alert rules are used to monitor and notify you when certain metrics, like error count, latency, or failure rate, cross a predefined threshold. These rules help you proactively identify and address issues in your project.
Metric Alert Rule Types
Below are the types of metric alert rules you can create and the parameter values required to set them up. All other parameters can be customized based on how you want the alert rule to work. Scroll down to Body Parameters for more information. Visit the Alert Types docs for more details on each metric alert rule type.
Number of Errors
eventTypes
: Any oferror
ordefault
.
{
"queryType": 0,
"dataset": "events",
"aggregate": "count()",
"eventTypes": ["error", "default"]
}
Users Experiencing Errors
eventTypes
: Any oferror
ordefault
.
{
"queryType": 0,
"dataset": "events",
"aggregate": "count_unique(user)"
}
Crash Free Session Rate
{
"queryType": 2,
"dataset": "metrics",
"aggregate": "percentage(sessions_crashed, sessions) AS _crash_rate_alert_aggregate"
}
Crash Free User Rate
{
"queryType": 2,
"dataset": "metrics",
"aggregate": "percentage(users_crashed, users) AS _crash_rate_alert_aggregate"
}
Throughput
{
"queryType": 1,
"dataset": "transactions",
"aggregate": "count()"
}
Transaction Duration
dataset
: If a custom percentile is used,dataset
istransactions
. Otherwise,dataset
isgeneric_metrics
.aggregate
: Valid values areavg(transaction.duration)
,p50(transaction.duration)
,p75(transaction.duration)
,p95(transaction.duration)
,p99(transaction.duration)
,p100(transaction.duration)
, andpercentile(transaction.duration,x)
, wherex
is your custom percentile.
{
"queryType": 1,
"dataset": "generic_metrics",
"aggregate": "avg(transaction.duration)"
}
Apdex
aggregate
:apdex(x)
wherex
is the value of the Apdex score.
{
"queryType": 1,
"dataset": "transactions",
"aggregate": "apdex(300)"
}
Failure Rate
{
"queryType": 1,
"dataset": "transactions",
"aggregate": "failure_rate()"
}
Largest Contentful Paint
dataset
: If a custom percentile is used,dataset
istransactions
. Otherwise,dataset
isgeneric_metrics
.aggregate
: Valid values areavg(measurements.lcp)
,p50(measurements.lcp)
,p75(measurements.lcp)
,p95(measurements.lcp)
,p99(measurements.lcp)
,p100(measurements.lcp)
, andpercentile(measurements.lcp,x)
, wherex
is your custom percentile.
{
"queryType": 1,
"dataset": "generic_metrics",
"aggregate": "p50(measurements.lcp)"
}
First Input Delay
dataset
: If a custom percentile is used,dataset
istransactions
. Otherwise,dataset
isgeneric_metrics
.aggregate
: Valid values areavg(measurements.fid)
,p50(measurements.fid)
,p75(measurements.fid)
,p95(measurements.fid)
,p99(measurements.fid)
,p100(measurements.fid)
, andpercentile(measurements.fid,x)
, wherex
is your custom percentile.
{
"queryType": 1,
"dataset": "generic_metrics",
"aggregate": "p100(measurements.fid)"
}
Cumulative Layout Shift
dataset
: If a custom percentile is used,dataset
istransactions
. Otherwise,dataset
isgeneric_metrics
.aggregate
: Valid values areavg(measurements.cls)
,p50(measurements.cls)
,p75(measurements.cls)
,p95(measurements.cls)
,p99(measurements.cls)
,p100(measurements.cls)
, andpercentile(measurements.cls,x)
, wherex
is your custom percentile.
{
"queryType": 1,
"dataset": "transactions",
"aggregate": "percentile(measurements.cls,0.2)"
}
Custom Metric
dataset
: If a custom percentile is used,dataset
istransactions
. Otherwise,dataset
isgeneric_metrics
.aggregate
: Valid values are:avg(x)
, wherex
istransaction.duration
,measurements.cls
,measurements.fcp
,measurements.fid
,measurements.fp
,measurements.lcp
,measurements.ttfb
, ormeasurements.ttfb.requesttime
.p50(x)
, wherex
istransaction.duration
,measurements.cls
,measurements.fcp
,measurements.fid
,measurements.fp
,measurements.lcp
,measurements.ttfb
, ormeasurements.ttfb.requesttime
.p75(x)
, wherex
istransaction.duration
,measurements.cls
,measurements.fcp
,measurements.fid
,measurements.fp
,measurements.lcp
,measurements.ttfb
, ormeasurements.ttfb.requesttime
.p95(x)
, wherex
istransaction.duration
,measurements.cls
,measurements.fcp
,measurements.fid
,measurements.fp
,measurements.lcp
,measurements.ttfb
, ormeasurements.ttfb.requesttime
.p99(x)
, wherex
istransaction.duration
,measurements.cls
,measurements.fcp
,measurements.fid
,measurements.fp
,measurements.lcp
,measurements.ttfb
, ormeasurements.ttfb.requesttime
.p100(x)
, wherex
istransaction.duration
,measurements.cls
,measurements.fcp
,measurements.fid
,measurements.fp
,measurements.lcp
,measurements.ttfb
, ormeasurements.ttfb.requesttime
.percentile(x,y)
, wherex
istransaction.duration
,measurements.cls
,measurements.fcp
,measurements.fid
,measurements.fp
,measurements.lcp
,measurements.ttfb
, ormeasurements.ttfb.requesttime
, andy
is the custom percentile.failure_rate()
apdex(x)
, wherex
is the value of the Apdex score.count()
{
"queryType": 1,
"dataset": "generic_metrics",
"aggregate": "p75(measurements.ttfb)"
}
Path Parameters
organization_slug
(string)REQUIREDThe slug of the organization the resource belongs to.
Body Parameters
name
(string)REQUIREDThe name for the rule, which has a maximimum length of 256 characters.
aggregate
(string)REQUIREDA string representing the aggregate function used in this alert rule. Valid aggregate functions are
count
,count_unique
,percentage
,avg
,apdex
,failure_rate
,p50
,p75
,p95
,p99
,p100
, andpercentile
. See Metric Alert Rule Types for valid configurations.timeWindow
(integer)REQUIREDThe time period to aggregate over.
1
- 1 minute5
- 5 minutes10
- 10 minutes15
- 15 minutes30
- 30 minutes60
- 1 hour120
- 2 hours240
- 4 hours1440
- 24 hours
projects
(array(string))REQUIREDMetric alerts are currently limited to one project. The array should contain a single slug, representing the project to filter by.
query
(string)REQUIREDAn event search query to subscribe to and monitor for alerts. For example, to filter transactions so that only those with status code 400 are included, you could use
"query": "http.status_code:400"
. Use an empty string for no filter.thresholdType
(integer)REQUIREDThe comparison operator for the critical and warning thresholds. The comparison operator for the resolved threshold is automatically set to the opposite operator. When a percentage change threshold is used,
0
is equivalent to "Higher than" and1
is equivalent to "Lower than".0
- Above1
- Below
triggers
(array(undefined))REQUIREDA list of triggers, where each trigger is an object with the following fields:
label
: One ofcritical
orwarning
. Acritical
trigger is always required.alertThreshold
: The value that the subscription needs to reach to trigger the alert rule.actions
: A list of actions that take place when the threshold is met. Set as an empty list if no actions are to take place.
Copiedtriggers: [ { "label": "critical", "alertThreshold": 50, "actions": [ { "type": "slack", "targetType": "specific", "targetIdentifier": "#get-crit", "inputChannelId": 2454362 "integrationId": 653532, } ] }, { "label": "warning", "alertThreshold": 25, "actions": [] } ]
Metric alert rule trigger actions follow the following structure:
type
: The type of trigger action. Valid values areemail
,slack
,msteams
,pagerduty
,sentry_app
,sentry_notification
, andopsgenie
.targetType
: The type of target the notification will be sent to. Valid values arespecific
(targetIdentifier
is a direct reference used by the service, like an email address or a Slack channel ID),user
(targetIdentifier
is a Sentry user ID),team
(targetIdentifier
is a Sentry team ID), andsentry_app
(targetIdentifier
is a SentryApp ID).targetIdentifier
: The ID of the target. This must be an integer for PagerDuty and Sentry apps, and a string for all others. Examples of appropriate values include a Slack channel name (#my-channel
), a user ID, a team ID, a Sentry app ID, etc.inputChannelId
: The ID of the Slack channel. This is only used for the Slack action, and can be used as an alternative to providing thetargetIdentifier
.integrationId
: The integration ID. This is required for every action type excludingemail
andsentry_app.
sentryAppId
: The ID of the Sentry app. This is required whentype
issentry_app
.priority
: The severity of the Pagerduty alert or the priority of the Opsgenie alert (optional). Defaults for Pagerduty arecritical
for critical andwarning
for warning. Defaults for Opsgenie areP1
for critical andP2
for warning.
environment
(string)The name of the environment to filter by. Defaults to all environments.
dataset
(string)The name of the dataset that this query will be executed on. Valid values are
events
,transactions
,metrics
,sessions
, andgeneric-metrics
. Defaults toevents
. See Metric Alert Rule Types for valid configurations.queryType
(integer)The type of query. If no value is provided,
queryType
is set to the default for the specifieddataset.
See Metric Alert Rule Types for valid configurations.0
- event.type:error1
- event.type:transaction2
- None
eventTypes
(array(string))List of event types that this alert will be related to. Valid values are
default
(events captured using Capture Message),error
andtransaction
.comparisonDelta
(integer)An optional int representing the time delta to use as the comparison period, in minutes. Required when using a percentage change threshold ("x%" higher or lower compared to
comparisonDelta
minutes ago). A percentage change threshold cannot be used for Crash Free Session Rate or Crash Free User Rate.resolveThreshold
(number)Optional value that the metric needs to reach to resolve the alert. If no value is provided, this is set automatically based on the lowest severity trigger's
alertThreshold
. For example, if the alert is set to trigger at the warning level when the number of errors is above 50, then the alert would be set to resolve when there are less than 50 errors. IfthresholdType
is0
,resolveThreshold
must be greater than the critical threshold, otherwise, it must be less than the critical threshold.owner
(string)The ID of the team or user that owns the rule.
monitorType
(integer)Monitor type represents whether the alert rule is actively being monitored or is monitored given a specific activation condition.
activationCondition
(integer)Optional int that represents a trigger condition for when to start monitoring
Scopes
<auth_token>
requires one of the following scopes:alert_rule:write
alerts:write
org:admin
org:write
curl https://sentry.io/api/0/organizations/{organization_slug}/alert-rules/ \ -H 'Authorization: Bearer <auth_token>' \ -H 'Content-Type: application/json' \ -d '{}'
{
"id": "177104",
"name": "Apdex % Check",
"organizationId": "4505676595200000",
"queryType": 2,
"dataset": "metrics",
"query": "",
"aggregate": "percentage(sessions_crashed, sessions) AS _crash_rate_alert_aggregate",
"thresholdType": 0,
"resolveThreshold": 80,
"timeWindow": 120,
"environment": null,
"triggers": [
{
"id": "293990",
"alertRuleId": "177104",
"label": "critical",
"thresholdType": 0,
"alertThreshold": 75,
"resolveThreshold": 80,
"dateCreated": "2023-09-25T22:01:28.673305Z",
"actions": [
{
"id": "281887",
"alertRuleTriggerId": "293990",
"type": "email",
"targetType": "team",
"targetIdentifier": "2378589792734981",
"inputChannelId": null,
"integrationId": null,
"sentryAppId": null,
"dateCreated": "2023-09-25T22:01:28.680793Z"
}
]
},
{
"id": "492849",
"alertRuleId": "482923",
"label": "warning",
"thresholdType": 1,
"alertThreshold": 50,
"resolveThreshold": 80,
"dateCreated": "2023-09-25T22:01:28.673305Z",
"actions": []
}
],
"projects": [
"our-project"
],
"owner": "team:4505676595200000",
"originalAlertRuleId": null,
"comparisonDelta": 10080,
"dateModified": "2023-09-25T22:01:28.637506Z",
"dateCreated": "2023-09-25T22:01:28.637514Z",
"createdBy": {
"id": 2837708,
"name": "Jane Doe",
"email": "jane.doe@sentry.io"
},
"monitorType": 0
}