cw-alertctl

NAME

cw-alertctl -- Query, create, test, and modify alerts for the cluster.

USAGE

cw-alertctl

[-h] [-v] [-q] [[-c | --config] CONFIG] [--base-url URL] [[-u | --user] USER[:PASSWD]] [--human | --json | --csv | --table] [--pretty | --no-pretty] [--fields FIELDS] [--show-uids] [[-i | --ids] ALERTS | -a | --all] [--reset] [--ensure-defaults] [{list,ls, create,mk, clone,cp, update,up, delete,rm, schema, test}]

OPTIONAL ARGUMENTS

-h, --help

Print usage message and exit. Ignore trailing args, parse and ignore preceding args.

-v, --verbose

Increase verbosity.

-q, --quiet

Decrease verbosity.

-c, --config CONFIG

Specify a client configuration file CONFIG.

--show-uids

Do not try to make the output more human readable.

-a, --all

Interact with all alerts (default for list).

-i, --ids ALERTS

A comma-separated list of alerts to query or modify. Values can include name, UID, or truncated UID. This option must be placed before the action.

--reset

Delete all alerts and recreate the default alerts originally created during install. Custom alerts are removed and edits to default alerts are discarded. This option does not run while any alert has frozen=true. It cannot be used with -i, -a, or an action.

Mutators are not changed. After the reset, the command warns about alerts or mutators that read from a missing mutator.

--ensure-defaults

Create any missing default alerts. Existing alerts, including custom alerts and edited default alerts, are left unchanged. This option cannot be used with -i, -a, or an action.

Mutators are not changed. After ensuring defaults, the command warns about alerts or mutators that read from a missing mutator. Use cw-mutatorctl --ensure-defaults to restore missing default mutators.

ARGUMENTS TO OVERRIDE BASIC CONFIGURATION DETAILS

--base-url URL

Specify the base URL of the REST API.

-u, --user USER[:PASSWD]

Masquerade as user USER with optional colon-separated password PASSWD.

FORMATTING ARGUMENTS

--human

Format the output for readability (default).

--json

Format the output as JSON.

--csv

Format the output as CSV.

--table

Format the output as a table.

--pretty

Indent JSON or XML output, and substitute human readable output for other formats.

--no-pretty

Opposite of --pretty.

--fields FIELDS

Select individual fields in the result or error.

ACTIONS

list (ls) [--long | --long-long]

Show information about alerts.

-l, --long

Show a subset of all optional information for each alert.

-L, --long-long

Show all optional information for each alert.

create (mk) [--content JSON | INI_FILE] [NAME=VALUE ...]

Add an alert.

Required fields are name, sources, output, and output_config. The sources field must be a non-empty list of mqtt:<topic> or mutator:<ident> strings. The output field must be a notifiers target such as slack or email. Use cw-alertctl schema to list supported targets and cw-alertctl schema OUTPUT to list the fields accepted by an output_config.

Optional fields include description, severity, severities, min_severity, enabled, mute, mute_until, mute_for, and frozen.

Supported severity values are DEBUG, INFO, WARNING, ERROR, and CRITICAL. severities is a list of severity values that cause the alert to send. min_severity causes the alert to send only for messages at or above the specified severity. Do not specify both severities and min_severity.

mute is true or false. mute_for accepts a positive duration such as 30m, 1h, or 2d; it sets mute to true and calculates mute_until. Do not specify both mute_for and mute_until. mute=false clears a mute and any mute_until timestamp.

Setting frozen=true prevents the alert from being modified or deleted.

--content JSON | INI_FILE

Load content into the database as an alert. Prefix a file path with @, or use @- for standard input. The content may be JSON or an INI file.

NAME=VALUE

Set alert fields from the command line. Use --content for list and object fields such as sources and output_config.

clone (cp) [--content JSON | INI_FILE] [NAME=VALUE ...]

Copy selected alert to a new identifier.

--content JSON | INI_FILE

Override fields in the cloned alert.

NAME=VALUE

Override fields in the cloned alert. Cloning requires a new name.

update (up) [--content JSON | INI_FILE] [NAME=VALUE ...]

Modify fields on selected alerts.

--content JSON | INI_FILE

Override fields on the selected alerts.

NAME=VALUE

Override fields on the selected alerts. Set frozen=true to prevent the alert from being modified or deleted, or frozen=false to allow changes again. Set mute_for=30m for a timed mute, or mute=false to unmute.

delete (rm)

Delete selected alerts. A frozen alert cannot be deleted until it is unfrozen.

schema [--min | --full] [OUTPUT]

List supported alert outputs or show the fields accepted by one output.

--min

Show only the fields required by OUTPUT. This is the default when OUTPUT is specified.

--full

Show the complete JSON schema for OUTPUT.

OUTPUT

Alert output to describe, such as slack or email. Omit OUTPUT to list all supported outputs. Do not use --min or --full without OUTPUT.

test [--message TEXT] [--send] [--force]

Preview or send a sample message through each selected alert output.

--message TEXT

Use this message text instead of the default sample message.

--send

Deliver the message through the alert output. Without --send, the command prints the message and redacted output_config that would be sent.

--force

Allow --send to deliver a test message for more than one selected alert.

EXAMPLES

cw-alertctl list

List all alerts.

cw-alertctl create --content @node-created-alert.json

Create an alert from a JSON or INI content file.

cw-alertctl schema slack

Show the required output_config fields for Slack alerts.

cw-alertctl -i node_created_slack clone name=node_created_critical_slack severity=CRITICAL

Clone an alert and override severity fields on the new alert.

cw-alertctl -i node_created_slack test --message "Slack alert test"

Preview a sample notification with a custom message without sending it.

cw-alertctl -i node_created_slack test --send

Send a test notification through the selected alert output.

RETURN VALUES

Upon successful completion, cw-alertctl returns 0. For operational failures, an error message is printed to stderr and cw-alertctl returns 1. Command line usage errors return 2.