cw-mutatorctl

NAME

cw-mutatorctl -- Query, create, test, and modify mutators for the cluster.

USAGE

cw-mutatorctl

[-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] MUTATORS | -a | --all] [--reset] [--ensure-defaults] [{list,ls, create,mk, clone,cp, update,up, delete,rm, test, graph}]

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 mutators (default for list).

-i, --ids MUTATORS

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

--reset

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

Alerts 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 mutators. Existing mutators, including custom mutators and edited default mutators, are left unchanged. This option cannot be used with -i, -a, or an action.

Alerts are not changed. After ensuring defaults, the command warns about alerts or mutators that read from a missing mutator.

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 mutators.

-l, --long

Show a subset of all optional information for each mutator.

-L, --long-long

Show all optional information for each mutator.

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

Add a mutator.

Required fields are name, sources, and format. Each source must be an mqtt:<topic> or mutator:<ident> string. The format template must produce valid JSON after its {field} placeholders are replaced.

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

Supported severity values are DEBUG, INFO, WARNING, ERROR, and CRITICAL. severity assigns that value to every message the mutator processes. severity_from_topic=true derives the severity from the MQTT topic, and severity_from_field specifies a dotted path in the message from which to derive severity. severities is a list of severity values that cause the mutator to process a message. min_severity causes the mutator to process only messages at or above the specified severity. Do not specify both severities and min_severity.

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.

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

--content JSON | INI_FILE

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

NAME=VALUE

Set mutator fields from the command line. Use --content for list fields such as sources and for the JSON format template.

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

Copy selected mutators to new identifiers.

--content JSON | INI_FILE

Override fields in the cloned mutators.

NAME=VALUE

Override fields in the cloned mutators. Specify a new name to set the clone name; otherwise, the command generates a name beginning with Copy_of_.

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

Modify fields on selected mutators.

--content JSON | INI_FILE

Override fields on the selected mutators.

NAME=VALUE

Override fields on the selected mutators. Set frozen=true to prevent the mutator from being modified or deleted, or frozen=false to allow changes again.

delete (rm)

Delete selected mutators. A frozen mutator cannot be deleted until it is unfrozen.

test [--message TEXT]

Render each selected mutator's format using a sample message, without changing the mutator or sending an alert. The command prints a JSON object containing the mutator name and rendered result.

--message TEXT

Use a JSON object or plain-text message as placeholder values. If omitted, the command uses sample values for when, topic, and message. A plain-text value supplies the message placeholder.

graph

Show the alerting pipeline as a tree. MQTT topics are roots, mutators that read from them are nested below, and alerts that consume mutators are leaves. Alert leaves include their output type.

With -i, the selected mutator or mutators become roots and only their downstream subtrees are shown. In the human-readable tree, (missing) marks a referenced mutator that does not exist, (see above) marks a node already printed under another parent, and (loop) marks a node already on the current path.

EXAMPLES

cw-mutatorctl list

List all mutators.

cw-mutatorctl create --content @node-event-mutator.json

Create a mutator from a JSON or INI content file.

cw-mutatorctl -i node_event_message clone name=node_event_summary

Clone a mutator with a new name.

cw-mutatorctl -i node_event_message test --message '{"when":"now","name":"node01","message":"offline"}'

Preview the JSON rendered by a mutator using a sample event message.

RETURN VALUES

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