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

Docs/specs/syntax

From Zabbix.org
Jump to: navigation, search

These are Zabbix rules regarding element naming, grammar usage etc. Primarily for frontend.

Syntax

  1. Both software and company are consistently referred to with only first letter capitalised like this: Zabbix.
  2. Random words should never be capitalised in the middle of a sentence or label. "Incorrect characters used for host", "Create host" etc should be used.
    1. "Zabbix agent", "Zabbix server", "Zabbix proxy", "Zabbix Java gateway" - note the capitalisation. Also "Zabbix active agent"
    2. Exception : Failure Audit, Success Audit - Windows Eventlog levels which are capitalised like that in original
  3. Names like "host name", "host group", "proxy name", "node name", "template name", "media type", "super admin" should always be written separately
  4. For referencing bytes with a multiplier prefix, KB, MB etc syntax should be used.
  5. For title capitalisation (uppercase/lowercase choices), first and last word should always be capitalised. Other words should be capitalised, except "a", "an", "and", "at", "but", "by", "for", "in", "nor", "of", "on", "or", "out", "so", "the", "to", "up", and "yet" (This rule from Grammar Girl). Such capitalisation should also be followed for value map entries if they are capitalised.

Date and time syntax

This describes date and time syntax, used for the default English locale. Other locales may have their own formats.

  • The time and date ordering always goes from the least precise to more precise units, for example, 2013-12-13 or 04:43:59
  • Single digit time and date values are always prefixed with a zero, for example, 01:02:03
  • open questions : use of text representation for months (Jan instead of 01), omitting units ("2014", "2014/May", 15:04)...

Formatting

  1. Entities (hosts, items, item keys...) should be referenced by enclosing them in double quotes, without additional characters - "like this". (Square brackets are already used for item parameters, asterisks are not commonly used and look confusing)
  2. Main status messages like "Host added" (displayed on green/red background at the top of the page) should never end with a dot. Detail (expandable) messages should always end with a dot.
  3. Detail messages follow the syntax of :
    Action: Object "Object name" on "Host name".
    
    1. Host part is only printed if relevant for the object (for example, it won't be printed for actions and network discovery rules).
    2. Example : "Created: Item "Free memory" on "Database server".
  4. ISO 8601 should be used for all date and time displaying, except graphs (for now). This was unified in ZBX-5430 for Zabbix 2.4. In March 2014, there was a discussion about how the duration is displayed in various locations in the frontend. Current formatting is, for example: 3h 6m. A suggestion was to potentially change it to 03:06:00. This change might have affected duration in trigger/event pages, duration in time period scrollbar and in graph title (formatting must be the same everywhere). It was decided not to change, as it might be confusing as for what this depicts (duration vs absolute time). An idea that was considered - "(Period length: nnnnn)", but that would increase length of various titles/labels. Start-end dates and times also would not be that great as it would be harder to figure out what the period is (think 15:00-23:00).

Referencing

  1. All entities (items, triggers, custom graphs, applications etc) are always referenced by host and entity name.
  2. In user visible messages, comments, documentation etc trigger functions should have empty set of parentheses added after function name, for example, last().

Grammar & style

  1. "Can't" vs "Cannot" - only the expanded form "Cannot" should be used
  2. The user should not be addressed, e.g., "No targets specified" should be used instead of "You did not specify targets"
  3. "checksum" not "check sum"
  4. "No n defined" (as in "No graphs defined") - always plural (not "No graph defined")
  5. "Incorrect parameter" - always "Incorrect parameter[s] for..." (not "Incorrect parameter[s] [is|are] [used] for...")
  6. Use "Acknowledgments" as the name in plural for the function of acknowledging
  7. Keep in mind that some words in English may have irregular formation of plural ("medium" sing. -> "media" pl.). In case of doubt, double check
  8. Macros are "expanded" (not "resolved") - Google search returns ~ 58 million for the first and ~ 18 million for the second.
  9. Trigger relationship is always described using words "dependency" and "dependencies" (not "dependence" and "dependences")
  10. "Minimum" and "maximum" instead of "minimal" and "maximal", e.g. "The minimum value" (note the use of the definite article). "Minimal" would represent a small amount, while "minimum" would represent the smallest possible (and similar for "maximum").
  11. "command line" is used everywhere (instead of "commandline" or "command-line")
  12. "frontend" and "backend" are written together when used as nouns and adjectives (as opposed to "front end" or "front-end").
  13. "non-zero" (as opposed to "nonzero" or "non zero")
  14. "dash" instead of "minus" (except when used in mathematical context)
  15. "dot" instead of "full stop"
  16. "Unix timestamp" - this capitalisation, no extra explanations
  17. "Web" or "web", not "WEB" - it's not an acronym
  18. "Double quote", not "doublequote", when referring to double quotation marks

Naming

General

  1. GUI -> Frontend (easier to translate)
  2. An ID should be referenced by a lowercase object type and a space-separated uppercase string "ID" - for example, "host ID" or "template IDs"

Operations

  1. If an entity is created/deleted, verbs "create" and "delete" should be used
  2. If an entity group membership is modified, verbs "add/remove" (as in "Added to group") should be used
  3. For template operations verbs "link/unlink" should to be used. For example, if templated entities are removed, this action should be called "Unlink and clear" or if it is a separate option - "Clear when unlinking".
  4. what about applications ? what verbs should be used to note item - application changes ? "item linked to application" or a different one ?
  5. Entities are always enabled and disabled (not activated/deactivated).
    1. For action to be performed: Enable/Disable
    2. For state: Enabled/Disabled
Hosts were Monitored/Not monitored. This was changed for Zabbix 2.4 to be consistent to Enabled/Disabled in ZBXNEXT-2270.

Entities

  1. Maps - links instead of connectors
  2. Interval vs Delay
    1. Interval should be used for:
      1. Items in the frontend and XML
      2. Network discovery (currently "Delay")
      3. Action escalations (currently "period", should be "step interval")
      4. Web monitoring (currently "Update interval")
    2. Delay should be used for:
      1. Slideshows
  3. Entity name is always called "Name" (not "Description") - items had "description" up to 2.0
  4. external scripts (config file) or external checks (frontend) ?
  5. "Network discovery" is always referred to as that (not auto-discovery etc)
  6. "Active agent auto-registration" or "Auto-registration"
  7. "Low level discovery"
  8. remote actions -> remote commands
  9. system maps -> network maps (just maps somehow ? how about consistency ?)
  10. frontend scripts ? scripts ? global scripts ?
  11. user alias -> user name
  12. "Metric" should not be used. Either "item" or "value", depending on what it describes
  13. "Inventory", not "profile" (as in "Host inventory") ZBXNEXT-863
  14. nodes - master/slave, parent/child ? zabbix uses all versions randomly - nodes have been removed for 2.4, not relevant anymore
  15. messages being sent out database has "alerts", frontend mostly uses "actions" (Administration -> General -> Housekeeper has Do not keep actions older than (in days), Administration -> Audit has Actions in the dropdown and page header - and there's also Administration -> Notifications... and these also do include remote commands
  16. It should always be clarified what type of an entity something is
    1. Not just "group", but "user group", "host group" etc, except when the group may be both host and template group
    2. "Required field "expression" is missing in icon mapping.", not "Required field "expression" is missing in mapping."
    3. Type may be skipped if the message already implies it, for example, "Icon map "%s" cannot have mapping with empty expression."
  17. Both item keys and trigger functions have "parameters" (not "arguments")
  18. rights or permissions ? permissions seems to be a bit more specific & better
  19. Trigger severity (not priority)
  20. Maps - "icons" instead of "images" for element icons.
  21. users can be 'user', 'admin' and 'superadmin' - currently frontend uses "types" (at least in user properties). possibly "roles", "[access] levels", "classes". in the future might be renamed to "access levels"
  22. screen items/elements/widgets ? same for dashboard
  23. it is suggested to reference specific entities when possible - currently, copying items and triggers calls them "elements"

External names

  1. Instead of just "DB2" use "IBM DB2" because there is also Berkeley DB2 database

API

  1. Objects and returned results have "properties", not "attributes" For example, the "lifetime" property.
  2. When referring to properties of an object, passed as an argument to the API, "parameter" should be used instead of "property" or "option". For example, the "selectTriggers" parameter.


Formatting - Parameters

Often the messages use a reference to the parameters. Currently the following standards can be found:

  • Without a standard for highlight a parameter:
VMware cache statistics. Valid modes are: total, free, pfree, used and pused.
  • Using TAG standard to highlight a parameter: "VMware virtual machine processor usage in Hz, <url> - VMware service URL, <uuid> - VMware virtual machine host name"
  • Using TAG standard to highlight a parameter and possible values:

1. Standard one:

VMware cache statistics. <mode> - total, free, pfree, used and pused.

2. Standard two:

Data cache statistics. Cache - one of values (modes: all, float, uint, str, log, text), history (modes: pfree, total, used, free), trend (modes: pfree, total, used, free), text (modes: pfree, total, used, free).

3. Standard three (with more explanation about parameter but without explanation about possible values):

CPU(s) load. Processor load. The cpu and mode are optional. If cpu is missing all is used. If mode is missing avg1 is used. Note that this is not percentage.

I like to start the discussion about what is the best standard. I think is required maintain 2 standards:

  • Standard to highlight a parameter (without a possible values for params):
<Description Message>, <param 1> - <description of param 1>[, <param N> - <description of param 1>].
  • Standard to highlight a parameter (with a possible values for one or more parameters):
<Description Message>, <param 1> - <description of param 1> (<value1>, <value2>[, <value3>])[, <param N> - <description of param 1>].
i'd say second one can cover all situations - for example
<Description Message>, <param 1> - <description of param 1> [(<value1>, <value2>[, <value3>])][, <param N> - <description of param 1>].
--"richlv@nakts.net" (talk) 14:05, 24 March 2014 (UTC)