[ZBX-22437] Zabbix v6.0.x documentation issues, part 2 Created: 2023 Mar 01  Updated: 2024 Apr 10  Resolved: 2023 Apr 28

Status: Closed
Project: ZABBIX BUGS AND ISSUES
Component/s: Documentation (D)
Affects Version/s: 6.0.13
Fix Version/s: 6.0.18rc1, 6.4.3rc1, 7.0.0alpha1, 7.0 (plan)

Type: Documentation task Priority: Trivial
Reporter: Constantin Oshmyan Assignee: Arturs Dancis
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Sub-task
depends on ZBX-23960 Zabbix v6.0.x documentation issues, p... Closed
depends on ZBX-24176 Zabbix v6.0.x documentation issues, p... Closed
depends on ZBX-22819 Zabbix v6.0.x documentation issues, p... Closed
part of ZBX-22233 Zabbix v6.0.x documentation issues Closed
Team: Team D
Sprint: Sprint 98 (Mar 2023), Sprint 99 (Apr 2023)
Story Points: 2

 Description   

This is a continuation of ZBX-22233 (it could be great to link it here; unfortunately, I have no such permissions).

During my work on documentation translation, I sometimes run into issues with the original (English) version of documentation.
In most cases they are small: broken links or broken formatting.
Probably, it is inefficient to create a separate ZBX on each of them, so I'll summarize just a lot of details in comments below.
[...]
Just note: I'm writing these comments reading the current version of documentation about Zabbix 6.0.
Probably, some of them (or, maybe, most of them) relates to the later versions, too (6.2 and 6.4); I didn't check that.



 Comments   
Comment by Constantin Oshmyan [ 2023 Mar 01 ]

The "Agent" page

The "Supported platform" section does not list HP-UX and NetBSD.
However, these operating systems are listed here.

The "Red Hat Enterprise Linux" page

The "SELinux configuration" section has the phrase:

In addition, Zabbix provides the zabbix-selinux-policy package as part of source RPM packages for RHEL 8 and RHEL 7.

"RHEL 8" and "RHEL 7" are the links; however, they lead to the same place. The second one (for RHEL 7) should be: (http://repo.zabbix.com/zabbix/6.0/rhel/7/SRPMS/).

The "Item keys specific to agent 2"

This page has the very first sentense:

Zabbix agent 2 supports all item keys supported for Zabbix agent on Unix and Windows.

The words "Unix" and "Windows" are a links to another pages; however, the link under the "Windows" is broken (it seems that some part of link has been duplicated).
Probably, the leading slash is absent at the beginning of this link, so it became relative regarding the current page.

The next paragraph: "See also: Plugins supplied out-of-the-box" also contains broken link: the target page does not have the "#plugins-supplied-out-of-the-box" section.
Probably, the correct section name should be: "#built-in".

The same page, a bit later: descriptions of "ceph.osd.discovery" and "ceph.pool.discovery" metrics both contain a link to discovery of systemd services.
Is it correct?
The same is true for the some metrics later: mongodb.collections.discovery, mongodb.db.discovery, mysql.db.discovery, mysql.replication.discovery, oracle.diskgroups.discovery, oracle.db.discovery, oracle.pdb.discovery, oracle.ts.discovery, oracle.user.info, pgsql.db.age, pgsql.db.bloating_tables, pgsql.db.discovery, pgsql.db.size, pgsql.locks.
Moreover, it's unclear how some of them could be used by LLD (for example, "pgsql.db.size" returning Integer instead of JSON).

The same page, "pgsql.dbstat" metric: descriptions of dependent items "pgsql.dbstat.numbackends" and "pgsql.dbstat.sum.blk_read_time" are the same. It seems that first of them is wrong (result of copy-paste).

Comment by Constantin Oshmyan [ 2023 Mar 01 ]

The "Windows-specific item keys" page

This page has the following sentence:

Two value maps are available Windows service state and Windows service startup type to map a numerical value to a text representation in the Frontend.

However, it's unclear: where they "are". Value maps were global before: Administration -> General; but currently they are a property of the host or template only.
So, probably, there should be a link to the appropriate template(s) here.

The "SNMP traps" page

The section "Configuring Perl trap receiver" has near the end instruction:

configure the receiver, e.g:

The example that followed has a broken formatting (2 lines merged into a single line).

The same is true a bit later in the "Configuring SNMPTT" section, after instruction:

log traps to the trap file which will be read by Zabbix:

The same section, the example for a date/time format is:

date_time_format = %H:%M:%S %Y/%m/%d = [DATE TIME FORMAT]

Probably, the last part of this line ("= [DATE TIME FORMAT]") is not needed (see the example here for this parameter).

The same page, the section "SNMPv3" has this instruction:

To enable accepting SNMPv3 add the following line to snmptrapd.conf:

However, there are 2 line to add; so there should be "the following lines" (with "s" ending for plural).

The same page, the very last example: it's unclear why the value of Zabbix item in this example has a different time and source UDP port comparing to values from the file snmptraps.log.
Probably, there was a copy-paste from a different instances of trap.

Comment by Constantin Oshmyan [ 2023 Mar 01 ]

The "Simple checks" page

Table "Supported simple checks": the key name "net.udp.service[service,<ip>,<port>]" should be emphasized by bold.

The "VMware monitoring item keys" page

This page begins with the "vmware.cl.perfcounter" metric, but it's unclear what is the "performance counter path" parameter.
Other performance counters ("vmware.hv.perfcounter" and "vmware.vm.perfcounter") have a link to Footnote 1 (describing that), but "vmware.cl.perfcounter" has no such link. If these performance counters have the same format, it's reasonable to add the same link to footnote 1 here.

And just note from me as a translator: the table on this page is very big, it's hard to work when a continuous text fragment is so huge.
It could be great to split this table onto several parts (at least, related to a cluster, datastore, hypervisor and virtual machines).
See the "Zabbix agent" page for comparing.

The "Internal checks" page

The table contains metric zabbix[host,,items_unsupported]: comment contains a star ("*") at the end (like it is a footnote), but there is no footnotes on this page.
Probably, just a misprint.

The "SSH checks" page

The beginning of this page has link "See also: Requirements" at the second paragraph.
This link is broken: it point to "(/manual/installation/requirements#server)" page, but this page has no "#server" section. Maybe, it assumed the "#serverproxy" section?

The same section has a note: "Only libssh is supported starting with RHEL 8."
This note is not clear enough; what does it mean? The libssh2 is NOT supported on RHEL 8+? Is it supported on other platforms - SUSE, Ubuntu, FreeBSD, Solaris, etc.?

The same page a bit later: the "Configuration" section has the subsection named "Passphrase authentication".
However, the "passphrase" term is used later: the passphrase could be set to additionally protect the key pair.
In this place speech is about password, so the "password" term is better here than the "passphrase".

The "Trapper items" page

The table here tells that the "Allowed hosts" field can contain IP addresses or hostnames.
However, it's not enough clear what is the "hostname" in this context: is it DNS name? FQDN? Zabbix hostname? Something else?
The example shows the "zabbix.domain" as an allowed value. Does it mean that DNS domains also supported (like *.zabbix.com)?
If it is DNS name, how the macro's {HOST.HOST} and {HOST.NAME} should work here (must they match with the DNS names?)?
Some more detailed explanation is required here.
The same is true for the "Server=" parameter in the agent configuration page and other similar places (for example, the "Allowed hosts" field here).

Comment by Constantin Oshmyan [ 2023 Mar 01 ]

The "JMX monitoring" page

The "Simple attributes" section contains the last sentence starting with:

In this example an object name is "com.example:Type=Hello"

The part of an object name in source code is in the angle brackets, so on the web this part seems like a link; but this link is invalid in any case.
Probably, it's necessary some other formatting here.

A bit later on the same page, the "Other issues" section contains a broken link (the section name "##parameter---quoted-string" contains doubled "#" symbol).

The same page later, section "Using custom endpoint with JBoss EAP 6.4":

  • it will be more readable if all file names and directory names be emphasized by a font (fixed size);
  • the example of file "~/needed_modules.txt" contains the "</pre>" tag at the very end (probably, just a junk);
  • the last command (after text "and then executing the command:") has some issue. It contains the following command:
    find /opt/jboss-eap-6.4 -iname ${i}*.jar -exec cp {} /usr/local/sbin/zabbix_java/lib/ \;
    

    The parameter "{}" in this command should be escaped by some way from the shell (as well as the final semocolon ";"). The easiest ways to do that: use either apostrophes:

    '{}'
    

    or backslashes:

    \{\}
    

    (references: here or here)

Comment by Constantin Oshmyan [ 2023 Mar 01 ]

The "ODBC monitoring" page

In the "Installing unixODBC" and "Installing unixODBC drivers" sections:

Installing [...] on RedHat/Fedora based systems using the yum package manager:

and then example of usage the dnf. So, which package manager is used – yum or dnf?

The "Item configuration in Zabbix frontend" section: description of the "key" parameter has broken link to example.
There is no "#using-dbodbcget" section on that page (probably, there should be "#using-db.odbc.get").

The "HTTP agent" page

The "Overview" section has the broken link to the " known issues" (there is no the "#https-checks" section on that page).

Comment by Constantin Oshmyan [ 2023 Mar 16 ]

The "Script items" page

The "Data collection with parameters" example does not demonstrate the parameters usage: the provided code does not use the parameter in this example ("host" in this case), so it's still unclear how it could be accessed from the JavaScript.

Comment by Constantin Oshmyan [ 2023 Mar 21 ]

The "Loadable modules" page

The last paragraph of this section is:

Upon agent startup it will load the [...number of modules listed...]. It will fail if a module [...set of conditions...].

It's unclear, however, the beginning of the last sentense: what exactly will fail – a separate module or an entire agent?

The same page, a bit later: the code example of dummy module has several misprints in the dummy_echo and dummy_random functions.
Probably, due to some autoreplacing the sequence "->" (a reference to the structure member in the C language) has been replaced by the arrow symbol "" (several times, including comments).

Comment by Marina Generalova [ 2023 Mar 30 ]

Dear constantin.oshmyan, thank you for your impact reporting documentation bugs. Kindly, create a new task for April finds if (or, most likely, when) there are more issues detected - once a month seems to be a good rhythm for such tasks. Meanwhile, we will start working on this one. By the way, most of the ZBX-22233 have been fixed, but I'm keeping that task open because of 3 or 4 issues that still need to be checked. 

Comment by Constantin Oshmyan [ 2023 Mar 30 ]

mgeneralova, Yes, of course. OK. Thank you!

Comment by Brian van Baekel [ 2023 Mar 30 ]

mgeneralova i am wondering, if ctrl+enter or cmd+enter still works for reporting documentation issues? I report them via that way (and do not create tickets) but if ctrl+enter or cmd+enter doesn't work anymore, that is wasted effort and it might be a good idea to have a generic ZBX open to report documentation issues?

Comment by Marina Generalova [ 2023 Mar 30 ]

brian.baekel  typo reports via ctrl/cmd+enter still work (and we are not planning to remove this functionality), please feel free to use whichever option is more convenient to you. 

Comment by Arturs Dancis [ 2023 Apr 28 ]

Thank you for reporting! Documentation updated:

  • Zabbix processes > Agent (7.0, 6.4, 6.0)
  • Installation > Installation from packages > Red Hat Enterprise Linux (7.0, 6.4, 6.0)
  • Configuration > Items > Item types > Zabbix agent > Zabbix agent 2 (7.0, 6.4) / Item keys specific to agent 2 (6.0)
  • Configuration > Items > Item types:
    • Zabbix agent > Windows Zabbix agent (7.0, 6.4) / Windows-specific item keys (6.0)
    • SNMP traps (7.0, 6.4, 6.0, 5.0, 4.0)
  • Configuration > Items > Item types > HTTP agent (7.0, 6.4, 6.0, 5.0, 4.0)
  • Installation > Installation from packages > Windows agent installation from MSI (7.0, 6.4)
  • Appendixes > Process configuration:
  • Configuration > Items > Item types > JMX monitoring (7.0, 6.4, 6.0, 5.0, 4.0)
  • Configuration > Items > Item types > ODBC (7.0, 6.4, 6.0)
  • Configuration > Items > Item types > Script items (7.0, 6.4, 6.0)
  • Extensions > Loadable modules (7.0, 6.4)
  • Configuration > Items > Loadable modules (6.0, 5.0, 4.0)
Comment by Constantin Oshmyan [ 2023 Apr 28 ]

adancis wrote:

Documentation updated: [...]

Thanks, great!

Comment by Constantin Oshmyan [ 2023 May 18 ]

Just some shortcomings:

Moreover, it's unclear how some of them could be used by LLD (for example, "pgsql.db.size" returning Integer instead of JSON).

A description of the "pgsql.db.age" item still has the phrase "Used for low-level discovery", however it returns the Integer value (link).

The "Item configuration in Zabbix frontend" section: description of the "key" parameter has broken link to example.
There is no "#using-dbodbcget" section on that page (probably, there should be "#using-db.odbc.get").

This broken link is not fixed yet.

Comment by Arturs Dancis [ 2023 May 19 ]

Thank you for pointing out the shortcomings! Documentation updated:

  • Configuration > Items > Item types:
    • ODBC monitoring (7.0, 6.4, 6.0, 5.0)
    • Zabbix agent > Zabbix agent 2 (7.0, 6.4), Item keys specific to agent 2 (6.0)
Generated at Wed Apr 16 07:34:47 EEST 2025 using Jira 9.12.4#9120004-sha1:625303b708afdb767e17cb2838290c41888e9ff0.