monitoring.alarms.create

Create an alarm on one metric of one resource

POST /monitoring/api/alarmsIAM monitoring:PutMetricAlarmChanges stateDestructive

An alarm goes to ALARM when every one of its evaluation periods breaches, to OK when any does not, and to INSUFFICIENT_DATA when none has data. webhookUrl must be https on a public address. Notifications go out on entering and leaving ALARM.

Request syntax

POST /monitoring/api/alarms
{
  "name": "string",
  "resourceType": "enum",
  "resourceId": "string",
  "metric": "string",
  "dimensions": "map of string",
  "statistic": "enum",
  "comparator": "enum",
  "threshold": "number",
  "periodSeconds": "number",
  "evaluationPeriods": "number",
  "notifyEmails": "array of string",
  "webhookUrl": "string",
  "enabled": "boolean"
}

Request body

  • nameRequired

    string

    Unique in the organization (409 when taken): 1–128 characters, no control characters

  • resourceTypeRequired

    enum

    instance, db_node, vpn_connection, eks_cluster, cdn_distribution, app, or custom: a series the organization publishes itself

    One of: instance, db_node, vpn_connection, eks_cluster, cdn_distribution, app, custom

  • resourceIdRequired

    string

    The resource’s id as resources lists it, 1–64 letters, digits and dashes; 404 when the organization has no such resource. For custom, the series’ namespace (up to 255 characters; the series need not exist yet)

  • metricRequired

    string

    One of cpu_percent, disk_read_iops, disk_write_iops, disk_read_bps, disk_write_bps, network_in_bps, network_out_bps, disk_used_percent, connections, replication_lag_bytes, query_slowdown, docdb_up, tunnel_up, tunnel_in_bps, tunnel_out_bps, bgp_prefixes, api_available, control_plane_ready, nodes_ready, nodes_not_ready, cdn_requests, cdn_cache_hits, cdn_cache_misses, cdn_hit_ratio, cdn_bytes_out, cdn_origin_bytes, waf_blocked, waf_counted, waf_challenged, waf_rate_limited, deploy_duration_seconds, deploys_succeeded, deploys_failed, and one the resource type records (400 otherwise); for custom, the series’ metric name

  • dimensionsOptional

    map of string

    custom only (400 otherwise): the series’ dimensions; none when omitted

    Constraints: key=value

    May be null.

  • statisticOptional

    enum

    avg (default), max, min, sum or count (the number of samples)

    One of: avg, max, min, sum, count

  • comparatorRequired

    enum

    How the period’s statistic is compared with threshold: >, >=, < or <=

    One of: >, >=, <, <=

  • thresholdRequired

    number

    The value the statistic is compared with, in the metric’s unit

  • periodSecondsRequired

    number

    Seconds per evaluated period, a whole number of minutes from 60 to 86400. period × evaluationPeriods may be at most one day. Required over the API; the console’s form starts at 300

    Constraints: integer

  • evaluationPeriodsOptional

    number

    How many periods in a row are evaluated, 1–100; ALARM when every one breaches (default 1)

    Constraints: integer

  • notifyEmailsOptional

    array of string

    Up to 10 addresses, mailed on entering and on leaving ALARM; none by default

  • webhookUrlOptional

    string

    An https URL on a public address, up to 2048 characters, POSTed on entering and on leaving ALARM; none by default

    May be null.

  • enabledOptional

    boolean

    Whether a state change notifies anyone; the alarm is evaluated and its state kept either way (default true)

Response

201 with the new alarm as get describes it, state INSUFFICIENT_DATA until its first evaluation. 409 when the name is taken; 404 when the organization has no such resource; 400 when the resource type does not record the metric.

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow monitoring:PutMetricAlarm on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud monitoring alarms create --name example --resource-type instance --resource-id example --metric example --comparator > --threshold 1 --period-seconds 1

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_monitoring_alarms_create.