Observability

Preview — pending review

This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.

Create an alert rule

POST
/scopes/{scopeId}/observability/alert-rules

Creates an alert rule in the project. The rule is evaluated every 60 seconds. Target: a rule watches a SET of instances named by tags -- target = {kind: instance_selector, match: {key: value, ...}}, every pair must match. The set is resolved inside the rule's project AT EVERY EVALUATION, so an instance tagged after the rule was written is evaluated on the next tick with no further action, and an instance whose tag is removed (or which is deleted) leaves the set: an alert it still holds open is resolved once (event reason=target_deleted) and it stops being billed. Each matched instance runs its OWN FIRING/OK cycle, its own forSeconds clock and its own notification, and target.instances reports each one's state. A selector that matches nothing is accepted: the rule is INSUFFICIENT_DATA until something is tagged. Providers: instance_state -- a matched instance FIRES when it has been in the ERROR state for condition.forSeconds and resolves (OK) when it leaves ERROR. metric -- compares a VM metric (condition.metric: CPU %, memory %, disk MB/s and IOPS, network Mbps, packets, errors, drops) aggregated over the window (condition.aggregation: avg default, or max; per disk / NIC the worst device counts -- the highest for gt/gte, the lowest for lt/lte) against condition.comparator + condition.threshold (all three required). A matched instance whose monitoring is OFF is SKIPPED, not refused: it is not evaluated and not billed, and it is counted in target.monitoringDisabledCount. Switching monitoring off on an instance that is FIRING sends its RESOLVED notification once (event reason=monitoring_disabled). Samples from spans monitoring was off are ignored. provider is an open vocabulary. Condition (window + for): windowSeconds is the aggregation window, at least 60, default 300; forSeconds (default 0) is how long the condition must hold before FIRING. Channels: channelIds are notification channels of the SAME project (at most 10); they receive the FIRING and the RESOLVED notification, never a no-data one. Each notification names the instance it is about. Limit and billing: the unit is the rule x MATCHED INSTANCE -- a rule matching 20 instances uses 20 of the project's 50 (operator adjustable) and bills 20 units per hour while it is enabled; firing costs nothing. Exceeding the limit is 409 QUOTA_EXCEEDED. Errors: a channel outside the project is 404; an empty or malformed match is 422. 409 CONFLICT when the Idempotency-Key was already used for a different request (or for a rule since deleted), or when a conflicting create landed concurrently. Idempotency: Idempotency-Key is optional (recommended); replaying the same key with the same body returns 200 with the same rule. RBAC: MANAGE on the observability plane (owner, contributor).

Authorization

bearerToken
headerAuthorizationBearer <token>

An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

Header Parameters

Idempotency-Key?string

Optional; recommended for safe retries. When sent, the same key+body within 24h replays the original result and the same key with a different body is 409 CONFLICT; keys are unique per tenant. When an API token or service-account (bearer) caller omits it, the request is applied once with no replay protection (a retry may apply it again). A console session gets one from the edge.

Formatuuid

Request Body

application/json
  1. body

Create body of an alert rule.

name*string

Display name of the rule.

Match^[^\p{C}\p{Z}\x{10000}-\x{10FFFF}](?:[^\p{C}\p{Zl}\p{Zp}\x{10000}-\x{10FFFF}]*[^\p{C}\p{Z}\x{10000}-\x{10FFFF}])?$
Length1 <= length <= 255
provider*AlertRuleProvider

Signal the rule evaluates. instance_state fires on an instance in ERROR; metric compares a VM metric of an instance with monitoring ON against a threshold. The vocabulary grows.

Value in"instance_state""metric"
target*

The set of resources a rule watches, named by tags. Every key: value pair must match (AND); at least one pair is required -- an empty selector is 422, never "every instance".

condition?

The window + for condition. Omitted values take their defaults (create) or keep their current value (update). metric, comparator and threshold are required for a metric rule and ignored for instance_state.

channelIds?array<string>

Notification channel ids of the same project (default none).

Itemsitems <= 10
enabled?boolean

Whether the rule is evaluated (default true).

Response Body

Idempotent replay of an earlier create.

application/json
  1. response

An alert rule of a project and its current evaluation state.

id*string
name*string
provider*AlertRuleProvider

Signal the rule evaluates. instance_state fires on an instance in ERROR; metric compares a VM metric of an instance with monitoring ON against a threshold. The vocabulary grows.

Value in"instance_state""metric"
target*

A rule's tag selector and what it matches RIGHT NOW. matchedCount is resolved on every read, so it is true the moment an instance is tagged -- before the next evaluation has run -- while instances carries the per-instance state of the last evaluation.

condition*

The effective window + for condition. The metric fields are present only on metric rules.

channelIds*array<string>

Notification channels (same project) that receive FIRING and RESOLVED notifications.

enabled*boolean
state*AlertRuleState

Evaluation state. INSUFFICIENT_DATA before the first evaluation and while the signal has no data (e.g. the target was deleted).

Value in"OK""FIRING""INSUFFICIENT_DATA"
stateSince*string

ISO-8601 time the rule entered its current state.

lastEvaluatedAt*|

ISO-8601 time of the last evaluation; null before the first.

createdAt*string
createdBy*string
updatedAt*string
curl -X POST "https://example.com/scopes/string/observability/alert-rules" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "provider": "instance_state",    "target": {      "kind": "instance_selector",      "match": {        "property1": "string",        "property2": "string"      }    }  }'
{  "id": "string",  "name": "string",  "provider": "instance_state",  "target": {    "kind": "instance_selector",    "match": {      "property1": "string",      "property2": "string"    },    "matchedCount": 0,    "monitoringDisabledCount": 0,    "instances": [      {        "id": "string",        "name": "string",        "state": "OK",        "stateSince": "string",        "lastValue": 0,        "lastEvaluatedAt": "string"      }    ]  },  "condition": {    "metric": "cpu.utilization",    "aggregation": "avg",    "comparator": "gt",    "threshold": 0,    "windowSeconds": 0,    "forSeconds": 0  },  "channelIds": [    "string"  ],  "enabled": true,  "state": "OK",  "stateSince": "string",  "lastEvaluatedAt": "string",  "createdAt": "string",  "createdBy": "string",  "updatedAt": "string"}