Monitoring & alerts tools
These tools give an AI client access to a server’s real-time performance metrics and the alert rules that watch them. They cover requests like “how loaded is web-01 right now,” “which server is using the most disk I/O,” or “set up an alert for high memory usage on the database servers.”
All tools accept workspace (required) and region (optional, defaults to the configured region). These common parameters are omitted from the tables below.
Summary
| Tool | Description | Access |
|---|---|---|
get_cpu_usage | CPU utilization statistics for a server | Read-only |
get_memory_usage | Memory utilization statistics for a server | Read-only |
get_disk_usage | Disk space usage for a device or partition | Read-only |
get_disk_io | Disk read/write throughput for a server | Read-only |
get_network_traffic | Network bandwidth and packet rates for a server | Read-only |
get_top_servers | Top 5 servers ranked by resource usage | Read-only |
get_server_metrics_summary | Combined CPU, memory, disk, and network overview for a server | Read-only |
list_alerts | Triggered alerts, with filtering | Read-only |
get_alert | Full detail for a single alert | Read-only |
acknowledge_alert | Mark an alert as checked or dismissed | Additive |
get_alert_rules | Configured alert rules and thresholds | Read-only |
create_alert_rule | Create a new alert rule | Additive |
update_alert_rule | Modify an existing alert rule | Idempotent write |
delete_alert_rule | Permanently delete an alert rule | Destructive |
attach_alert_rule | Attach an existing rule to a server | Idempotent write |
detach_alert_rule | Detach a rule from a server | Idempotent write |
get_alert_rule_recipients | Preview who an alert rule would notify, as counts | Read-only |
list_rule_overrides | Per-server departures from a workspace rule, with filtering | Read-only |
get_rule_override | Full detail for a single rule override | Read-only |
create_rule_override | Create a per-server departure from a rule | Additive |
update_rule_override | Modify an existing rule override | Idempotent write |
delete_rule_override | Permanently delete a rule override | Destructive |
Metrics
The five time-series metrics tools (get_cpu_usage, get_memory_usage, get_disk_usage, get_disk_io, get_network_traffic) all accept start_date and end_date in ISO 8601 format (e.g. 2024-01-01T00:00:00Z). When start_date is omitted, it defaults to 24 hours before the current time. end_date is optional; when omitted, no end boundary is sent with the request, and the effective upper bound is determined by the API.
get_cpu_usage
Get CPU utilization metrics for a server over a time range. Returns current, average, min, and max usage percentage, along with a health status derived from the current value.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server ID to get metrics for |
start_date | string | No | Start of the time range, ISO 8601 (e.g. 2024-01-01T00:00:00Z). Defaults to 24 hours ago |
end_date | string | No | End of the time range, ISO 8601 (e.g. 2024-01-02T00:00:00Z) |
Example
“Show me CPU usage for web-01 over the last 24 hours”
The client resolves web-01 to a server ID and returns current, average, min, and max CPU usage with a status (idle, low, moderate, high, or critical).
get_memory_usage
Get RAM utilization metrics for a server over a time range. Returns current, average, min, and max usage percentage, along with a health status. Useful for investigating memory pressure or out-of-memory issues.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server ID to get metrics for |
start_date | string | No | Start of the time range, ISO 8601. Defaults to 24 hours ago |
end_date | string | No | End of the time range, ISO 8601 |
Example
“Is db-02 running low on memory?”
Returns memory usage statistics for the last 24 hours by default, including a status field that flags idle, low, moderate, high, or critical usage.
get_disk_usage
Get disk space usage for a server by device or partition. Returns usage percentage and total, used, and free space in human-readable units. Takes either device or partition; if neither is given, the tool automatically looks up the server’s available devices and uses the first one.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server ID to get metrics for |
device | string | No | Device path (e.g. /dev/sda1). Auto-discovered if omitted and partition is also omitted |
partition | string | No | Partition path (e.g. /) |
start_date | string | No | Start of the time range, ISO 8601. Defaults to 24 hours ago |
end_date | string | No | End of the time range, ISO 8601 |
Example
“How much disk space is left on the root partition of app-03?”
Returns current, average, min, and max usage percentage plus total/used/free space for the resolved device or partition.
get_disk_io
Get disk read/write throughput metrics for a server. Returns peak and average transfer rates per device. Useful for diagnosing storage performance bottlenecks.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server ID to get disk I/O metrics for |
device | string | No | Disk device name (e.g. sda, nvme0n1) |
start_date | string | No | Start of the time range, ISO 8601. Defaults to 24 hours ago |
end_date | string | No | End of the time range, ISO 8601 |
Example
“Check disk I/O on the database server for the last hour”
Returns read/write throughput data points for the requested device and time range.
get_network_traffic
Get network bandwidth and traffic metrics for a server by interface. Returns current, average, and peak values for input/output throughput (bps) and packet rate (pps).
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server ID to get metrics for |
interface | string | No | Network interface (e.g. eth0) |
start_date | string | No | Start of the time range, ISO 8601. Defaults to 24 hours ago |
end_date | string | No | End of the time range, ISO 8601 |
Example
“What’s the network throughput on the load balancer today?”
Returns current, average, and peak input/output bandwidth and packet rates for the server’s interface.
get_top_servers
Get the top 5 servers in a workspace ranked by resource usage over the last 24 hours. Results are capped at 5 servers per metric type—this is not configurable. Supports querying multiple metric types in a single call.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
metric_types | string | No | Comma-separated metric types: cpu, memory, disk_io, traffic. Leave empty to get all four |
Example
“Which servers are using the most CPU and memory right now?”
Calling with metric_types="cpu,memory" returns ranked results for both metrics in one response.
get_server_metrics_summary
Get a comprehensive monitoring overview for a single server, combining CPU, memory, disk, and network data availability into one compact response. Intended as a quick health check or a starting point before drilling into a specific metric with its dedicated tool.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server ID to get metrics for |
hours | integer | No | Hours of history to summarize. Default 24, capped at 168 (one week) |
Example
“Give me a quick health check on web-01”
Returns a summary noting whether CPU, memory, disk, and network data are available for the requested window, with pointers to the dedicated tools for full time-series data.
Alerts
Alert rules define the thresholds that generate alerts; alerts are the individual notifications those rules trigger. get_alert_rules and the CRUD tools below all operate on rules, while list_alerts, get_alert, and acknowledge_alert operate on the alerts a rule has produced. attach_alert_rule and detach_alert_rule connect a rule to the servers it watches; see Rule overrides below for tuning a rule on one server without changing it everywhere.
list_alerts
List alerts for a workspace, optionally filtered by server, status, or acknowledgement/dismissal state. Useful for checking active alerts or reviewing alert history.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | No | Filter by server ID |
status | string | No | Filter by alert status |
acknowledged | boolean | No | Filter by acknowledgement state (false returns active/unacknowledged alerts) |
dismissed | boolean | No | Filter by dismissed state |
page | integer | No | Page number |
page_size | integer | No | Items per page |
Example
“Show me active alerts on the production servers”
Returns alerts filtered to acknowledged=false, so only alerts that haven’t been reviewed yet appear.
get_alert
Get full detail for a specific alert.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
alert_id | string | Yes | Alert ID to retrieve |
Example
“What triggered alert abc-123?”
Returns the full alert record, including the rule and metric values that caused it to fire.
acknowledge_alert
Record an acknowledgement against an alert, marking it as checked (seen) or dismissed (not worth acting on). You get one acknowledgement per user per alert, and it can’t be changed afterward—a second call on the same alert is refused.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
alert_id | string | Yes | Alert ID to acknowledge |
action_type | string | Yes | checked or dismissed |
Example
“Mark that disk space alert as seen, I’ll deal with it later”
The agent calls acknowledge_alert with action_type="checked"; a follow-up list_alerts filtered to acknowledged=false no longer includes it.
get_alert_rules
Get the monitoring alert rules configured for servers in a workspace, optionally filtered to one server.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | No | Filter rules to a specific server |
Example
“What alert rules are configured for the database servers?”
Returns each rule’s full definition: name, target metric, threshold, operator, duration, recovery threshold, no-data window, device, severity, email destination, Slack channel post, and whether it’s the workspace default.
create_alert_rule
Create a workspace-level alert rule that watches one target metric, such as CPU, memory, or disk usage. Authoring a rule needs a paid plan; only one rule per target can be marked as the default. Creating a rule doesn’t attach it to any servers—use attach_alert_rule for that afterward.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Name of the alert rule, unique within the workspace |
target | string | Yes | Target metric to watch (e.g. cpu-usage, memory-usage, disk-usage, or one of the peak/average bandwidth or packet-rate metrics) |
threshold | number | Yes | Value the metric must cross to trigger the alert |
is_default | boolean | No | Make this the default rule for the target, automatically applied to every server registered afterward. Default false |
operator | string | No | Which side of the threshold breaches: gte (default) fires at or above it, lte fires at or below it |
duration_s | integer | No | How long the condition must hold before firing, in seconds. 0 (default) fires on a single breaching sample. A positive value must be at least two collection intervals for the target; shorter is rejected with 400 (metrics_alert_rule_duration_too_short) |
recovery_threshold | number | No | Value the metric must return to before the alert resolves. Omitted, the threshold itself resolves it |
no_data_after_s | integer | No | Raise an alert when no sample arrives for this many seconds |
device | string | No | Narrow the rule to one disk, partition, or network interface. Only accepted for a device-scoped target (disk usage, disk I/O, network); cpu-usage and memory-usage are host-wide and reject it |
severity | string | No | Severity the raised alert carries: critical, warning (default), or info. Only a critical rule can email; critical and warning can post to Slack; info reaches neither, whatever notify_email and notify_slack_channel say |
notify_email | string | No | Who the alert email is addressed to, within the people who can already see the server: all (default), admins, group_members, or none. Only a human caller may set this—a service-token or agent write naming it is refused with 400 (metrics_alert_rule_destination_not_allowed). Takes effect only on a critical-severity rule |
notify_slack_channel | boolean | No | Whether a raise and its resolution post to the workspace’s connected Slack channel. Default true. Same human-only restriction as notify_email. Takes effect at critical and warning severity, not info |
Example
“Alert me if any server’s memory usage goes above 90% for more than 5 minutes”
Creates a rule with target="memory-usage", threshold=90, and duration_s=300 so a brief spike doesn’t fire it. Attach it to the servers that should be watched with a follow-up attach_alert_rule call.
update_alert_rule
Update an existing alert rule. Only the fields included in the call are changed; at least one updatable field must be provided. Use this to adjust a threshold or rename a rule without recreating it.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
rule_id | string | Yes | Alert rule ID to update |
name | string | No | New name |
target | string | No | New target metric |
threshold | number | No | New threshold value |
is_default | boolean | No | Make this the default rule for the target |
operator | string | No | gte fires at or above the threshold, lte fires at or below it |
duration_s | integer | No | How long the condition must hold before firing, in seconds. 0 fires on a single breaching sample. A positive value must be at least two collection intervals for the target; shorter is rejected with 400 (metrics_alert_rule_duration_too_short) |
recovery_threshold | number | No | Value the metric must return to before the alert resolves. Omitted, the threshold itself resolves it |
no_data_after_s | integer | No | Raise an alert when no sample arrives for this many seconds |
device | string | No | Narrow the rule to one disk, partition, or network interface. Only accepted for a device-scoped target |
severity | string | No | Severity the raised alert carries: critical, warning, or info. Only a critical rule can email; critical and warning can post to Slack; info reaches neither, whatever notify_email and notify_slack_channel say |
notify_email | string | No | Who the alert email is addressed to: all, admins, group_members, or none. Same human-only restriction and severity behavior as on create_alert_rule. Omitted, the rule’s current value is left alone |
notify_slack_channel | boolean | No | Whether a raise and its resolution post to the workspace’s connected Slack channel. Same human-only restriction and severity behavior as on create_alert_rule. Omitted, the rule’s current value is left alone |
Example
“Raise the CPU alert threshold for db-02 to 95%”
Updates only threshold on the matching rule, leaving its other fields unchanged.
delete_alert_rule
Permanently delete an alert rule. Use this to remove rules that are no longer needed.
Access: Destructive
Deleting an alert rule cannot be undone. To stop it watching one server without losing the rule for everyone else, use detach_alert_rule instead. To exempt just one server while the rule keeps running on the rest of the fleet, use create_rule_override with enabled=false instead of detaching or deleting.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
rule_id | string | Yes | Alert rule ID to delete |
Example
“Delete the old disk space alert rule for the decommissioned server”
Removes the rule permanently; it stops evaluating and generating alerts immediately.
attach_alert_rule
Attach an existing alert rule to a server so the rule starts watching it. Use this after create_alert_rule to put a newly created rule to work—creating a rule doesn’t attach it to anything. Attaching a rule that’s already attached to the server succeeds without changing anything, so it’s safe to retry.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server the rule should watch |
rule_id | string | Yes | Alert rule to attach |
Example
“Watch the new memory alert rule on web-01, web-02, and web-03”
The agent calls attach_alert_rule once per server with the rule’s ID.
detach_alert_rule
Detach an alert rule from a server so the rule stops watching it, without deleting the rule itself—it keeps watching every other server it’s attached to. Detaching a rule that was never attached to the server succeeds without changing anything.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server to stop watching |
rule_id | string | Yes | Alert rule to detach |
Example
“Stop the CPU alert rule from watching db-02, but leave it running everywhere else”
The agent calls detach_alert_rule with db-02’s server ID and the rule’s ID; the rule keeps evaluating on every other attached server.
get_alert_rule_recipients
Preview who an alert rule would notify, as counts—never names—without waiting for it to actually fire.
Requires alpacon-server 2.36.0 or later.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
rule_id | string | Yes | Alert rule ID to preview |
Example
“How many people would hear about it if the CPU alert on db-02 fired right now?”
Returns email (mode echoing notify_email, count, and reasons broken down by admins/group_members/owner—these overlap and don’t have to sum to count), slack_channel (enabled echoing notify_slack_channel, connected for whether the workspace has a usable Slack installation), and event_subscriptions (machine listeners, unaffected by either destination). email.count is 0 for a warning- or info-severity rule regardless of notify_email—only a critical rule mails directly—and slack_channel.enabled/.connected stay as configured even for an info-severity rule, which posts nowhere either way.
Counted only over the servers the rule is attached to that you can see and that it can actually fire on. A 404 while the rule itself reads fine through get_alert_rules means every one of its servers is outside what you can see, not that the rule is gone; a rule attached to no server answers zeros instead.
Rule overrides
A rule override is a per-server departure from a workspace alert rule: a different threshold, recovery threshold, or duration for one server, or an outright exemption. Each field left unset on an override keeps the rule’s own value for that server—an override only overrides what you give it. A server can carry at most one override per rule; creating a second for the same pair is refused.
Rule overrides are a variant of the underlying rule for one server, not a substitute for attach_alert_rule/detach_alert_rule. The rule still has to be attached to the server for either the rule or its override to evaluate.
list_rule_overrides
List the rule overrides configured in a workspace. Filter by server, rule, or enabled state to audit which servers depart from a workspace rule.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | No | Filter to overrides on this server |
rule_id | string | No | Filter to overrides on this rule |
enabled | boolean | No | Filter by the override’s enabled state; false is a whole-rule exemption for that server |
page | integer | No | Page number |
page_size | integer | No | Items per page |
Example
“Which servers have a different CPU alert threshold than the rest of the fleet?”
The agent calls list_rule_overrides with rule_id set to the CPU rule’s ID and reviews each override’s threshold.
get_rule_override
Get full detail for a single rule override.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
override_id | string | Yes | Rule override ID to retrieve |
Example
“Show me the override that’s exempting db-02 from the disk alert”
The agent calls get_rule_override with the override’s ID and reports its server, rule, and which fields it changes.
create_rule_override
Create a per-server departure from a workspace alert rule: replace the threshold, recovery_threshold, or duration_s for one server, or set enabled=false to exempt the server from the rule entirely regardless of the other fields.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server the override applies to |
rule_id | string | Yes | Alert rule being overridden |
threshold | number | No | Replace the rule’s threshold for this server; unset keeps the rule’s value |
recovery_threshold | number | No | Replace the rule’s recovery threshold for this server; unset keeps the rule’s value |
duration_s | integer | No | Replace the rule’s duration for this server, in seconds; unset keeps the rule’s value, 0 fires on a single breaching sample |
enabled | boolean | No | false exempts this server from the rule entirely, whatever the other fields hold. Default true, matching the rule |
Example
“The staging database is noisier than production—raise its CPU alert threshold to 95% without touching the rule everywhere else”
The agent calls create_rule_override with server_id set to the staging database, rule_id set to the CPU rule, and threshold=95.
update_rule_override
Update an existing rule override. Only the fields you pass are sent; an omitted field keeps its current value on the override rather than reverting to the rule’s own value.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
override_id | string | Yes | Rule override ID to update |
server_id | string | No | Move the override to a different server |
rule_id | string | No | Move the override to a different alert rule |
threshold | number | No | New threshold override |
recovery_threshold | number | No | New recovery threshold override |
duration_s | integer | No | New duration override, in seconds |
enabled | boolean | No | false exempts this server from the rule entirely |
A server can carry at most one override per rule. Moving an override onto a (server_id, rule_id) pair that already has one fails—delete the existing override first, or update it directly instead of moving this one onto it.
Example
“That staging override’s threshold is still too sensitive—push it to 98%”
The agent calls update_rule_override with the override’s ID and threshold=98, leaving recovery_threshold, duration_s, and enabled as they were.
There’s no way to clear a single overridden field back to the rule’s own value through update_rule_override—an omitted field keeps its current value on the override. To fully remove a departure, use delete_rule_override instead.
delete_rule_override
Permanently delete a rule override, returning that server to the workspace rule’s own values.
Access: Destructive
Deletion is permanent. The server immediately starts evaluating the workspace rule’s own threshold and settings again.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
override_id | string | Yes | Rule override ID to delete |
Example
“Remove the CPU threshold override for the staging database, it should follow the fleet rule now”
The agent finds the override with list_rule_overrides, then calls delete_rule_override with its ID.