IPAM Datasets
IPAM datasets define what an IPAM device writes from its sweep of one IPv4 subnet (dataset type ipam). They attach to devices of type ipam, and in
Collector Types
There are two datasets, one per data model, each with its own definition id, event.dataset (ipam.<dataset>), and pipeline. Both are written from the device's one sweep: assigning both does not sweep the subnet twice.
| Dataset (console title) | Dataset | Definition | Definition id | Kind | Default interval | Minimum |
|---|---|---|---|---|---|---|
| IPAM Addresses | address | ipam_address_collector | 13100 | inventory | 300 s | 60 s |
| IPAM Usage | usage | ipam_usage_collector | 13150 | metric | 300 s | 60 s |
Every dataset takes these properties:
| Field | Required | Type | Default | Description |
|---|---|---|---|---|
interval | N | int | 300 | Seconds between readings. At least 60. |
pipeline_name | N | string | the device's | The preprocessing pipeline the dataset's records enter. |
Rules
- One sweep, one interval. The device reads at the shortest interval among the datasets assigned to it, since both are written from the same readings.
- Intervals. An interval under the minimum, or not a whole number, is left out with a warning in the device's log, and the device's other dataset runs.
- One of each. A dataset assigned twice is read once. The first assignment decides its settings.
- Failures stay apart. Address records that could not all be written hold the sweep back: the next reading sweeps those addresses again. A usage record that could not be written is kept and written at the next reading.
Records
Every record is one ECS 8.11 document:
event.moduleisipam, andevent.datasetisipam.addressoripam.usage.- The sweep is described under
observer.*:observer.vendor(VirtualMetric),observer.product(IPAM),observer.name(the device), andobserver.hostname(the Director it ran on, since what answers depends on where the sweep is made from). ipam.subnet(192.0.2.0/24) andnetwork.type(ipv4) are on every record.- Durations are whole microseconds (
{"us": 412}), and a share is a fraction of 1. A value that was not measured is left out, never written as zero.
Addresses
address writes one record per address that answers, at every reading that sweeps it, dated when the reading began. A free address writes nothing: the free addresses are counted in usage.
| Dataset | One record per | Fields |
|---|---|---|
address | Address that answered | event.kind state, event.category host, network; host.ip, related.ip, related.hosts (its names); ipam.address.ip, answered (icmp, tcp), icmp.rtt (the echo's round trip), tcp.open (the ports that took a connect), dns.names (its PTR records' names), unknown (the probes of it that could not be sent: tcp/<port>, dns), with error.type incomplete and error.message |
From the second time the sweep looks at an address on, its record carries event.action:
event.action | event.type | Meaning |
|---|---|---|
added | creation | It answers, and was free the last time |
changed | change | It answers, and its open ports or its names differ. Its round trip, and whether its echo came back while a port answers, are not compared |
unchanged | info | It answers as it did |
removed | deletion | It is free, and answered the last time: its last record is written once more, as it was, dated at the reading that found it gone |
- Only the slice just swept is marked. A reading looks at its own slice of the subnet. An address outside it is neither marked unchanged nor removed: it is kept as the sweep last found it until the reading whose slice holds it.
- Not known is not removed. An address that did not answer while a probe of it could not be sent writes nothing, and keeps its last look. An address that answered while one of its probes could not be sent is written as it answered, with
ipam.address.unknownsaying what is missing, and with no action. - The first look after a start marks nothing: what the dataset last found is kept in memory, so a restart, or a move to another Director, marks nothing the first time the sweep looks at each address again.
{
"@timestamp": "2026-09-27T12:00:00Z",
"ecs": {"version": "8.11.0"},
"event": {"module": "ipam", "dataset": "ipam.address", "kind": "state", "category": ["host", "network"],
"type": ["change"], "action": "changed"},
"observer": {"vendor": "VirtualMetric", "product": "IPAM", "name": "office-lan", "hostname": "director01"},
"host": {"ip": ["192.0.2.10"]},
"network": {"type": "ipv4"},
"related": {"ip": ["192.0.2.10"], "hosts": ["web01.example.com"]},
"ipam": {"subnet": "192.0.2.0/24",
"address": {"ip": "192.0.2.10", "answered": ["icmp", "tcp"], "icmp": {"rtt": {"us": 412}},
"tcp": {"open": [22, 443]}, "dns": {"names": ["web01.example.com"]}}}
}
Usage
usage writes one record per completed sweep of the whole subnet, from the reading that probes its last address. A subnet swept over four readings writes one record every four intervals.
| Dataset | One record per | Fields |
|---|---|---|
usage | Completed sweep | event.kind metric, event.category network, event.start, event.end (when the sweep ended, also @timestamp), event.duration; ipam.usage.total (the addresses a sweep probes), used, free, unknown, used_pct (used out of the addresses known, used and free; left out when none is known), readings (how many readings the sweep took) |
{
"@timestamp": "2026-09-27T12:00:38Z",
"ecs": {"version": "8.11.0"},
"event": {"module": "ipam", "dataset": "ipam.usage", "kind": "metric", "category": ["network"], "type": ["info"],
"start": "2026-09-27T12:00:00Z", "end": "2026-09-27T12:00:38Z", "duration": 38000000000},
"observer": {"vendor": "VirtualMetric", "product": "IPAM", "name": "office-lan", "hostname": "director01"},
"network": {"type": "ipv4"},
"ipam": {"subnet": "192.0.2.0/24",
"usage": {"total": 254, "used": 61, "free": 190, "unknown": 3, "used_pct": 0.243, "readings": 1}}
}
Examples
Writing a subnet's usage alone, every hour, with echoes as the only probe... | |