See www.zabbix.com for the official Zabbix site.

Docs/specs/ZBXNEXT-1575

From Zabbix.org
Jump to: navigation, search

Support of internal events

ZBXNEXT-1575

Status: v2.2

Owner: Alexei, Sasha

Reasoning and overview

See https://www.zabbix.org/wiki/Docs/specs/ZBXNEXT-341

Specification (PART 2. Support of internal events)

Summary

Currently there is no easy way to alert users in case if an item becomes unsupported or a trigger goes to unknown state. The new functionality based on internal events should resolve it.

Events

New events will be generated:

  • Trigger goes to 'unknown' state
    • EVENT_SOURCE_INTERNAL, EVENT_OBJECT_TRIGGER, events.objectid = <triggerid>, events.value = TRIGGER_STATE_UNKNOWN
  • Trigger goes back to 'normal' state
    • EVENT_SOURCE_INTERNAL, EVENT_OBJECT_TRIGGER, events.objectid = <triggerid>, events.value = TRIGGER_STATE_NORMAL
  • Item goes to 'not supported' state
    • EVENT_SOURCE_INTERNAL, EVENT_OBJECT_ITEM, events.objectid = <itemid>, events.value = ITEM_STATE_NOTSUPPORTED
  • Item goes back to 'normal' state
    • EVENT_SOURCE_INTERNAL, EVENT_OBJECT_ITEM, events.objectid = <itemid>, events.value = ITEM_STATE_NORMAL
  • Discovery rule goes to 'not supported' state
    • EVENT_SOURCE_INTERNAL, EVENT_OBJECT_LLDRULE, events.objectid = <itemid>, events.value = ITEM_STATE_NOTSUPPORTED
  • Discovery rule goes back to 'normal' state
    • EVENT_SOURCE_INTERNAL, EVENT_OBJECT_LLDRULE, events.objectid = <itemid>, events.value = ITEM_STATE_NORMAL

Database changes

  • Rename existing field triggers.value_flags to triggers.state
  • Rename existing field proxy_history.status to proxy_history.state
    • SQL: update proxy_history set state=ITEM_STATE_NOTSUPPORTED where state=ITEM_STATUS_NOTSUPPORTED
  • New field for table 'items'
    • FIELD |state |t_integer |'0' |NOT NULL |ZBX_SYNC,ZBX_PROXY
    • Supported values: ITEM_STATE_NORMAL (0), ITEM_STATE_NOTSUPPORTED (1)
    • The field will not be indexed
  • Update value of the new field
    • SQL: update items set state=ITEM_STATE_NOTSUPPORTED, status=ITEM_STATUS_ACTIVE where status=ITEM_STATUS_NOTSUPPORTED
  • Modify existing index for table 'events'
    • UNIQUE |1 |source,object,objectid,eventid
  • New field for table 'escalations' (only used for internal item or LLD rule events)
    • FIELD |itemid |t_id | |NULL |0 |-|items
  • Modify existing index for table 'escalations'
    • UNIQUE |1 |actionid,triggerid,itemid,escalationid
  • Add default actions in disabled state to data.sql
    • Report not supported items
      • Default and recovery messages
 Subject: {ITEM.STATE}: {HOST.NAME}:{ITEM.NAME}
 Body:
 Host: {HOST.NAME}
 Item: {ITEM.NAME}
 Key: {ITEM.KEY}
 State: {ITEM.STATE}
      • Conditions
        Event type = Item in "not supported" state
      • Operations
        Send message to user groups: Zabbix administrators via all media
    • Report not supported low level discovery rules
      • Default and recovery messages
 Subject: {LLDRULE.STATE}: {HOST.NAME}:{LLDRULE.NAME}
 Body:
 Host: {HOST.NAME}
 Low level discovery rule: {LLDRULE.NAME}
 Key: {LLDRULE.KEY}
 State: {LLDRULE.STATE}
      • Conditions
        Event type = Low-level discovery rule in "not supported" state
      • Operations
        Send message to user groups: Zabbix administrators via all media
    • Report unknown triggers
      • Default and recovery messages
 Subject: {TRIGGER.STATE}: {TRIGGER.NAME}
 Body:
 Trigger name: {TRIGGER.NAME}
 Expression: {TRIGGER.EXPRESSION}
 State: {TRIGGER.STATE}
      • Conditions
        Event type = Trigger state not supported
      • Operations
        Send message to user groups: Zabbix administrators via all media

Front-end

  • Remove status 'not supported' from item configuration and mass update forms
    • Existing drop-down will be replaced by a new check box: 'Enabled'
  • Configuration -> Items, Configuration -> Discovery rules and item pop ups
    • Possible values for column Status: Disabled, Enabled, Not supported (if Enabled and items.state = ITEM_STATE_NOTSUPPORTED)
  • Configuration -> Items and Configuration -> Discovery rules
    • Click on the status: Disabled -> Enabled/Not supported (depends on items.state, does not change items.state only items.status), Enabled -> Disabled, Not supported -> Disabled
  • Configuration -> Items, Configuration -> Discovery rules and Configuration -> Triggers
    • The error icon must not be displayed if an object is disabled
  • Configuration -> Items
    • The Not supported option must be removed from the Status filter
    • Additional State filter will be added with options Normal and Not supported above the Status filter, pushing Triggers and Template fields down. Only enabled items will be shown when filtering items by state
      • When the "State" filter is set, the "Status" filter will be set to "Enabled" and become disabled. When the "State" filter is unset, the "Status" filter is re-enabled and reset to the previously selected value
      • a "State" subfilter will be added
  • Configuration -> Triggers and trigger pop ups
    • Possible values for column Status: Disabled, Enabled, Unknown (if Enabled and trigger.state = TRIGGER_STATE_UNKNOWN)
    • Status switching logic is the same as with items
  • Host import and export
    • When importing an item with status=3, the status must be set to 0
    • The state property must not be exported
  • An action could be defined for event source 'Internal'
    • Tab Action: same as for Source=Trigger events
      • Default and recovery messages will be empty
    • Tab Conditions: Type of calculation, Conditions, New condition (Host group =/<>, Application =/like/not like, Host, Host template, Event type=Item in "not supported" state/Item in "normal" state/Low-level discovery rule in "not supported" state/Low-level discovery rule in "normal" state/Trigger in "unknown" state/Trigger in "normal" state, Node =/<>)
    • Tab Operations: same as for Source=Trigger, except:
      • No Operation type (only send message is allowed)
      • No Conditions
  • Constant ITEM_STATUS_NOTSUPPORTED should be removed
  • Administration -> Audit -> actions should contain actions generated by the internal events
  • TRIGGER_VALUE_FLAG_* should be renamed to TRIGGER_STATE_*
  • Disabling a trigger, host or item must not change the state and the error of triggers

API

action
  • the operation condition object must support an additional conditiontype value: 23 - CONDITION_TYPE_EVENT_TYPE
  • The event type condition supports only the "=" operator
  • The event type condition supports the following values:
    0 - EVENT_TYPE_ITEM_NOTSUPPORTED
    1 - EVENT_TYPE_ITEM_NORMAL
    2 - EVENT_TYPE_LLDRULE_NOTSUPPORTED
    3 - EVENT_TYPE_LLDRULE_NORMAL
    4 - EVENT_TYPE_TRIGGER_UNKNOWN
    5 - EVENT_TYPE_TRIGGER_NORMAL
alert

The alert API must correctly handle alerts generated by events from various sources and objects.

alert.get

  • the eventsource and eventobject parameters must be implemented and work the same way as event.get source and object parameters
  • permissions must be correctly checked for alerts generated by item and LLD rule events
  • the groupids, hostids and selectHosts parameters must work with events generated by items and LLD rules
event
  • new source parameter value: EVENT_SOURCE_INTERNAL
  • new object parameter values: EVENT_OBJECT_ITEM and EVENT_OBJECT_LLDRULE

event.get

  • the source and object parameters must accept only one value
  • the source and object parameters must default to EVENT_SOURCE_TRIGGERS and EVENT_OBJECT_TRIGGER respectfully.
  • the source parameter must be validated. If it's incorrect, an error should be triggered:

Incorrect source value..

  • the source and object parameters must match, otherwise and error must be triggered. The error message text must be:

Incorrect object "%object%" (%objectName%) for source "%source%" (%sourceName%), only the following objects are supported: %supportedObjects%.

  • For example:

"Incorrect object "0" (trigger) for source "1" (discovery), only the following objects are supported: 1 - discovered host, 2 - discovered service."

  • The following object values are possible for each source value:
    • EVENT_SOURCE_TRIGGERS: EVENT_OBJECT_TRIGGER
    • EVENT_SOURCE_DISCOVERY: EVENT_OBJECT_DHOST and EVENT_OBJECT_DHOST
    • EVENT_SOURCE_AUTO_REGISTRATION: EVENT_OBJECT_AUTOREGHOST
    • EVENT_SOURCE_INTERNAL: EVENT_OBJECT_TRIGGER, EVENT_OBJECT_ITEM and EVENT_OBJECT_LLDRULE
  • event.get should always use column 'source' to take advantage of the new index
  • the objectids parameter will be implemented to filter events by the objects that triggered them; the triggerids parameter will be deprecated
  • the hostids, groupids and selectHosts parameters must also work for events generated by items and LLD rules.
  • the selectRelatedObject parameter will be implemented to retrieve the object that generated the event. It must return a single object, not an array. The selectItems and selectTriggers parameters will be deprecated.

event.acknowledge

  • Only trigger events can be acknowledged.
  • If we try to acknowledge a non-trigger event, an error must be triggered:

Only trigger events can be acknowledged.

item and discoveryrule
  • value 3 (not supported) for property status is dropped
  • new property state; readonly, supported values: 0 - (default) normal, 1 - not supported
trigger
  • the value_flag is renamed to state
  • value_flag must rename as a deprecated alias and be supported in trigger.get (if being requested specifically or using extend), create and update methods. Requesting the parameter in trigger.get or using in create or update must trigger a deprecated error in the frontend.
  • the state and value are read-only attributes, not for update
  • trigger.create must set the state to TRIGGER_STATE_NORMAL, value to TRIGGER_VALUE_FALSE and leave error empty

Server and Proxy

  • Server should process new action conditions
  • Constant ITEM_STATUS_NOTSUPPORTED should be removed
  • Housekeeper will remove internal events same way it removes other events
  • Server will process items.state modified by server or proxy
  • Server will send item status to the proxy (config sync) using existing logic
  • Server will not send items.state to proxies
  • New macros will be supported for notifications
    • {ITEM.STATE<1-9>} - Normal, Not supported
      • can be used for item- and trigger-based internal events
    • {LLDRULE.ID}, {LLDRULE.NAME}, {LLDRULE.DESCRIPTION}, {LLDRULE.KEY}, {LLDRULE.STATE} - Normal, Not supported
      • can be used only for LLD rule discovery events
    • {TRIGGER.STATE} - Normal, Unknown
      • can be used only for trigger internal events
  • Existing macros supported for notifications based on internal events
    • {DATE}, {ESC.HISTORY}, {EVENT.AGE}, {EVENT.DATE}, {EVENT.ID}, {EVENT.TIME}, {HOST.*} (except HOST.PORT and HOST.ID), {INVENTORY.*}, {NODE.*}, {PROXY.*}, {TIME}, {host:key.func(param)} for all internal events
    • {ITEM.DESCRIPTION}, {ITEM.ID}, {ITEM.KEY}, {ITEM.NAME} only for item- and trigger-based internal events
    • {TRIGGER.*} (except all related to ACK, {TRIGGER.VALUE} and {TRIGGER.STATUS}) only for trigger-based internal events
  • TRIGGER_VALUE_FLAG_* should be renamed to TRIGGER_STATE_*
  • New triggers created by the server must have the state set to TRIGGER_STATE_NORMAL, value to TRIGGER_VALUE_OK and error left empty

Translation strings

  • Item in "not supported" state
  • Item in "normal" state
  • Low-level discovery rule in "not supported" state
  • Low-level discovery rule in "normal" state
  • Trigger in "unknown" state
  • Trigger in "normal" state
  • Normal
  • Incorrect object "%1$s" (%2$s) for source "%3$s" (%4$s), only the following objects are supported: %5$s.
  • Only trigger events can be acknowledged.

Documentation

  • What's new
  • Configuration of actions based on internal events
  • New macros and support of existing macros for actions based on internal events
    • New column 'Internal notifications' in the list of supported macros by location
  • HOWTO send notifications on triggers in unknown state and not supported items
  • API documentation
    • Document event.get, triggers.state
  • Update database structure

Test cases

  • New action condition works as expected
    • It should work for trigger actions only
  • Escalation works fine for the new action condition
  • New functionality must not affect existing functionality (actions, escalations, etc)

Discussed but will not be included

  • Macros for item and trigger error fields
  • Displaying of history of internal events (asked for in ZBXNEXT-2170)

ChangeLog

  • 1.1 database changes: proxy_history.status renamed to proxy_history.state
  • 1.2
    • changed source-object pair validation message
    • added the event.get objectids and selectRelatedObject parameters
  • 1.3
    • replaced multiple new condition types with a single "Event type" condition
    • added the "Node" condition for internal event actions
  • 1.4
    • described unsupported item import handling
    • described the new filters in the item configuration section
  • 1.5
    • The error icon must not be displayed in the configuration if an item, LLD rule or trigger is disabled
    • Disabling a trigger, host or item must not change the state and the error of triggers
  • 1.6
    • The status indicator in the trigger list must also display the "Unknown" status
    • New triggers must have have the state set to TRIGGER_STATE_NORMAL, value to TRIGGER_VALUE_FALSE and error left empty
  • 1.7
    • added a new field "escalations.itemid"
    • updated "escalations_1" index
  • 1.8
    • updated list of supported macros
  • 1.9
    • updated default message (removed unsupported {ITEM.VALUE} macros)
  • 2.0
    • added changes to the alert API
  • 2.1
    • fixed Translation strings, related to the "Event type" condition
  • 2.2
    • specify that only enabled items will be shown when filtering items by state