Zabbix Retention
@acameron17/zabbix-retentionv2026.09.15.1
01README
Zabbix database-growth diagnostics — find what fills the history tables and what retention those items carry, without Zabbix frontend administration access. Read-only. No CLI dependencies: native fetch against the Zabbix JSON-RPC API with an API token stored in a swamp vault.
Authentication
Requires a Zabbix API token with read access, stored in a swamp vault.
Usage
swamp model create @acameron17/zabbix-retention zbx-retention \
--global-arg baseUrl=https://zabbix.example.org \
--global-arg 'apiToken=${{ vault.get("zabbix", "API_TOKEN") }}'
swamp model method run zbx-retention audit_item_retention
swamp model method run zbx-retention get_housekeepingMethods
- audit_item_retention — item history/trends retention across all hosts, grouped by retention period, value type, host, key prefix, and template
- measure_log_volume — which log item keys write the most rows to history_log, with exact counting and whole-table comparison
- sample_log_values — row width in bytes for one key, to turn row counts into disk growth
- get_item_trends — trend data for one item aggregated per day, outliving the history retention window
- get_audit_log — audit log for a window, grouped by resource type, operation, user, and hour
- get_housekeeping — Administration -> Housekeeping settings
02Models
@acameron17/zabbix-retentionv2026.09.15.1zabbix_retention.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| baseUrl | string | Zabbix frontend base URL, e.g. https://zabbix.example.org |
| apiToken | string | Zabbix API token, sent as a Bearer credential (use a vault reference) |
fn audit_item_retention(valueTypes: array, limit: number, buckets: number, topN: number)
Audit item history/trends retention across all hosts. Groups items by retention period, value type, host, key prefix, and template. Use valueTypes to focus on one storage table (2 = log -> history_log).
| Argument | Type | Description |
|---|---|---|
| valueTypes | array | Value types to include: 0=float, 1=character, 2=log, 3=unsigned, 4=text |
| limit | number | Max items to fetch |
| buckets | number | Item-id buckets for the creation-cluster histogram |
| topN | number | Rows to keep per grouping |
fn measure_log_volume(windowHours: number, sampleSize: number, topKeys: number, exact: boolean, tableTotal: boolean, valueType: number, keySearch?: string, idBatch: number, offsetHours: number, itemLimit: number)
Measure which log item keys write the most rows to history_log. In exact mode it counts every item of a key in one history.get countOutput call, so no extrapolation is needed. It also counts the whole table over the same window, which shows how much of the real volume the per-key numbers explain.
| Argument | Type | Description |
|---|---|---|
| windowHours | number | Look-back window in hours |
| sampleSize | number | Items sampled per distinct key. Ignored when exact is true. |
| topKeys | number | Distinct keys to measure |
| exact | boolean | Count all items of a key in one call instead of sampling |
| tableTotal | boolean | Also count the whole table. history_log has no clock-only index, so this forces a partition scan. Leave it off on a busy server: exact mode over every key already covers the table. |
| valueType | number | History value type: 0=float 1=char 2=log 3=uint 4=text |
| keySearch? | string | Only measure keys that contain this substring |
| idBatch | number | Itemids per history.get call in exact mode |
| offsetHours | number | End the window this many hours before now. Use it to count only rows older than a cutoff. |
| itemLimit | number |
fn get_item_trends(key: string, itemid?: string, hostSearch?: string, days: number, divisor: number, unit: string, source: enum)
Read trend data for one item and aggregate it per day. Trends outlive the history retention window, so this can show months of a gauge such as a table size. Use it to tell a real plateau from an API retention clamp.
| Argument | Type | Description |
|---|---|---|
| key | string | Exact item key. Ignored when itemid is set. |
| itemid? | string | Exact itemid. Use it when one key exists on several hosts. |
| hostSearch? | string | Restrict to hosts matching this name. item.get matches hosts by the host param, not by search. |
| days | number | Days of trend data to read |
| divisor | number | Divide raw values by this. Default converts bytes to GiB. |
| unit | string | |
| source | enum | Read hourly trends, or raw history. Use history when trends are empty. |
fn sample_log_values(key: string, sampleItems: number, rowsPerItem: number, rowsPerDayForKey: number, windowHours: number, itemLimit: number)
Sample stored values for one log item key and measure the row width in bytes. Multiply the width by measured rows per day to turn a row count into disk growth. It also reports the earliest sampled timestamp, which shows when the key started to collect.
| Argument | Type | Description |
|---|---|---|
| key | string | Exact item key to sample |
| sampleItems | number | Items sampled for the key |
| rowsPerItem | number | Rows fetched per item |
| rowsPerDayForKey | number | Measured rows per day for this key, from measure_log_volume |
| windowHours | number | |
| itemLimit | number |
fn get_audit_log(timeFrom: number, timeTill: number, resourceTypes?: array, label: string, limit: number, detailLimit: number)
Read the Zabbix audit log for a time window. Groups entries by resource type, operation, user, and hour. Use it to find the configuration change that caused a behaviour shift.
| Argument | Type | Description |
|---|---|---|
| timeFrom | number | Unix timestamp, start of window |
| timeTill | number | Unix timestamp, end of window |
| resourceTypes? | array | Filter by resource type, e.g. 4=item, 13=template, 36=housekeeping, 31=settings |
| label | string | Name for the produced data |
| limit | number | |
| detailLimit | number | Full entries to keep |
fn get_housekeeping()
Read Administration -> Housekeeping settings (history/trends override, retention periods, housekeeping mode).
Resources
retentionAudit(24h)— Item retention audit grouped by history period, value type, host, and key
housekeeping(24h)— Administration -> Housekeeping settings
logVolume(24h)— Measured history_log row volume per item key, sampled and extrapolated
itemTrends(24h)— Trend history for one item, aggregated per day
logSample(24h)— Measured row width for one log item key
auditTrail(24h)— Audit log entries for a time window, grouped by type and user
03Stats
A
100 / 100
Downloads
0
Archive size
28.0 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
04Platforms
05Labels