Loading

Network Topology field reference

This page describes every Elasticsearch field the Network Topology plugin reads or writes, its ECS compliance status, mapping type, and expected values.

Badge Meaning
Core ECS Defined in the Elastic Common Schema (ECS) and used as specified.
ECS ext. Uses an ECS-defined namespace but with values that extend beyond the official spec.
Custom No ECS equivalent — SNMP-specific data for which ECS does not define field sets.
Field Type ECS status Description Examples
@timestamp date Core ECS Document timestamp — when the SNMP poll was collected. 2024-01-01T12:00:00.000Z

ECS host fields identify the monitored network device.

Field Type ECS status Description Examples
host.name keyword Core ECS Device hostname (SNMP sysName). hq-core-rtr-01
host.ip ip Core ECS Primary management IP address. 10.1.1.2
host.mac keyword Core ECS Primary MAC address. aa:bb:cc:dd:ee:01
host.type keyword ECS ext. Device category — set explicitly in the Logstash collector config. The ingest pipeline infers it from observer.sys_descr as a fallback when unset. router, switch, firewall, server, ap, unknown

ECS observer fields describe the network device as the observed system.

Field Type ECS status Description Examples
observer.vendor keyword Core ECS Vendor name — auto-detected from observer.sys_descr by the ingest pipeline. Cisco, Juniper, Palo Alto, Arista, Fortinet, HPE, Aruba
observer.sys_descr text Core ECS Raw SNMP sysDescr string — the ingest pipeline uses this to populate observer.vendor and host.type. Cisco IOS XR Software, ASR 9000 Series Router
observer.os.full keyword Core ECS Full OS version string. IOS-XR 7.3.2, Junos 22.1R1

These fields provide hierarchical location context for the device. The ECS network field set covers protocol and transport data; the site, building, and role fields below extend that namespace.

Field Type ECS status Description Examples
network.site keyword ECS ext. Site or datacenter identifier. Defaults to Ungrouped if absent (set by the ingest pipeline). HQ-DC1, Branch-NYC, Branch-CHI
network.building keyword ECS ext. Building within the site. Main, Annex, Tower-B
network.role keyword ECS ext. Network tier — used for topology hierarchy. Controls the vertical position of nodes in the topology map. core, distribution, access, server

No ECS field set covers SNMP interface MIB (IF-MIB, RFC 2863) data. These fields are plugin-defined under the interface.* namespace.

Field Type ECS status SNMP MIB OID Description Examples
interface.name keyword Custom ifDescr (1.3.6.1.2.1.2.2.1.2) Interface name. Gi0/0/0, eth0, xe-0/0/0
interface.speed long Custom ifSpeed (1.3.6.1.2.1.2.2.1.5) Interface speed in bits/sec. 10000000000 (10 Gbps)
interface.status.admin keyword Custom ifAdminStatus (1.3.6.1.2.1.2.2.1.7) Administrative status. up, down
interface.status.oper keyword Custom ifOperStatus (1.3.6.1.2.1.2.2.1.8) Operational status. up, down, testing
interface.traffic.in.bytes long Custom ifInOctets (1.3.6.1.2.1.2.2.1.10) Cumulative inbound bytes. 125000000
interface.traffic.out.bytes long Custom ifOutOctets (1.3.6.1.2.1.2.2.1.16) Cumulative outbound bytes. 87500000
interface.errors.in long Custom ifInErrors (1.3.6.1.2.1.2.2.1.14) Inbound error count. 0
interface.errors.out long Custom ifOutErrors (1.3.6.1.2.1.2.2.1.20) Outbound error count. 0
Note

These are cumulative counters, not rates. To compute bits/sec, take the delta between two consecutive polls in your collector or use a Kibana scripted field.

Populated from the IP-MIB ipNetToMediaTable (RFC 1213, OID 1.3.6.1.2.1.4.22). Used to infer Layer 3 adjacency in the topology map.

Field Type ECS status SNMP MIB OID Description Examples
arp.ip_addr ip Custom ipNetToMediaNetAddress (.4) ARP neighbor IP address. 10.1.1.3
arp.mac_addr keyword Custom ipNetToMediaPhysAddress (.2) ARP neighbor MAC address. aa:bb:cc:dd:ee:02
arp.interface_index integer Custom ipNetToMediaIfIndex (.1) Interface on which the ARP entry was learned. 1

Populated from the BRIDGE-MIB dot1dTpFdbTable (RFC 1493, OID 1.3.6.1.2.1.17.4.3). Used to infer Layer 2 adjacency between switches in the topology map.

Field Type ECS status SNMP MIB OID Description Examples
mac_table.mac_addr keyword Custom dot1dTpFdbAddress (.1) MAC address in forwarding table. aa:bb:cc:dd:ee:05
mac_table.port_index integer Custom dot1dTpFdbPort (.2) Bridge port on which this MAC was seen. 2
mac_table.status keyword Custom dot1dTpFdbStatus (.3) Entry type. learned, static, mgmt

Populated from the IP-MIB ipAddrTable (RFC 1213, OID 1.3.6.1.2.1.4.20). Used to determine which network segments (CIDRs) each device participates in.

Field Type ECS status SNMP MIB OID Description Examples
ip_addr.address ip Custom ipAdEntAddr (.1) Interface IP address — used for CIDR-based segment lookups. 192.168.10.1
ip_addr.netmask keyword Custom ipAdEntNetMask (.3) Interface subnet mask. 255.255.255.0
ip_addr.network keyword Custom computed CIDR block derived from address and netmask — used for segment grouping. 192.168.10.0/24
ip_addr.prefix_length integer Custom computed Prefix length derived from netmask. 24
ip_addr.if_index integer Custom ipAdEntIfIndex (.2) Interface index linking this IP to an interface row. 3
Note

Loopback (127.x), link-local (169.254.x), multicast (>=224), and unspecified (0.x) addresses are filtered out at collection time.

Populated from the BGP4-MIB bgpPeerTable (RFC 4273, OID 1.3.6.1.2.1.15.3). Used to display BGP peering sessions and create logical overlay links on the topology map.

Field Type ECS status SNMP MIB OID Description Examples
bgp_peer.remote_ip ip Custom bgpPeerRemoteAddr (.7) BGP peer remote IP address. 198.51.100.1
bgp_peer.remote_asn long Custom bgpPeerRemoteAs (.9) Remote autonomous system number. 3356
bgp_peer.local_asn long Custom bgpLocalAs (1.3.6.1.2.1.15.2) Local autonomous system number. 65000
bgp_peer.peer_state keyword Custom bgpPeerState (.2) BGP FSM state. Established, Idle, Active
bgp_peer.prefixes_received long Custom vendor-specific Prefixes received from this peer (not in standard BGP4-MIB). 920000
bgp_peer.prefixes_sent long Custom vendor-specific Prefixes advertised to this peer. 12
bgp_peer.uptime_seconds long Custom bgpPeerFsmEstablishedTime (.16) Seconds since the session was established. 2592000
bgp_peer.in_updates long Custom bgpPeerInUpdates (.10) BGP UPDATE messages received. 45000
bgp_peer.out_updates long Custom bgpPeerOutUpdates (.11) BGP UPDATE messages sent. 1200
Note

Prefix counts (prefixes_received, prefixes_sent) are not part of the standard BGP4-MIB. They are available in vendor-specific MIBs (for example, Cisco CISCO-BGP4-MIB, Juniper jnxBgpM2PrefixCounters) or in BGP4-MIB-V2 (draft). The Logstash filter sets these to 0 when unavailable.

Populated from the OSPF-MIB ospfNbrTable (RFC 4750, OID 1.3.6.1.2.1.14.10). Used to display OSPF adjacency state and create interior routing links on the topology map.

Field Type ECS status SNMP MIB OID Description Examples
ospf_neighbor.neighbor_ip ip Custom ospfNbrIpAddr (.1) OSPF neighbor IP address. 10.1.1.2
ospf_neighbor.router_id ip Custom ospfNbrRtrId (.3) Neighbor's OSPF router ID. 10.1.1.2
ospf_neighbor.state keyword Custom ospfNbrState (.6) OSPF FSM adjacency state. Full, 2-Way, Down
ospf_neighbor.area_id keyword Custom from OID index OSPF area identifier. 0.0.0.0 (backbone)
ospf_neighbor.priority integer Custom ospfNbrPriority (.5) DR election priority. 1
ospf_neighbor.dead_timer integer Custom configured Dead interval in seconds. 40
ospf_neighbor.retrans_count integer Custom ospfNbrEvents (.7) Number of state change events. 3
Note

OSPF state values: 1=Down, 2=Attempt, 3=Init, 4=2-Way, 5=ExStart, 6=Exchange, 7=Loading, 8=Full. Full means fully adjacent (exchanged LSDBs). 2-Way is normal for DROther routers on broadcast segments.

A single SNMP poll cycle produces six document types per device, all indexed into the logs-snmp.topology-default data stream:

Document type Distinguishing field Purpose
Interface metrics interface.name present Per-interface status, speed, traffic, errors.
ARP entry arp.mac_addr present Layer 3 neighbor discovery.
MAC table entry mac_table.mac_addr present Layer 2 forwarding topology.
IP address entry ip_addr.address present Interface IPs and subnet membership for segment views.
BGP peer session bgp_peer.remote_ip present BGP peering state, AS numbers, prefix counts, uptime.
OSPF neighbor ospf_neighbor.neighbor_ip present OSPF adjacency state, router ID, area, priority.

All six share the same host.*, observer.*, and network.* fields to identify which device the data belongs to.

The ingest pipeline performs the following on every incoming document:

  1. Device type default — sets host.type = "unknown" if the field is absent.
  2. Site default — sets network.site = "Ungrouped" if the field is absent.
  3. Device type inference (fallback) — if host.type is still "unknown", performs a keyword match on observer.sys_descr to set host.type (router, switch, firewall, ap, server). This is a best-effort fallback; setting host.type explicitly in the collector config is preferred.
  4. Vendor detection — runs a regex match on observer.sys_descr to set observer.vendor. Cisco, Juniper, Arista, Fortinet, Palo Alto, HPE, and Aruba are recognized out of the box, and you can extend the pipeline to recognize additional vendors.

The pipeline is created by the scripts/setup_elasticsearch.sh script in the Network Topology plugin repository.