.. _trigger_mgmnt:

******************
Trigger management
******************

Clicking the Alerts **Triggers** tab shows a summary of all configured triggers:

.. figure:: /images/c3-alerts-triggers-overview.png
    :width: 600px
    :alt: Populated Triggers page Control Center

Initially, the Triggers page is blank when there aren't any triggers defined yet.

Use the Triggers page to:

- Create a trigger using the **+ New trigger** button.
- View and sort a summary of triggers and their assigned actions.
- Search for a trigger.
- :ref:`Edit <edit_alert_trigger>` or :ref:`delete <delete_alert_trigger>` an 
  existing trigger.

.. _new_edit_trigger_form:

New/Edit Trigger Form
=====================

Use the New Trigger form to define the criteria that will activate 
associated
alert actions. Some of the fields
are already pre-populated when you clicked **Set up an alert** from a 
context menu.

The following component types of triggers can be created:

- :ref:`Broker <broker_triggers>`
- :ref:`Cluster <cluster_triggers>`
- :ref:`Consumer Groups <consumergroup_triggers>`
- :ref:`Topic <topic_triggers>`

.. _broker_triggers:

Broker Triggers
---------------

Use this broker trigger field reference for guidance when adding a 
broker trigger.

.. figure:: /images/c3-alerts-broker-trigger.png
    :width: 600px
    :alt: Broker alert trigger form Control Center

    Broker trigger form


Trigger name
  A unique name used to identify the trigger (for example: Broker fetch request 
  latency).

  .. include:: ../includes/unique-trigger-action-name.rst

Component type
  Select the Broker component type.

Cluster id
  Select a cluster to trigger based on conditions of individual brokers.

  .. include:: ../includes/warn-select1-cluster-trigger.rst

Metric
  Values in Metric are triggered on a per-broker basis.

  .. important:: Any broker that meets the defined Condition will trigger 
     individually.

  Bytes in
    Number of bytes per second produced a broker.

  Bytes out
    Number of bytes per second fetched from a broker (does not account for 
    internal replication traffic).

  .. note::

    Prior to Kafka 0.11.0.0, the ``BytesOutPerSec`` accounted for traffic from 
    the consumer
    and internal replication. This has been changed to only account for consumer 
    traffic for this broker.
    Adjust alerts accordingly.

  Fetch request latency
    .. include:: ../includes/brokerFetchRequestLatency.rst

  Production request count
    Total number of produce requests to a broker (requests per minute).

  Production request latency
    .. include:: ../includes/brokerProductionRequestLatency.rst

Condition
    The trigger will fire when the Condition is true of the comparison between 
    the value of the
    metric being monitored and the value of the Value field. Possible options 
    are **Greater than**,
    **Less than**, **Equal to**, **Not equal to**, **Online**, or **Offline**, 
    depending on
    the selected **Metric**.

Value
  The value to which the broker Metric is compared.

.. _cluster_triggers:

Cluster Triggers
----------------

Use this cluster trigger field reference for guidance when adding a 
cluster trigger.

.. figure:: ../../images/c3-alerts-cluster-trigger.png
    :width: 600px
    :alt: Cluster alert trigger form Control Center

    Cluster trigger form

Trigger name
  A unique name that identifies the trigger (for example: 
  ``Control Center Cluster down``).

  .. include:: ../includes/unique-trigger-action-name.rst

Component type
  Select the Cluster component type.

Cluster id
  Select a cluster to trigger based on a defined condition.

  .. include:: ../includes/warn-select1-cluster-trigger.rst

Metric
  Values in Metric are triggered on a cluster-wide basis. A cluster that meets
  the defined Condition triggers an associated action.

  Cluster down
    A trigger should be created for Condition ``Yes``. 
    See :ref:`c3_cluster_offline`.

  Leader election rate
    .. include:: ../includes/brokerClusterLeaderElection.rst

  Offline topic partitions
    .. include:: ../includes/brokerClusterOfflineTopicPartitions.rst

    A trigger should be created for values ``> 0`` (Greater than zero).

  Unclean election count
    .. include:: ../includes/brokerClusterUncleanCount.rst

    A trigger should be created for values ``!= 0`` (Not equal to zero).

  Under replicated topic partitions
    .. include:: ../includes/brokerClusterUnderReplicated.rst

    A trigger should be created for values ``> 0`` (Greater than zero).

  |zk| status
    Are brokers able to connect to |zk|? 'Offline' / 'Online' are possible 
    values.

  |zk| expiration rate
    .. include:: ../includes/brokerClusterZooKeeperExpires.rst

Condition
    The trigger will fire when the Condition is true of the comparison between 
    the value of the
    metric being monitored and the value of the Value field. Possible options 
    are **Greater than**,
    **Less than**, **Equal to**, **Not equal to**, **Online**, or **Offline**, 
    depending on the selected **Metric**.

Value
  The value to which the cluster Metric is compared.

.. _consumergroup_triggers:

Consumer Group Triggers 
-----------------------

Use this consumer group trigger field reference for guidance when adding a 
consumer group trigger.

.. figure:: /images/c3-alerts-cgroup-trigger.png
    :width: 600px
    :alt: Consumer Group alert trigger form Control Center

    Consumer group trigger form


Trigger name
  A unique name used to identify the trigger (for example: *consumer group name* 
  under consumption).

  .. include:: ../includes/unique-trigger-action-name.rst

Component type
  Should be pre-selected as Consumer group (default type) if the **Set up an alert** button
  was clicked from the Consumer lag page. Otherwise, select Consumer group.

Consumer group name
  The name of the consumer group to monitor for anomalies.

Metric
  The metric to monitor:

  Average latency (ms)
    Average latency of the consumer group in milliseconds.

  Consumer lag
    How far behind consumer applications are while consuming from their producer
    applications. The consumer lag is the difference between the end offset and 
    the current offset. Tracks the opposite of **Consumer lead**.

  Consumer lead
    How far ahead consumer applications are while consuming from producer
    applications. The consumer lead is the difference between the current offset 
    and the beginning offset. For example, a consumer at offset 15 in a partition 
    that starts at offset 0 would have a lead of 15. This alert metric indicates
    when consumption is close to the earliest available messages, which means
    there is *potential* for data loss. Tracks the opposite of **Consumer lag**.

  Consumption difference
    The difference between the expected consumption value and the
    actual consumption value within a given time bin. Typically, there is a gap
    between expected and actual consumption that is very close to real time. 
    This gap should diminish over time.

  Maximum latency (ms)
    Maximum latency of the consumer group in milliseconds.

Buffer (Deprecated)
    The delay behind real time to wait until a time window is considered for 
    triggering. Refer
    to :ref:`buffer_cg_triggers`
    for more information.

Condition
    The trigger will fire when the Condition is true of the comparison between 
    the value of the
    metric being monitored and the value of the Value field. Available options 
    are **Greater than**,
    **Less than**, **Equal to**, or **Not equal to**.

Value
  The value to which the monitored consumer group Metric is compared.

.. _topic_triggers:

Topic Triggers
--------------

Use this topic trigger field reference for guidance when adding a 
topic trigger.

.. figure:: /images/c3-alerts-topic-trigger.png
    :width: 600px
    :alt: Topic alert trigger form Control Center

    Topic trigger form

Trigger name
  A unique name used to identify the trigger (for example: *topic name*
  production requests).

  .. include:: ../includes/unique-trigger-action-name.rst

Component type
  Should be pre-selected as **Topic** if you clicked **Set up an alert** from
  the legacy **System Health > Topics** tab or within another page context menu.
  Otherwise, **Topic** should be selected.

Cluster id
  The trigger for a topic is limited to a specific cluster ID. If you require a 
  topic to be triggered
  by multiple clusters, create independent triggers for each cluster.

Condition
  A select list of options for matching against the value field (below). The 
  name of the topic
  can **Equals**,
  **Begins with**, **Ends with**, or **Contains** a specified value.

  .. note::

    For example, selecting **Contains** and then entering 'topic' into the value
    field will match 'my topic', 'topical', and 'topics with data'. If **Begins 
    with** is selected,
    the trigger will only match
    'topical' and 'topics with data', not 'my topic'.

Topic name
  The name or part of a topic name to be triggered against. Works in conjunction 
  with **Condition**
  to match against one or more topics.

  .. note::

    If multiple topics match against topic name, the trigger will be *per topic*, 
    not an aggregate.
    In the case where there are two topics that **Begin with** 'mytopic'; and 
    the trigger is set
    to ``Bytes in`` for **Metric**, ``Greater than`` for **Condition**, and 
    ``100`` for **Value**,
    any 'mytopic' matches will fire the trigger if they get > 100 **Bytes In**.

  .. warning::

     A message appears when there are greater than five
     topics that match the criteria. Narrow the criteria if you see this message.

Metric
  The value to check for the trigger alert. Possible values are:

  Bytes in
    Amount of bytes per second coming in to a topic.

  Bytes out
    Amount of bytes per second going out from a topic (does not account for 
    internal replication traffic).

  .. note::

    Prior to |ak-tm| 0.11.0.0, the ``BytesOutPerSec`` accounted for traffic from 
    the consumer
    and internal replication. This has been changed to only account for consumer 
    traffic for this topic.
    Adjust alerts accordingly.

  Out of sync replica count
    .. include:: ../includes/topicInSyncReplica.rst

  Production request count
    Amount of production requests per second to a topic in a cluster.

  Under-replicated topic partitions
    Amount of under-replicated topic partitions. A use case for this metric 
    would be
    wanting to know if a Kafka broker crashed while holding a specific topic 
    partition.

Condition
  The trigger will fire when a Condition is true for the comparison between the 
  value of the
  metric being monitored and the value of the Value field. Available options are 
  **Greater than**,
  **Less than**, **Equal to**, or **Not equal to**.

Value
  The value to which the topic Metric is compared.

.. tip:: See :ref:`config_triggers_ex` for step-by-step trigger examples.

.. _edit_alert_trigger:

Edit an alert trigger
=====================

.. first nav step click bell

.. include:: ../includes/alerts-bell-nav.rst

#. Click the **Triggers** tab.

#. Click the name of the trigger.

#. Click **Edit trigger**.

#. Make the changes you want to the trigger fields.

#. Click **Submit**.

.. _delete_alert_trigger:

Delete an alert trigger
=======================

.. first nav step click bell

.. include:: ../includes/alerts-bell-nav.rst

#. Click the **Triggers** tab.

#. Click the name of the trigger.

#. Click **Delete trigger**.

#. Confirm deleting the trigger.