Purpose
This guide explains how to prepare a Zabbix server and configure the Zabbix API integration in Logsign USO. The integration pulls two kinds of data from the Zabbix JSON-RPC API: trigger events (the problems you see under Monitoring > Problems, together with their recovery) and the Zabbix audit log (logins, failed logins and configuration changes made in Zabbix).
Each Logsign source collects exactly one of these two streams. If you want both trigger events and audit log records from the same Zabbix server, add two sources that point at the same URL, one per collection type. In practice they usually need different Zabbix users anyway, because the audit log can only be read by a Super admin (see Prerequisites).
Prerequisites
Zabbix version: Zabbix 5.4 or later. Logsign selects the authentication method automatically: on Zabbix 6.4 and later the token is sent in the Authorization: Bearer header, on older releases it is sent in the auth field of the request body. The version is read from apiinfo.version, which Zabbix answers without authentication, so no extra configuration is needed for this.
Network access: the Logsign server must reach the Zabbix frontend over HTTP or HTTPS. All requests go to a single endpoint, <Zabbix frontend URL>/api_jsonrpc.php.
Zabbix user for Trigger Events: a dedicated user with read access to the host groups whose problems you want in Logsign. Zabbix only returns events for hosts the user can read, so a user with no host group permissions will authenticate successfully but collect nothing. If the user's role restricts API methods with an allow list, the list must contain event.get.
Zabbix user for Audit Log: Zabbix restricts auditlog.get to users whose user type is Super admin; this is a Zabbix restriction and cannot be relaxed from the Logsign side. To keep the account as narrow as possible, you can give it a role whose API access is limited with an allow list containing only auditlog.get and whose UI access is disabled. Note that the Zabbix allow list is a single list per role, so a user limited to auditlog.get cannot also be used for the Trigger Events source.
Step 1: Create an API Token in Zabbix
Using an API token is the recommended method. Repeat these steps for each user you created above.
- Sign in to the Zabbix frontend as an administrator.
- Go to Users > API tokens (on Zabbix 5.4 and 6.0 this page is under Administration > General > API tokens) and click Create API token.
- Select the dedicated user, give the token a name such as "Logsign USO", and set an expiry date if your policy requires one. An expired token stops collection until a new one is entered in Logsign.
- Click Add and copy the token value. Zabbix shows it only once.
If you cannot use API tokens, the integration also supports User Login mode. In that mode Logsign calls user.login with the username and password at the start of every polling cycle and calls user.logout at the end, so sessions do not accumulate on the Zabbix side.
Step 2: Configure the Integration in Logsign USO
In Logsign USO, add a new API source and select Zabbix. The form contains the following fields:
| Field | Value |
|---|---|
| Base URL | The Zabbix frontend URL, for example https://zabbix.example.local/zabbix. Do not add api_jsonrpc.php; Logsign appends it. If you do include it, or leave a trailing slash, Logsign still builds the correct address. Include the scheme (https:// or http://). |
| Collection Type | Trigger Events (default) or Audit Log. One source collects one stream. |
| Auth Mode | API Token (default) or User Login. |
| API Token | Shown when Auth Mode is API Token. The token from Step 1. |
| Username / Password | Shown when Auth Mode is User Login. The credentials of the dedicated Zabbix user. |
| Verify SSL | Enabled by default. Disable it only if the Zabbix frontend uses a self-signed certificate that the Logsign server does not trust. |
The common source fields (polling period, EPS, initial lookback and so on) are available as for other API sources. On the first run the integration collects the last 24 hours by default; the initial lookback field can change this up to a maximum of 720 hours (30 days).
What Gets Collected
Trigger Events
The integration reads trigger events with event.get in event ID order and continues from the last event ID it processed, so a restart does not resend history. It produces three kinds of records, identified by Event.Status:
| Event.Status | Meaning | Classification |
|---|---|---|
| PROBLEM | A trigger went into problem state. | System / State / Error |
| RESOLVED | The recovery (OK) event produced by Zabbix. Zabbix does not put the original problem's event ID or severity on this event; its severity is always 0 (Not classified). | System / State / Info |
| CLOSED | A record generated by Logsign when a problem it saw earlier is closed. It carries the original problem's event ID in Event.ID, its severity, and the recovery time in Time.End. | System / State / Info |
Because the CLOSED record has the same Event.ID as the PROBLEM record, it is the one to use when you want to match a closure to the problem that opened it (for example in alert rules or playbooks), and it is also the one to filter on if you need closures above a certain severity. Logsign keeps track of up to 5,000 open problems per source; if more stay open at the same time, the oldest ones are no longer tracked and no CLOSED record is produced for them. Triggers configured in Zabbix with the recovery mode "None" never generate a recovery event, so problems from those triggers never get a RESOLVED or CLOSED record.
The poller does not filter by severity or trigger name. Every trigger event is collected, and you decide which ones should raise an alert through Alert Rules in Logsign, where you can also silence repeating alerts during maintenance windows.
Zabbix severities are converted to Logsign severity names as follows:
| Zabbix severity | Severity.Name in Logsign |
|---|---|
| 5 Disaster | alert |
| 4 High | critical |
| 3 Average | error |
| 2 Warning | warning |
| 1 Information | information |
| 0 Not classified | unknown |
The raw Zabbix number is kept in Event.Severity. Main field mappings for trigger events:
| Zabbix field | Logsign field |
|---|---|
| eventid | Event.ID |
| clock | Time.Generated |
| recovery time (CLOSED only) | Time.End |
| name | Event.Name |
| severity | Event.Severity |
| status (PROBLEM, RESOLVED, CLOSED) | Event.Status |
| r_eventid (recovery event ID) | Event.TrackID |
| objectid (trigger ID) | Rule.ID |
| acknowledged | Event.Result |
| suppressed | Event.Note |
| suppression data (maintenance ID and end time) | Event.AdditionalInformation |
| opdata | Event.Info |
| host (technical name) | Source.HostName |
| host visible name | Device.Name |
| hostid | Device.ID |
tags (as tag=value; ...) | Event.Taxonomy |
Only the first host of an event is mapped. Host groups are not returned by event.get and are not collected.
Audit Log
The integration reads auditlog.get in time order and continues from the timestamp of the last record it processed, skipping records it already sent from the same second. Configuration changes are split into old and new values: for an update, Configuration.Old and Configuration.New both contain the changed paths; for an add, only Configuration.New is filled. Zabbix itself masks secret values such as passwords (******) in these details.
| Zabbix field | Logsign field |
|---|---|
| auditid | Audit.ID |
| clock | Time.Generated |
| username | Source.UserName |
| userid | Source.UserID |
| ip | Source.IP |
| action / action name | Operation.Code / Operation.Name |
| resourcetype / resource type name | Object.Type / Object.Name |
| resourceid | Object.ID |
| resource_cuid | Object.UUID |
| resourcename | Object.Path |
| recordsetid | Event.TrackID |
| details (raw) | Event.ChangeDetails |
Audit records are classified as follows:
| Zabbix action | Classification |
|---|---|
| Login | Identity / User / Login |
| Failed login | Identity / User / Deny |
| Logout | Identity / User / Logout |
| Add, Update, Delete on a user | Identity / User / Add, Modify, Delete |
| Add, Update, Delete on a user role | System / Role / Change |
| Add, Update, Delete on any other object (host, trigger, template, action, settings and so on) | System / Configuration / Change |
| Execute (script) | System / Command / Info |
| History clear | System / Log / Reset |
| Config refresh, Push | System / Configuration / Info |
Actions outside this list are still collected and fall back to the System / State / Info classification.
Notes and Limits
- One stream per source: Trigger Events and Audit Log are separate sources, each with its own position.
- One Zabbix server per source: if you monitor several independent Zabbix installations (for example one per customer), add a source for each of them.
- Paging: records are requested 1,000 at a time with a one second pause between pages, up to 500 pages per polling cycle. Anything left over is collected on the next cycle.
- Timeout: each request waits up to 120 seconds for the Zabbix frontend to answer. Very large first-run windows on a busy server may hit PHP limits on the Zabbix side (
max_execution_time, memory); lower the initial lookback if that happens. - No historical backfill beyond the lookback: events and audit records older than the initial lookback window are not collected.
Troubleshooting
Zabbix returns API errors inside an HTTP 200 response, so most problems do not show up as HTTP error codes. The poller log shows the Zabbix method and the error text, in the form <method> error <code>: <message>.
| Symptom | Likely cause | What to check |
|---|---|---|
Failed to acquire Zabbix API token. | User Login mode could not log in, or the API Token field is empty. | Check the username and password, and that the user is not blocked or disabled in Zabbix. |
... error ...: Not authorized. or Session terminated, re-login, please. | The API token is invalid, expired or disabled, or its user is disabled. | Check the token status and expiry under API tokens in Zabbix and enter a new token in Logsign if needed. |
auditlog.get error ... mentioning permissions | The user is not a Super admin, or the role's API allow list does not include auditlog.get. | Change the user type to Super admin or adjust the role's API method list. |
event.get error ... mentioning permissions | The role's API allow list does not include event.get. | Adjust the role's API method list. |
Source runs without errors but There are no new events. every cycle | The user has no read access to the relevant host groups, or there really were no new events. | Check the user group's host group permissions in Zabbix. |
unexpected status 404 | The Base URL does not point at the Zabbix frontend. | Open <Base URL>/api_jsonrpc.php from the Logsign server; the Base URL should be the address you use to open the Zabbix web interface. |
unexpected status 401 or 403 | A reverse proxy or web server in front of Zabbix is rejecting the request. | Check the web server or proxy access rules for the Logsign server's address. |
request failed with an SSL error | The Zabbix certificate is not trusted by the Logsign server. | Use a trusted certificate, or disable Verify SSL for this source. |
Failed to read Zabbix API version; assuming pre-6.4 auth. | apiinfo.version could not be read, so the token is sent in the request body. Zabbix 7.2 and later no longer accept that, so authentication then fails on those versions. | Make sure the Base URL is correct and reachable; once the version can be read, the correct method is selected automatically. |