Create a monitor

POST {{baseUrl}}/api/v1/monitor

Create a monitor using the specified options.

Monitor Types

The type of monitor chosen from:

• anomaly: query alert
• APM: query alert or trace-analytics alert
• composite: composite
• custom: service check
• event: event alert
• forecast: query alert
• host: service check
• integration: query alert or service check
• live process: process alert
• logs: log alert
• metric: query alert
• network: service check
• outlier: query alert
• process: service check
• rum: rum alert
• SLO: slo alert
• watchdog: event alert
• event-v2: event-v2 alert
• audit: audit alert
• error-tracking: error-tracking alert
• database-monitoring: database-monitoring alert

Note: Synthetic monitors are created through the Synthetics API. See the Synthetics API documentation for more information.

Query Types

Metric Alert Query

Example: time_aggr(time_window):space_aggr:metric{tags} [by {key}] operator #

• time_aggr: avg, sum, max, min, change, or pct_change
• time_window: last_#m (with # between 1 and 10080 depending on the monitor type) or last_#h(with # between 1 and 168 depending on the monitor type) or last_1d, or last_1w
• space_aggr: avg, sum, min, or max
• tags: one or more tags (comma-separated), or *
• key: a 'key' in key:value tag syntax; defines a separate alert for each tag in the group (multi-alert)
• operator: <, <=, >, >=, ==, or !=
• #: an integer or decimal number used to set the threshold

If you are using the _change_ or _pct_change_ time aggregator, instead use change_aggr(time_aggr(time_window), timeshift):space_aggr:metric{tags} [by {key}] operator # with:

• change_aggr change, pct_change
• time_aggr avg, sum, max, min Learn more
• time_window last_#m (between 1 and 2880 depending on the monitor type), last_#h (between 1 and 48 depending on the monitor type), or last_#d (1 or 2)
• timeshift #mago (5, 10, 15, or 30), #hago (1, 2, or 4), or 1d_ago

Use this to create an outlier monitor using the following query: avg(last_30m):outliers(avg:system.cpu.user{role:es-events-data} by {host}, 'dbscan', 7) > 0

Service Check Query

Example: "check".over(tags).last(count).by(group).count_by_status()

• check name of the check, for example datadog.agent.up
• tags one or more quoted tags (comma-separated), or *. for example: .over("env:prod", "role:db"); over cannot be blank.
• count must be at greater than or equal to your max threshold (defined in the options). It is limited to 100. For example, if you've specified to notify on 1 critical, 3 ok, and 2 warn statuses, count should be at least 3.
• group must be specified for check monitors. Per-check grouping is already explicitly known for some service checks. For example, Postgres integration monitors are tagged by db, host, and port, and Network monitors by host, instance, and url. See Service Checks documentation for more information.

Event Alert Query

Example: events('sources:nagios status:error,warning priority:normal tags: "string query"').rollup("count").last("1h")"

• event, the event query string:
• string_query free text query to match against event title and text.
• sources event sources (comma-separated).
• status event statuses (comma-separated). Valid options: error, warn, and info.
• priority event priorities (comma-separated). Valid options: low, normal, all.
• host event reporting host (comma-separated).
• tags event tags (comma-separated).
• excluded_tags excluded event tags (comma-separated).
• rollup the stats roll-up method. count is the only supported method now.
• last the timeframe to roll up the counts. Examples: 45m, 4h. Supported timeframes: m, h and d. This value should not exceed 48 hours.

NOTE The Event Alert Query is being deprecated and replaced by the Event V2 Alert Query. For more information, see the Event Migration guide.

Event V2 Alert Query

Example: events(query).rollup(rollup_method[, measure]).last(time_window) operator #

• query The search query - following the Log search syntax.
• rollup_method The stats roll-up method - supports count, avg and cardinality.
• measure For avg and cardinality rollup_method - specify the measure or the facet name you want to use.
• time_window #m (between 1 and 2880), #h (between 1 and 48).
• operator <, <=, >, >=, ==, or !=.
• # an integer or decimal number used to set the threshold.

Process Alert Query

Example: processes(search).over(tags).rollup('count').last(timeframe) operator #

• search free text search string for querying processes. Matching processes match results on the Live Processes page.
• tags one or more tags (comma-separated)
• timeframe the timeframe to roll up the counts. Examples: 10m, 4h. Supported timeframes: s, m, h and d
• operator <, <=, >, >=, ==, or !=
• # an integer or decimal number used to set the threshold

Logs Alert Query

Example: logs(query).index(index_name).rollup(rollup_method[, measure]).last(time_window) operator #

• query The search query - following the Log search syntax.
• index_name For multi-index organizations, the log index in which the request is performed.
• rollup_method The stats roll-up method - supports count, avg and cardinality.
• measure For avg and cardinality rollup_method - specify the measure or the facet name you want to use.
• time_window #m (between 1 and 2880), #h (between 1 and 48).
• operator <, <=, >, >=, ==, or !=.
• # an integer or decimal number used to set the threshold.

Composite Query

Example: 12345 && 67890, where 12345 and 67890 are the IDs of non-composite monitors

• name [required, default = dynamic, based on query]: The name of the alert.
• message [required, default = dynamic, based on query]: A message to include with notifications for this monitor. Email notifications can be sent to specific users by using the same '@username' notation as events.
• tags [optional, default = empty list]: A list of tags to associate with your monitor. When getting all monitor details via the API, use the monitor_tags argument to filter results by these tags. It is only available via the API and isn't visible or editable in the Datadog UI.

SLO Alert Query

Example: error_budget("slo_id").over("time_window") operator #

• slo_id: The alphanumeric SLO ID of the SLO you are configuring the alert for.
• time_window: The time window of the SLO target you wish to alert on. Valid options: 7d, 30d, 90d.
• operator: >= or >

Audit Alert Query

Example: audits(query).rollup(rollup_method[, measure]).last(time_window) operator #

• query The search query - following the Log search syntax.
• rollup_method The stats roll-up method - supports count, avg and cardinality.
• measure For avg and cardinality rollup_method - specify the measure or the facet name you want to use.
• time_window #m (between 1 and 2880), #h (between 1 and 48).
• operator <, <=, >, >=, ==, or !=.
• # an integer or decimal number used to set the threshold.

NOTE Only available on US1-FED and in closed beta on US1, EU, AP1, US3, and US5.

CI Pipelines Alert Query

Example: ci-pipelines(query).rollup(rollup_method[, measure]).last(time_window) operator #

• query The search query - following the Log search syntax.
• rollup_method The stats roll-up method - supports count, avg, and cardinality.
• measure For avg and cardinality rollup_method - specify the measure or the facet name you want to use.
• time_window #m (between 1 and 2880), #h (between 1 and 48).
• operator <, <=, >, >=, ==, or !=.
• # an integer or decimal number used to set the threshold.

NOTE CI Pipeline monitors are in alpha on US1, EU, AP1, US3, and US5.

CI Tests Alert Query

Example: ci-tests(query).rollup(rollup_method[, measure]).last(time_window) operator #

• query The search query - following the Log search syntax.
• rollup_method The stats roll-up method - supports count, avg, and cardinality.
• measure For avg and cardinality rollup_method - specify the measure or the facet name you want to use.
• time_window #m (between 1 and 2880), #h (between 1 and 48).
• operator <, <=, >, >=, ==, or !=.
• # an integer or decimal number used to set the threshold.

NOTE CI Test monitors are available only in closed beta on US1, EU, AP1, US3, and US5.

Error Tracking Alert Query

Example(RUM): error-tracking-rum(query).rollup(rollup_method[, measure]).last(time_window) operator # Example(APM Traces): error-tracking-traces(query).rollup(rollup_method[, measure]).last(time_window) operator #

• query The search query - following the Log search syntax.
• rollup_method The stats roll-up method - supports count, avg, and cardinality.
• measure For avg and cardinality rollup_method - specify the measure or the facet name you want to use.
• time_window #m (between 1 and 2880), #h (between 1 and 48).
• operator <, <=, >, >=, ==, or !=.
• # an integer or decimal number used to set the threshold.

Database Monitoring Alert Query

Example: database-monitoring(query).rollup(rollup_method[, measure]).last(time_window) operator #

• query The search query - following the Log search syntax.
• rollup_method The stats roll-up method - supports count, avg, and cardinality.
• measure For avg and cardinality rollup_method - specify the measure or the facet name you want to use.
• time_window #m (between 1 and 2880), #h (between 1 and 48).
• operator <, <=, >, >=, ==, or !=.
• # an integer or decimal number used to set the threshold.

NOTE Database Monitoring monitors are in alpha on US1.

Request Body

{"message"=>"You may need to add web hosts if this is consistently high.", "name"=>"Bytes received on host0", "options"=>{"no_data_timeframe"=>20, "notify_no_data"=>true}, "query"=>"avg(last_5m):sum:system.net.bytes_rcvd{host:host0} > 100", "tags"=>["app:webserver", "frontend"], "type"=>"query alert"}

HEADERS

RESPONSES

status: OK

{"type":"query alert","query":"avg(last_5m):sum:system.net.bytes_rcvd{host:host0} \u003e 100","created":"1989-12-01T14:28:43.831Z","creator":{"email":"officia sunt","handle":"pariatur","name":"aute do"},"deleted":"2020-10-30T20:46:24.520Z","id":-50675854,"matching_downtimes":[{"id":1625,"end":1412792983,"scope":["env:staging"],"start":1412792983},{"id":1625,"end":1412792983,"scope":["env:staging"],"start":1412792983}],"message":"ullamco incididunt cupidatat","modified":"1981-03-27T05:04:03.098Z","multi":false,"name":"My monitor","options":{"aggregation":{"group_by":"host","metric":"metrics.name","type":"count"},"device_ids":["mobile_small","chrome.tablet"],"enable_logs_sample":false,"enable_samples":false,"escalation_message":"none","evaluation_delay":-52819274,"group_retention_duration":"dolor Lorem qui","groupby_simple_monitor":false,"include_tags":true,"locked":false,"min_failure_duration":0,"min_location_failed":1,"new_group_delay":-94315945,"new_host_delay":300,"no_data_timeframe":-86360342,"notification_preset_name":"show_all","notify_audit":false,"notify_by":["labore dolore","deserunt commodo consectetur"],"notify_no_data":false,"on_missing_data":"resolve","renotify_interval":null,"renotify_occurrences":56355858,"renotify_statuses":["warn","no data"],"require_full_window":false,"scheduling_options":{"evaluation_window":{"day_starts":"04:00","hour_starts":0,"month_starts":1}},"silenced":{"non_6f_":77287100},"synthetics_check_id":"culpa in laborum irure","threshold_windows":{"recovery_window":"culpa cupidatat Lorem ut","trigger_window":"fugiat officia mollit esse quis"},"thresholds":{"critical":-44507487.0891542,"critical_recovery":94365870.17342958,"ok":26645340.31156695,"unknown":-32772943.396166816,"warning":75330874.10211122,"warning_recovery":30665996.226613894},"timeout_h":null,"variables":[{"data_source":"rum","compute":{"aggregation":"avg","interval":60000,"metric":"@duration"},"name":"query_errors","group_by":[{"facet":"status","limit":10,"sort":{"aggregation":"avg","metric":"minim tempor i","order":"desc"}},{"facet":"status","limit":10,"sort":{"aggregation":"avg","metric":"Ut fugiat officia","order":"desc"}}],"indexes":["days-3","days-7"],"search":{"query":"service:query"}},{"data_source":"rum","compute":{"aggregation":"avg","interval":60000,"metric":"@duration"},"name":"query_errors","group_by":[{"facet":"status","limit":10,"sort":{"aggregation":"avg","metric":"do velit","order":"desc"}},{"facet":"status","limit":10,"sort":{"aggregation":"avg","metric":"amet proident anim in","order":"desc"}}],"indexes":["days-3","days-7"],"search":{"query":"service:query"}}]},"overall_state":"Warn","priority":1,"restricted_roles":["enim qui cillum est","quis ut"],"state":{"groups":{"Lorem_1":{"last_nodata_ts":-12653992,"last_notified_ts":-66141067,"last_resolved_ts":5643925,"last_triggered_ts":-6121593,"name":"dolore nulla i","status":"OK"},"nisi_c43":{"last_nodata_ts":-66061060,"last_notified_ts":-86988012,"last_resolved_ts":-39919633,"last_triggered_ts":13467862,"name":"Ut fugiat eiusmod anim","status":"Ignored"},"minim_c":{"last_nodata_ts":6509669,"last_notified_ts":39348490,"last_resolved_ts":13221088,"last_triggered_ts":21889420,"name":"in velit Duis","status":"Alert"}}},"tags":["ex tempor","enim veniam dolore"]}