Mutator Endpoints#

A mutator primitive transforms MQTT event data before the data is included in an alert notification sent from ClusterWareAI ™ to a third-party product, such as Slack, Teams, or email. Use mutators to modify MQTT event messages with the information that the intended recipient needs to understand what occurred or investigate a problem.

Mutators can use MQTT event topics or the output of other mutators as sources. Using other mutators as a source allows multiple transformations to be chained before an alert is delivered. Mutator loops are not allowed.

When issuing requests, the UID field in the URL can be either the actual UID of the primitive or the name of the primitive as given in the name field. For example, a mutator named node_event_message can be referenced through /mutator/node_event_message or /mutator/<UID>.

Data Fields#

Mutator primitives have several fields:

name
   Required: The name of the mutator. Names must start with a letter, not a
   number.

description
   Optional: A text description for the mutator.

sources
   Required: A list of independent input sources. Each source must be of the
   form ``mqtt:<topic>`` or ``mutator:<ident>``.

format
   Required: A substitution template that produces valid JSON after its
   ``{field}`` placeholders are replaced. Consult the documentation for the
   third-party alert target for any target-specific message content or
   formatting requirements.

mute
   Optional: A True/False value that suppresses output from the mutator.
   The default is ``false`` for a newly created mutator. When cloning, the
   clone retains the template mutator's ``mute`` value unless overridden.

mute_until
   Optional: A Unix timestamp at which a timed mute expires. The mutator stays
   muted while ``mute`` is ``true`` and this timestamp is in the future.

mute_for
   Optional: A positive duration such as ``30m``, ``1h``, or ``2d``. It sets
   ``mute`` to ``true`` and calculates ``mute_until`` from the current time.
   ``mute_for`` is not stored.

frozen
   Optional: A True/False indicator that allows admins to block changes to
   the mutator.

Additional Endpoints#

The mutator API provides the following endpoints:

GET /mutators
   Returns a list of all mutators.

POST /mutators
   Creates a mutator.

POST /mutators?template=<MUTATOR>
   Creates a mutator by cloning an existing mutator (by name or UID). The
   request body must include a new ``name`` and can include field overrides,
   such as format.

GET /mutator/<MUTATOR>
   Returns details about a mutator (by name or UID).

PATCH /mutator/<MUTATOR>
   Updates a mutator (by name or UID).

DELETE /mutator/<MUTATOR>
   Deletes a mutator (by name or UID).

Usage Notes#

  • Consult the documentation for the third-party alert target for any target-specific message content or formatting requirements.

  • To end a mute and clear any associated mute_until timestamp, update the mutator with {"mute": false}.

  • Do not send both mute_for and mute_until in the same request.

Example#

Create a mutator that formats node event data for an alert:

curl -X POST https://head1.cluster.local/api/v1/mutators \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     --data '{
       "name":"node_event_message",
       "description":"Format node events for operations notifications.",
       "sources":["mqtt:clusterware/node/event"],
       "format":"{\"when\": \"{when}\", \"message\": \"Node {name}: {message}\"}"
     }'
{"success":true,"data":"341b9947f6e644b78f6d88f5d7f898f4"}

Get mutator details by name:

curl -X GET https://head1.cluster.local/api/v1/mutator/node_event_message \
     -H "Authorization: Bearer <access_token>" | jq
{
  "success": true,
  "data": {
    "name": "node_event_message",
    "description": "Format node events for operations notifications.",
    "sources": ["mqtt:clusterware/node/event"],
    "format": "{\"when\": \"{when}\", \"message\": \"Node {name}: {message}\"}",
    "mute": false,
    "uid": "341b9947f6e644b78f6d88f5d7f898f4"
  }
}

Mute a mutator for 30 minutes:

curl -X PATCH https://head1.cluster.local/api/v1/mutator/node_event_message \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     --data '{"mute_for":"30m"}'
{"success":true}

Create a mutator that uses another mutator as its source:

curl -X POST https://head1.cluster.local/api/v1/mutators \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     --data '{
       "name":"node_event_summary",
       "sources":["mutator:node_event_message"],
       "format":"{\"summary\": \"{message}\"}"
     }'
{"success":true,"data":"a914cfbf1ccf4e9a9fe23921a3ebf7da"}

Clone an existing mutator with a new name:

curl -X POST "https://head1.cluster.local/api/v1/mutators?template=node_event_message" \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     --data '{"name":"node_event_message_email"}'
{"success":true,"data":"c3c4d5e6f70849a0b1c2d3e4f5a6b7c8"}