Guide

Monitoring

Ze provides real-time BGP event monitoring and a live peer dashboard through the CLI. Commands follow verb-first syntax: monitor <module>.

Live Peer Dashboard

ze cli -c "monitor bgp"

The dashboard refreshes every second and shows router identity plus a sortable, color-coded peer table with update rates. Keys: j/k moves, s/S sorts, Enter opens detail, and Esc exits.

Each column sorts by the value it holds, not by the text it prints. Addresses sort numerically, so 10.0.0.9 comes before 10.0.0.10 and every IPv4 peer comes before every IPv6 one. Uptime sorts by duration, so 59s comes before 1m0s. State sorts by how far the session has progressed, from stopped to established. Rows that hold the same value in the sorted column come out in address order. The highlighted peer therefore stays under the cursor from one refresh to the next, and when you change the sort column or reverse the direction.

Event Streaming

ze cli -c "monitor event"

Filters

Filter Example Description
peer peer upstream1 Show events for one peer
include include update,state Filter by event type (comma-separated)
exclude exclude keepalive Exclude event types
direction direction received Only received or sent events

Combine filters:

ze cli -c "monitor event peer upstream1 include update direction received"

Event Types

Event Has Direction Description
update ✓ Route announcements and withdrawals
open ✓ OPEN message exchange
notification ✓ Session error notifications
keepalive ✓ Keepalive exchanges
refresh ✓ Route refresh requests
state ✕ Peer state changes (up/down)
negotiated ✕ Capability negotiation results
eor ✓ End-of-RIB markers
rpki ✓ RPKI validation results

Output Formats

Pipe the output through format operators:

ze cli -c "monitor event | json"      # Full JSON envelope
ze cli -c "monitor event | table"     # Tabular format
ze cli -c "monitor event | match rx"  # Regex filter on output

JSON Event Format

All events follow the ze-bgp JSON envelope:

{
  "type": "bgp",
  "bgp": {
    "peer": {
      "address": "10.0.0.1",
      "local": {"address": "10.0.0.2", "as": 65000},
      "remote": {"address": "10.0.0.1", "as": 65001}
    },
    "message": {
      "id": 42,
      "direction": "received",
      "type": "update"
    }
  }
}

UPDATE Event

{
  "type": "bgp",
  "bgp": {
    "peer": {"address": "10.0.0.1", "local": {"address": "10.0.0.2", "as": 65000}, "remote": {"address": "10.0.0.1", "as": 65001}},
    "message": {"id": 1, "direction": "received", "type": "update"},
    "update": {
      "ipv4/unicast": [
        {
          "next-hop": "10.0.0.1",
          "action": "add",
          "nlri": ["10.0.0.0/24", "10.0.1.0/24"]
        }
      ]
    },
    "origin": "igp",
    "as-path": [65001, 65002],
    "local-preference": 100
  }
}

State Event

{
  "type": "bgp",
  "bgp": {
    "peer": {"address": "10.0.0.1", "local": {"address": "10.0.0.2", "as": 65000}, "remote": {"address": "10.0.0.1", "as": 65001}},
    "message": {"type": "state"},
    "state": "up"
  }
}

Programmatic Access

Plugins can subscribe to events via the SDK:

attach process my-plugin {
    receive [ update state ]
}

The plugin receives events through its OnEvent callback. See Plugins guide for details.

Prometheus Metrics

Ze exposes Prometheus metrics when telemetry { prometheus { ... } } is configured. BGP metrics are refreshed every 10 seconds. By default the HTTP listener binds to 127.0.0.1:9273; configure an explicit server address to expose it to remote scrapers.

Without BGP, Ze installs the metrics registry before plugins start. Their startup counters then use the same registry that the exporter serves.

For the system RIB, show doctor includes rib-routing-view in both plugin placements. It reports an initializing or unavailable routing view and names the configured plugin's restart command. ze_rib_view_ready becomes one after the authoritative view and its output synchronize. ze_rib_view_resync_total counts reconstruction attempts, and ze_rib_view_pending_prefixes shows prefixes held for snapshot or forwarding reconciliation.

The netdata block only controls Netdata-compatible OS collector metrics. It does not rename Ze-native metrics such as ze_bgp_*, ze_bfd_*, or ze_l2tp_*.

telemetry {
    prometheus {
        enabled true;
        server main {
            ip 0.0.0.0;
            port 9273;
        }
        path /metrics;
        basic-auth {
            enabled true;
            username prometheus;
            plaintext-password "secret";
        }
        netdata {
            enabled true;
            prefix netdata;
            interval 1;
            collector diskspace {
                enabled false;
            }
            collector snmp6 {
                interval 10;
            }
        }
    }
}
Path Default Description
enabled false Enable Prometheus HTTP endpoint
server 127.0.0.1:9273 Listener list. Explicit 0.0.0.0 binds all interfaces
path /metrics HTTP metrics path
basic-auth/enabled false Require HTTP Basic Authentication for metrics and health endpoints
basic-auth/realm ze prometheus Basic Auth realm
basic-auth/username unset Basic Auth username
basic-auth/password unset Bcrypt-hashed Basic Auth password
basic-auth/plaintext-password unset Write-only password input, hashed at commit and at load
netdata/enabled true Enable Netdata-compatible OS collectors
netdata/prefix netdata Prefix for Netdata-compatible OS collector metrics only
netdata/interval 1 Netdata-compatible OS collector sampling interval (1-60s)
netdata/collector -- Per-Netdata-collector enable and interval overrides

Deprecated compatibility aliases remain accepted: prefix, interval, and collector directly under prometheus. Prefer netdata/prefix, netdata/interval, and netdata/collector in new config.

HTTP Basic Authentication

When basic-auth/enabled is true, Ze requires HTTP Basic Authentication for every handler on the Prometheus service, including both /metrics and /health. The password is stored as a bcrypt hash in the persisted config. Use plaintext-password when you edit the config and Ze replaces it with password at commit. If automation already has a hash from ze passwd, set password directly.

A config file loaded at daemon start or at SIGHUP gets the same transform. Ze hashes the leaf in memory and leaves your file as you wrote it. It warns that the plaintext is still on disk.

Prometheus scrape configuration:

scrape_configs:
  - job_name: ze
    static_configs:
      - targets: ["router.example.net:9273"]
    basic_auth:
      username: prometheus
      password: secret

Basic Auth does not provide transport encryption. Keep the listener on loopback, use a trusted management network, or put TLS in front of the service if the scrape crosses an untrusted network.

Per-collector overrides:

netdata {
    collector diskspace { enabled false; }
    collector snmp6 { interval 10; }
}

OS Metrics (Netdata-compatible)

Ze exports OS metrics from /proc and /sys named and labeled after Netdata's Prometheus exporter (its /api/v1/allmetrics?format=prometheus endpoint), so dashboards built on Netdata's metric names can read them. No test compares the names, the values or the metric count against a running Netdata.

Metric name format: {prefix}_{context}_{units}_average{chart="...",dimension="...",family="..."}, where {prefix} is telemetry.prometheus.netdata.prefix.

Collector /proc or /sys source Charts exposed
CPU /proc/stat system.cpu, cpu.cpu<N>
cpufreq /sys/devices/system/cpu/cpu*/cpufreq cpufreq.cpufreq, cpu.core_throttling
cpuidle /sys/devices/system/cpu/cpu*/cpuidle cpuidle.cpu<N>_cpuidle
Memory /proc/meminfo system.ram, system.swap, mem.available, mem.committed, mem.kernel, mem.slab, mem.thp, mem.writeback, mem.hugepages, mem.reclaiming, mem.swap_cached, mem.cma, mem.directmaps, mem.hwcorrupt, mem.zswap
Load /proc/loadavg system.load
Processes /proc/stat system.processes, system.forks, system.ctxt, system.intr
Interrupts /proc/softirqs system.softirqs
Pressure (PSI) /proc/pressure/* system.{cpu,memory,io}_{some,full}_pressure
Network (per-iface) /proc/net/dev, /sys/class/net net.net, net.packets, net.errors, net.drops, net.fifo, net.compressed, net.events, net.speed, net.duplex, net.operstate, net.carrier, net.mtu
Network (aggregate) /proc/net/dev, snmp, snmp6 system.net, system.ipv4, system.ipv6
IPv4 /proc/net/snmp ipv4.packets, ipv4.errors, ipv4.tcppackets, ipv4.tcperrors, ipv4.tcphandshake, ipv4.tcpsock, ipv4.udppackets, ipv4.udperrors, ipv4.icmp, ipv4.icmpmsg, ipv4.fragsout, ipv4.fragsin
IPv4 netstat /proc/net/netstat ipv4.mcast, ipv4.mcastpkts, ipv4.bcast, ipv4.bcastpkts, ipv4.ecnpkts, ip.tcpconnaborts, ip.tcpmemorypressures, ip.tcpreorders, ip.tcpofo
IPv6 /proc/net/snmp6 ipv6.packets, ipv6.errors, ipv6.udppackets, ipv6.udperrors, ipv6.mcast, ipv6.fragsout, ipv6.fragsin
Sockets /proc/net/sockstat, sockstat6 ip.sockstat_sockets, ipv4.sockstat_tcp_sockets, ipv4.sockstat_tcp_mem, ipv4.sockstat_udp_sockets, ipv4.sockstat_udp_mem, ipv6.sockstat6_*
Conntrack /proc/net/stat/nf_conntrack netfilter.conntrack_sockets, _new, _changes, _errors, _search, _expect
Softnet /proc/net/softnet_stat system.softnet_stat, cpu.cpu<N>_softnet_stat
Disk I/O /proc/diskstats disk.io, disk.ops, disk.mops, disk.iotime, disk.busy, disk.backlog, disk.await, disk.svctm, disk.avgsz, disk.qops, system.io
Disk space /proc/mounts + statfs disk_space.<mount>
mdstat /proc/mdstat md.health, md.disks, md.mismatch_cnt
ZFS /proc/spl/kstat/zfs/arcstats zfs.arc_size, zfs.reads, zfs.hits, zfs.hits_rate, zfs.l2_size, zfs.l2_hits_rate, zfs.memory_ops
btrfs /sys/fs/btrfs/*/allocation btrfs.disk, btrfs.data, btrfs.metadata, btrfs.system
VMstat /proc/vmstat mem.pgfaults, system.pgpgio, mem.swapio, mem.oom_kill, mem.numa, mem.balloon, mem.zswapio, mem.ksm_cow, mem.thp_faults, mem.thp_collapse
SCTP /proc/net/sctp/snmp sctp.snmp
IPVS /proc/net/ip_vs_stats ipvs.net
Wireless /proc/net/wireless net_wireless.*
Other /proc/uptime, /proc/sys/kernel/random/entropy_avail, /proc/sys/fs/file-nr system.uptime, system.entropy, system.file_nr_used

Collectors whose data sources are absent (no ZFS loaded, no btrfs mounts, no wireless NICs, etc.) skip silently.

Side-by-side validation against Netdata:

curl -s http://localhost:9273/api/v1/allmetrics?format=prometheus | grep "^netdata_" | sed 's/ .*//' | sort -u > nd.txt
curl -s http://localhost:9274/metrics | grep "^netdata_" | sed 's/ .*//' | sort -u > ze.txt
diff nd.txt ze.txt

Host Inventory Metrics

Metric Type Labels Description
ze_host_memory_total_bytes gauge - Total physical memory in bytes
ze_host_memory_available_bytes gauge - Available physical memory in bytes
ze_host_cpu_logical_count gauge - Number of logical CPUs
ze_host_cpu_physical_cores gauge - Number of physical CPU cores
ze_host_uptime_seconds gauge - Host uptime in seconds
ze_host_ecc_correctable_errors_total gauge - ECC correctable error count
ze_host_ecc_uncorrectable_errors_total gauge - ECC uncorrectable error count
ze_host_nic_link_speed_mbps gauge name NIC link speed in Mbps
ze_host_nic_carrier gauge name NIC carrier state (1=up, 0=down)
ze_host_storage_size_bytes gauge name Block device size in bytes
ze_host_thermal_temp_mc gauge name, device Thermal sensor reading in millicelsius

Ze collects host metrics once when the exporter starts and again every 30 seconds. The detector caches an inventory for 60 seconds, so a value can be up to a minute old. Neither interval is configurable. Linux only; on other platforms no host metrics are registered.

Contained Panics

Metric Type Labels Description
ze_task_panics_total counter component, task Panics recovered at a network-input task boundary. Each one ended one unit (a session, a neighbor, a request, a connection) while Ze kept running

Any value above zero is a Ze defect. The ERROR log line of each panic names the unit and the stack, and ze show crashes lists its crash record with kind recovered: attach that record to the bug report. A component's tasks appear at zero from the moment the component has a metrics registry.

component task The unit one panic ends
bgp read One BGP session: the peer is sent Cease / Unspecific and reconnects after its backoff
bgp cancel One BGP session's connection, closed when the session ends
bgp connect One connection cycle of a peer (dial, OPEN setup): the peer retries after its backoff
bgp delivery One BGP session whose received UPDATEs could not reach the plugins: Cease / Unspecific
bgp accept One accepted TCP connection: the listener keeps accepting

| rpki | rtr-read | One RTR sync with one cache: the cache is sent an Error Report Internal Error, the connection closes, the next cache in preference order takes the load, and this cache is asked again after its Retry Interval |

| bmp | receive | One monitored router's BMP session: it closes with no message sent back, the router's routes are withdrawn, and the router reconnects under its own configuration |

| ldp | session | One LDP session: the peer is sent an Internal Error Notification, the session closes, and the neighbor's next Hello sets it up again | | ldp | discovery | One received Hello, dropped: discovery reads the next one on the same socket |

| rsvp-te | signaling | The LSPs one received RSVP message names: each loses its state as if it had timed out (the forwarding entry it installed, its label and admission charge released, no teardown message sent). A transit or egress LSP is set up again by the upstream's next PATH refresh; a tunnel or bypass this router heads is signaled again only when the configuration is next committed. The engine handles the next message at once | | rsvp-te | receive | One received RSVP datagram, dropped: the receiver reads the next one on the same socket |

| ospf | interface-read | One OSPFv2 interface's socket reader: the interface leaves OSPF, its neighbors go Down, and the 30-second rescan reopens it | | ospf | interface-fan-in | The same interface, when the transport's per-interface fan-in panicked: same recovery |

| ospfv3 | interface-read | One OSPFv3 interface's socket reader: the interface leaves OSPFv3, its neighbors go Down, and the 30-second rescan reopens it | | ospfv3 | interface-fan-in | The same interface, when the OSPFv3 transport's per-interface fan-in panicked: same recovery |

| ospf | consumer | One call into a callback another package registered with the OSPF engine (an opaque LSA consumer, a Router Information TLV builder, an Extended Link or Prefix sub-TLV codec): its contribution to that one LSA or origination is dropped, its own error counter rises, and it is called again on the next one | | ospf | show-decode | One LSA body decoded or rendered for a show ospf database command: that row is shown undecoded | | ospf | receive | One received OSPFv2 or OSPFv3 packet: it is dropped and its sending neighbor goes Down (KillNbr), its next Hello brings it back, and every other neighbor keeps its state |

| isis | interface-read | One IS-IS circuit's socket reader: the circuit leaves IS-IS, its adjacencies go Down, and the 30-second rescan reopens it | | isis | interface-fan-in | The same circuit, when the transport's per-circuit fan-in panicked: same recovery |

| isis | receive | One received IS-IS PDU: it is dropped and the adjacencies of the neighbor that sent it, on that circuit only, go Down; its next Hello brings them back, and every other adjacency keeps its state |

| l2tp | control | One L2TP tunnel: it is cleared with a StopCCN (Result Code 1, General request to clear control connection), its sessions end, the LAC sets it up again, and the other tunnels keep running | | l2tp | auth-handler | One session's authentication, refused: the subscriber's PPP retries it | | l2tp | pool-handler | One session's address request, refused: the subscriber's PPP retries it |

| pppoe | discovery | One discovery frame: the session its PADR was admitting ends (removed with no frame sent before the PADS, a PADT after it), the host starts discovery again, and the reader serves every other host | | pppoe | auth-handler | One session's authentication, refused: the subscriber's PPP retries it | | pppoe | pool-handler | One session's address request, refused: the subscriber's PPP retries it |

| ike | inbound | One received IKE datagram, dropped: the socket's dispatch goroutine reads the next one, and the peer retransmits its request | | ike | established | One IKE SA: the peer is sent a Delete for it (unless it stopped answering), its Child SAs go with it, and Ze sets it up again through IKE_SA_INIT and IKE_AUTH; every other SA keeps running |

| plugin | rpc-read | One plugin connection, when its reader panicked: the connection closes and the engine releases the plugin as it does one whose process exited; every other plugin keeps its connection | | plugin | rpc-route | The same connection, when the reader that routes answers and requests panicked: same recovery, and the plugin's calls in flight fail |

| plugin | connect-back | One external plugin's connect-back, before its handshake: the connection closes, and that plugin fails to start as one that never connected |

| plugin | run | One in-process plugin: it ends as if it had returned, and the engine releases it as it does any plugin that exited |

| plugin | engine-op | One request a plugin sent the engine: it is answered with an error and is not applied; the plugin keeps its connection and its other requests are served | | plugin | managed-client | One managed client's connection: it closes and the client's name is released; the client connects again on its own schedule, and every other client keeps its connection |

| bfd | receive | One received BFD packet, dropped: the socket reader reads the next one, and no session changes state |

| bfd | express | The BFD session the loop was serving, when it was serving one: it goes Down with diagnostic 0 (No Diagnostic) and comes back Up through the three-way handshake; every other session on the loop keeps running |

| vrrp | receive | One received advertisement, dropped: the virtual router's socket reader reads the next one, and its state is unchanged |

| vrrp | advertisement | One virtual router: it runs Shutdown (an Active router resigns with Priority 0) and Startup, re-entering as Backup, or as Active when it owns the address; every other virtual router is untouched |

| radius | read | One answer from a RADIUS server, dropped: the client's reader reads the next one, and the request it answered retransmits and fails over as on a timeout |

| radius-coa | request | One CoA-Request or Disconnect-Request: answered with a NAK carrying Error-Cause 506 (Resources Unavailable) when it had been authenticated, dropped otherwise; the listener serves the next one |

| radius-auth | request | One subscriber login, denied with internal error; every other login is served as before |

| radius-auth | accounting | One session's Start and Interim-Update records: none follow, the session stays up, and its Stop record is still sent when it ends; every other session accounts as before |

| dhcp | request | One DHCP request, unanswered: the client retransmits it, and the listener serves the next one |

| tftp | request | One TFTP request: its client is sent an ERROR (code 0), and the listener serves the next request | | tftp | transfer | One file transfer: its client is sent an ERROR (code 0) on the transfer's socket and the transfer ends; every other transfer runs on |

| tacacs | request | One TACACS+ authentication, authorization or accounting request: it fails as if the server were unreachable, so the AAA chain moves to its next backend, and the connection it used is closed |

| ssh | session | One SSH session, interactive or exec: its user is told on the session that an internal defect ended it and which ze show crashes command finds the record, and it exits with status 1; the listener and every other session keep running | | ssh | auth | One login attempt, refused: the client sees an authentication failure and can try again; every other login and session keeps running |

| gnmi | rpc | One gNMI call (Capabilities, Get, Set) or one Subscribe stream: it ends with status Internal and a plain message naming the ze show crashes command, and a Set's uncommitted edits are discarded; the listener and every other call and stream keep running |

| config-confirm | write | One config write on the commit-confirm worker (a gNMI Set, an SSH, web or API commit, an accept, an abort, a managed push): its caller gets an error saying the write may be partly applied and naming the ze show crashes command; the worker serves the next write and the open window's deadline |

PPPoE Client IPv6 Metrics

A home CPE on a PPPoE WAN publishes whether IPv6 reached the WAN and whether the WAN holds a prefix for the LAN, one series per pppoe-client name:

Metric Type Meaning
ze_pppoe_client_ipv6cp_opened{name} gauge 1 while IPv6CP is Opened and IPv6 passes on the session; 0 before it opens, after the access concentrator rejects or closes it, during an LCP restart, and once the session ends
ze_iface_delegated_prefixes_held{name} gauge The delegated prefixes the client's DHCPv6 lease holds. 0 means no LAN unit whose ipv6 delegated-prefix names this client has a /64
ze_pppoe_client_renegotiations_total{name} counter Network-phase LCP renegotiations the client started

An alert on ze_pppoe_client_ipv6cp_opened == 1 and ze_iface_delegated_prefixes_held == 0 finds a WAN with IPv6 whose ISP has not delegated a prefix. show interface pppoe-client shows the prefixes and the lifetimes that remain.

Loc-RIB Import Policy Metrics

An import chain (<protocol> filter import, rib filter import) can hide a path: the Loc-RIB keeps it but never selects it. These two series count what the chains hid, labelled by the protocol that offered the path. What each hidden path is and which chain hid it: show rib candidates prefix <prefix> (route policy).

Metric Type Labels Description
ze_rib_policy_hidden_paths gauge source Paths of that source the Loc-RIB holds hidden now
ze_rib_policy_rejected_total counter source, chain (source or central) Rejections. Every route a protocol offers that a chain rejects counts once; a reload counts a stored path again only when its verdict changes

BGP Metrics

Instance

Metric Type Description
ze_info gauge Instance info (labels: version, router_id, local_as)
ze_uptime_seconds gauge Seconds since reactor started
ze_peers_configured gauge Number of configured peers
ze_cache_entries gauge UPDATE cache entry count

Per-Peer

Metric Type Labels Description
ze_peer_state gauge peer FSM state (0=stopped, 1=connecting, 2=active, 3=established)
ze_peer_messages_received_total counter peer, type Messages received (type: update, keepalive, open, notification, refresh, eor)
ze_peer_messages_sent_total counter peer, type Messages sent (type: update, keepalive, open, notification, refresh, eor)

Session Lifecycle

Metric Type Labels Description
ze_peer_sessions_established_total counter peer Times the session reached Established
ze_peer_session_flaps_total counter peer Sessions dropped from Established
ze_peer_state_transitions_total counter peer, from, to Peer FSM state transitions
ze_peer_notifications_sent_total counter peer, code, subcode NOTIFICATION messages sent
ze_peer_notifications_received_total counter peer, code, subcode NOTIFICATION messages received
ze_peer_session_duration_seconds gauge peer Seconds since the session established
ze_bgp_open_in_established_total counter peer OPEN messages refused because the connection was already in Established or OpenConfirm
ze_bgp_open_rejected_bad_peer_as_total counter peer OPEN messages refused with NOTIFICATION 2/2 Bad Peer AS
ze_bgp_connect_retry_counter gauge peer RFC 4271 ConnectRetryCounter: times this peer has tried to establish a session since the last operator start or stop

A non-zero ze_bgp_open_in_established_total names a peer that tried to re-negotiate mid-session. Ze answers it with a Cease and closes the connection.

A non-zero ze_bgp_open_rejected_bad_peer_as_total names a peer whose OPEN carried an AS Ze does not accept for it: AS 0 (RFC 7607 Section 2), or an AS that is neither the configured remote { as } nor, on a session configured with session { asn { migration } }, the other AS of the migration pair (RFC 7705 Section 4.2). The usual cause is a mistyped remote { as } on one side. Ze refuses the OPEN and closes the connection, so the session never establishes and the peer retries.

ze_bgp_connect_retry_counter is RFC 4271 Section 8.1.1 mandatory session attribute 2, "the number of times a BGP peer has tried to establish a peer session". The BGP FSM raises it by one on each teardown RFC 4271 Section 8.2.2 gives an increment clause: a hold-timer expiry, a header or OPEN error, a NOTIFICATION, an UPDATE error, a mid-session TCP failure, and any event the state does not expect. Two events set it back to zero, and only these two: the operator starts the peer, and the operator stops it. A reconnect does not, which is what makes the value a history rather than a flag.

It is a GAUGE, not a counter. Those operator resets make the value go down, and a Prometheus counter that goes down reads as a counter reset to rate(). Use the value directly, not a rate: it already IS a count.

Read the same number per peer with show bgp peer <address> detail, field connect-retry-counter.

Startup and Connection Timing

Metric Type Labels Description
ze_plugin_startup_seconds histogram - WaitForPluginStartupComplete duration
ze_api_ready_seconds histogram - WaitForAPIReady duration
ze_peer_dial_seconds histogram peer, result TCP dial duration (result: ok, fail)
ze_peer_connect_attempt_seconds histogram peer Full connection attempt (runOnce) duration
ze_peer_connect_attempts_total counter peer Connection attempts
ze_peer_backoff_seconds histogram peer Backoff wait duration before retry

Forward Pool / Congestion

Metric Type Labels Description
ze_forward_workers_active gauge - Active forward pool workers
ze_bgp_pool_used_ratio gauge - Global overflow pool utilization (0.0 = empty, 1.0 = full)
ze_bgp_overflow_items gauge peer Items in per-destination overflow buffer
ze_bgp_overflow_ratio gauge source Per-source overflow ratio: overflowed / (forwarded + overflowed)

Attribute Index

Metric Type Labels Description
ze_bgp_update_span_spill_total counter peer Received UPDATEs whose attribute count exceeded the inline span capacity
ze_bgp_update_nlri_malformed_total counter peer, action Received typed NLRIs (BGP-MUP) with a malformed body: withdrawn when treated as withdrawn, discarded when no route key forms to withdraw them by

Ze indexes the path attributes of every received UPDATE once, on the receive goroutine, and holds the first 8 spans inline. A 9th attribute puts the remainder on the heap and increments this counter. A public-internet corpus of 112M routes has a maximum of 10 attributes and 99.9% at 8 or fewer, so a steady rate here means either an unusual peer or an attribute set worth raising the inline size for.

The count is taken over the attributes Ze publishes, not over the attributes the peer sent. Ordinary sessions first drop unrecognized non-transitive attributes; route-server client sessions retain them. Thus a nine-attribute UPDATE with two such attributes stays below the inline limit on an ordinary session, but not necessarily on a route-server client session. Partial-bit normalization and other publication-time repairs also precede index construction. This counter does not measure the untouched wire attribute set.

Egress Modification Failures

Metric Type Labels Description
ze_bgp_update_modify_failed_total counter reason An egress modification could not be applied to a route

A non-zero value means a configured modification (a next-hop rewrite, a community strip, a private-ASN removal) did not fit the route it applied to. The reason label set is closed: malformed, overflow, attr-length-range, withdrawn-size, no-handler, handler-fault, and truncated. The no-failure sentinel must never be emitted as a failure. An unnamed internal reason raises a BUG assertion instead of producing an unclassified label.

Treat any increment as a policy that did not take effect. Ze counts the failure at the point the modification is built, on all five paths that build one: the forward rail, the route-server rail, the ingress and egress policy chains, and the RFC 9494 stale re-advertise rail.

Well-Known Community Suppressions

Metric Type Labels Description
ze_bgp_wellknown_community_suppressed_total counter community A route was withheld from one destination peer by an RFC 1997 well-known community

An increment means a route ze received carrying NO_EXPORT, NO_ADVERTISE or NO_EXPORT_SUBCONFED was not advertised to a peer that community forbids. One observation is one destination, so a route withheld from 20 peers counts 20. The suppression is not configurable and is never logged per route, so this counter is the only place an operator sees it.

AS_SET Withdrawals

Metric Type Labels Description
ze_bgp_as_set_withdrawn_total counter none A route was written to a peer as a withdrawal because its AS_PATH or AS4_PATH held an AS_SET or AS_CONFED_SET

RFC 9774 Section 3 forbids advertising a set, so the writer sends the withdrawal form of such an UPDATE instead, whatever produced it (a static route with a raw attribute, update hex, a plugin). The counter adds the number of routes the UPDATE announced. A warning line, at most one a second for each peer, names the peer and the route count and says to remove the set segment.

The community label set is closed and holds three values: no-advertise, no-export-subconfed, no-export. A route carrying more than one is counted under the strictest, so one suppressed route is always one observation.

The counter says nothing about withdrawals. RFC 1997 forbids ADVERTISING such a route, so a suppressed destination still receives the withdrawals of the same UPDATE and keeps no route ze cannot take back.

Announces Refused For Size

Metric Type Labels Description
ze_bgp_announce_dropped_oversize_total counter rail, stage An announce did not fit its build buffer and was not sent to that peer

An increment means a route never reached one peer. Ze queries the encoded size before it writes, so no truncated UPDATE goes out: the announce is abandoned whole. Nothing else reports this to the operator, because the peer is not notified and the session is not disturbed.

Both label sets are closed. rail is batch for an announce built from the API and queued for one built from the RIB. stage is nlri when the prefix block did not fit and attributes when the path-attribute block did not.

A batch increment also reaches the caller: AnnounceNLRIBatch returns errAnnounceTooLarge, which the dispatcher turns into a StatusError response, so a plugin sees its own announce refused. A queued increment has no such channel and the counter is the only signal besides the log line. Act on either by sending fewer prefixes per announce, or by reducing the attributes on the route.

Sends Refused By The Attach Permission

Metric Type Labels Description
ze_bgp_send_refused_total counter process, type A process asked to generate a message toward a peer whose config does not attach it with that send type. Nothing reached the peer

A peer feeds and is fed by the processes its attach process <name> blocks name, and the send list inside a block is the permission to originate toward that peer. An increment means a program addressed a peer it was never attached to: the peer was dropped from that command and nothing went on its wire. type is update for a route, a withdrawal or an End-of-RIB marker, and refresh for a route refresh or a soft clear.

A steady non-zero rate with no config change is usually a program that widened its selector to peer * and is now reaching for peers the operator never linked it to. A step at reload is usually the opposite: an attach block was removed while the program kept announcing. The WARN line beside each increment names the peer, which this counter deliberately does not (an error path should not carry peer-driven cardinality), and it prints the exact block to add.

An operator at the CLI, over SSH or through the REST API never appears here: their authority is checked by AAA, and send grants authority to a program.

Prefix Limits (RFC 4486)

Metric Type Labels Description
ze_bgp_prefix_count gauge peer, family Current prefix count
ze_bgp_prefix_maximum gauge peer, family Configured hard maximum
ze_bgp_prefix_warning gauge peer, family Warning threshold
ze_bgp_prefix_warning_exceeded gauge peer, family 1 if count >= warning
ze_bgp_prefix_ratio gauge peer, family count / maximum (0.0 to 1.0+)
ze_bgp_prefix_maximum_exceeded_total counter peer, family Times maximum exceeded
ze_bgp_prefix_teardown_total counter peer Sessions torn down for prefix limit
ze_bgp_prefix_stale gauge peer 1 if prefix data older than 6 months

Single Command

For scripting, use -c to execute a single command and exit:

ze cli -c "show bgp"
ze cli -c "show bgp rib received"
ze cli -c "show bgp rpki status"