| name | interface-health |
| description | Interface and link health assessment with error counter analysis, optical power monitoring, discard diagnosis, and utilization trending. Multi-vendor coverage for Cisco IOS-XE/NX-OS, Juniper JunOS, and Arista EOS with severity-tiered thresholds for physical and data-link layer metrics. |
| license | Apache-2.0 |
| metadata | {"safety":"read-only","author":"network-security-skills-suite","version":"1.0.0","openclaw":"{\"emoji\":\"🔍\",\"safetyTier\":\"read-only\",\"requires\":{\"bins\":[\"ssh\"],\"env\":[]},\"tags\":[\"interface\",\"errors\",\"optics\"],\"mcpDependencies\":[],\"egressEndpoints\":[]}"} |
Interface Health Assessment
Threshold-driven diagnostic skill for interface and link health. Covers the
physical and data-link layers — error counters, optical power levels, discard
rates, interface flaps, and bandwidth utilization. Each metric is evaluated
against four severity tiers (Normal / Warning / Critical / Emergency) with
vendor-specific collection commands.
Commands are labeled [Cisco], [JunOS], or [EOS] where syntax
diverges. Unlabeled statements apply to all three vendors. Detailed command
syntax is in references/cli-reference.md; full threshold tables with
per-optic-type ranges are in references/threshold-tables.md.
When to Use
- Interface reported down or flapping (repeated up/down transitions)
- Users reporting packet loss or degraded throughput on a link
- Monitoring alerts for CRC errors, input errors, or output drops
- Pre/post maintenance validation of link quality after cable or optic swap
- Optical power alarms from DOM (Digital Optical Monitoring) readings
- Capacity planning — identifying interfaces approaching saturation
- Troubleshooting latency spikes that correlate with interface congestion
- Baseline collection for new link turn-ups or circuit migrations
Prerequisites
- SSH or console access to the device (read-only privilege sufficient)
- Interfaces to evaluate are identified (specific interfaces or all active)
- Baseline error counts or a prior snapshot for delta comparison — without a
baseline, only instantaneous rates and absolute counters are available
- Knowledge of expected link parameters: speed, duplex, media type (copper vs
fiber), SFP model, and cable distance
- For optical checks: SFP/QSFP modules with DOM support installed
Procedure
Work through each step sequentially. Early steps collect broad status; later
steps drill into specific failure domains identified by prior output.
Step 1: Interface Status Overview
Collect admin state, operational state, speed, duplex, and media type for all
interfaces under review.
[Cisco]
show interfaces status
show interfaces [intf] | include line protocol|BW|duplex
[JunOS]
show interfaces terse
show interfaces [intf] | match "Physical|Speed|Duplex|Link-level"
[EOS]
show interfaces status
show interfaces [intf] | include line protocol|BW|duplex
Record each interface: name, admin/oper state, speed, duplex, media type. Any
interface that is admin up but operationally down requires immediate
investigation — skip to the Decision Trees section for that interface. Duplex
mismatches (one end full, other half) cause late collisions and must be
resolved before error analysis is meaningful.
Step 2: Error Counter Analysis
Collect error counters and calculate per-interval rates. Raw counters are
cumulative since last clear — always compute a delta over a known interval
(minimum 5 minutes) for actionable rates.
[Cisco]
show interfaces [intf] | include CRC|input errors|output errors|frame|runts|giants
show interfaces [intf] counters errors
[JunOS]
show interfaces [intf] extensive | match "CRC|Errors|Framing|Runts|Giants"
[EOS]
show interfaces [intf] counters errors
show interfaces [intf] | include CRC|input errors|output errors|runts|giants
Key counters to evaluate:
- CRC errors — corrupted frames; indicates physical-layer problems (bad
cable, dirty fiber, failing SFP, EMI)
- Input errors — superset including CRC, frame, overrun; aggregate
indicator of receive-path health
- Output errors — transmission failures; often buffer exhaustion or
interface congestion
- Frame errors — non-integer-octet frames; typically duplex mismatch or
bad NIC
- Runts — undersized frames (<64 bytes); usually collision fragments or
bad NIC
- Giants — oversized frames; MTU mismatch between endpoints
Compare rates against thresholds in references/threshold-tables.md. Any
counter incrementing steadily (not a stale historical value) at Warning level
or above warrants investigation.
Step 3: Discard Analysis
Evaluate input and output discards separately — they have different root
causes.
[Cisco]
show interfaces [intf] | include drops|discard|queue
show policy-map interface [intf]
[JunOS]
show interfaces queue [intf]
show class-of-service interface [intf]
[EOS]
show interfaces [intf] counters discards
show qos interface [intf]
- Output discards — interface transmit ring full. Causes: sustained
congestion (traffic exceeds link capacity), inadequate QoS scheduling,
microbursts overwhelming shallow buffers.
- Input discards — receive ring full. Causes: CPU unable to process at
line rate (control plane punt), input QoS policer drops, or receive buffer
exhaustion.
- Queue drops — per-queue drops visible in QoS policy output. Identify
which traffic class is affected to prioritize remediation.
High output discards with low utilization suggests microburst activity —
short-duration traffic spikes that don't appear in 5-minute utilization
averages but overflow interface buffers.
Step 4: Interface Reset and Flap Detection
Identify interfaces with recent or recurring resets.
[Cisco]
show interfaces [intf] | include resets|Last input|Last output|last change
[JunOS]
show interfaces [intf] extensive | match "Last flapped|Resets"
[EOS]
show interfaces [intf] | include resets|Last input|Last output
show logging | include [intf].*up|[intf].*down
Record reset counts and last-flap timestamps. Correlate flap events with error
counter spikes — a link that flaps and accumulates CRC errors on recovery
likely has a physical-layer issue (loose cable, marginal SFP). Frequent resets
without errors may indicate auto-negotiation failures or spanning-tree
reconvergence triggers.
Threshold: >3 resets/hour is Critical; >10 resets/hour is Emergency. See
references/threshold-tables.md for full severity tiers.
Step 5: Optical Power Monitoring
For fiber interfaces with DOM-capable SFPs, collect Tx power, Rx power, laser
bias current, and module temperature.
[Cisco]
show interfaces [intf] transceiver detail
[JunOS]
show interfaces diagnostics optics [intf]
[EOS]
show interfaces [intf] transceiver detail
Key readings:
- Tx Power (dBm) — transmit optical power. Out-of-range indicates SFP
degradation or failure.
- Rx Power (dBm) — received optical power. Low Rx with normal Tx on the
remote end indicates fiber attenuation (dirty connector, bend loss, distance
exceeded, bad splice).
- Laser Bias Current (mA) — current driving the laser. Rising bias over
time indicates SFP aging; high bias with low Tx power means the SFP is
compensating for degradation.
- Temperature (°C) — module operating temperature. Elevated temperature
accelerates SFP aging and can cause transmission errors.
Compare readings against the per-optic-type tables in
references/threshold-tables.md. The tables provide manufacturer spec ranges
for common SFP types (1G-SX, 10G-SR, 10G-LR, 25G-SR, 100G-SR4).
Step 6: Utilization Assessment
Measure bandwidth usage to identify congested or underutilized links.
[Cisco]
show interfaces [intf] | include input rate|output rate|reliability
show interfaces [intf] summary
[JunOS]
show interfaces [intf] traffic
show interfaces [intf] statistics traffic
[EOS]
show interfaces [intf] | include input rate|output rate
show interfaces [intf] counters rates
Calculate utilization as a percentage of interface speed. Note that CLI
"input/output rate" values are typically 5-minute weighted averages — they
smooth out microbursts. For burst detection, correlate with output discards
(Step 3) and use streaming telemetry or shorter polling intervals if available.
Threshold Tables
Summary of key thresholds used in this skill. Full per-optic-type tables and
detailed severity definitions are in references/threshold-tables.md.
| Metric | Normal | Warning | Critical | Emergency |
|---|
| CRC errors/5min | 0 | 1–5 | 6–50 | >50 |
| Input errors/5min | 0–2 | 3–20 | 21–100 | >100 |
| Output discards/5min | 0–10 | 11–100 | 101–1000 | >1000 |
| Interface resets/hr | 0 | 1–2 | 3–10 | >10 |
| Rx Power vs low-warn | >3 dBm margin | 1–3 dBm margin | 0–1 dBm margin | Below low-alarm |
| Utilization % | 0–50% | 51–75% | 76–90% | >90% |
Decision Trees
High Error Rate
Errors incrementing (CRC, input, frame)
├── Single interface affected?
│ ├── Yes → Physical layer issue
│ │ ├── Fiber interface?
│ │ │ ├── Check Rx power → Low? → Clean connectors, check fiber run
│ │ │ ├── Rx power normal? → Check SFP seating, try reseat
│ │ │ └── SFP temperature high? → Check airflow, replace SFP
│ │ └── Copper interface?
│ │ ├── Check cable length (<100m for Cat6)
│ │ ├── Check for EMI sources near cable run
│ │ └── Swap cable, test with known-good
│ └── No → Multiple interfaces affected
│ ├── Same line card/module? → Suspect line card hardware
│ ├── Same patch panel? → Suspect patch panel or cable tray
│ └── All interfaces? → Upstream power or grounding issue
├── Frame errors specifically?
│ └── Check duplex settings both ends → Mismatch causes late collisions
├── Giants specifically?
│ └── Check MTU both ends → Must match; check for jumbo frame config
└── Runts specifically?
└── Check for collision domain issues or bad NIC on connected device
High Discards
Discards incrementing
├── Output discards?
│ ├── Utilization >75%? → Congestion — consider link upgrade or ECMP
│ ├── Utilization <50% but discards high? → Microburst activity
│ │ ├── Check per-queue drops → Identify affected traffic class
│ │ └── Increase interface buffer or tune QoS scheduling
│ └── QoS policy applied?
│ ├── Check policer/shaper rates → May be too restrictive
│ └── Check queue allocation → Priority queue starving best-effort
├── Input discards?
│ ├── CPU-bound traffic? → Check CoPP counters for punt drops
│ ├── Input policer configured? → Check rate vs actual traffic
│ └── Receive buffer exhaustion → Rare; check for flood traffic
└── Intermittent vs sustained?
├── Sustained → Capacity issue; plan upgrade
└── Intermittent → Burst-driven; tune buffers or QoS
Optical Power Out of Range
Optical reading outside normal range
├── Rx power low?
│ ├── Remote Tx power normal? → Fiber path issue
│ │ ├── Clean both connectors (IPA wipes, not compressed air alone)
│ │ ├── Check for fiber bends exceeding minimum bend radius
│ │ ├── Verify distance within SFP spec (e.g., 10G-SR max 300m OM3)
│ │ └── Test with OTDR if available → Locate fault point
│ └── Remote Tx power also low? → Remote SFP failing
├── Tx power low?
│ ├── Laser bias current high? → SFP degrading, plan replacement
│ ├── Laser bias current normal? → SFP may be misconfigured
│ └── Temperature elevated? → Fix cooling, then recheck Tx power
├── Rx power high?
│ └── Short fiber run without attenuator → Add inline attenuator
└── Temperature alarm?
├── Ambient temp normal? → SFP internal issue, replace
└── Ambient temp high? → Fix chassis/room cooling first
Report Template
INTERFACE HEALTH REPORT
========================
Device: [hostname]
Vendor: [Cisco | JunOS | EOS]
Check Time: [timestamp]
Performed By: [operator/agent]
INTERFACE SUMMARY:
- Total interfaces reviewed: [n]
- Admin Up / Oper Up: [n]
- Admin Up / Oper Down: [n] — [list]
- Interfaces with active errors: [n]
- Interfaces with discards: [n]
FINDINGS:
1. [Severity] [Category] — [Description]
Interface: [name]
Observed: [metric value and rate]
Threshold: [Normal/Warning/Critical/Emergency boundary crossed]
Root Cause: [diagnosis from decision tree]
Action: [recommended remediation]
OPTICAL STATUS:
- Interfaces with DOM data: [n]
- Rx power warnings: [list with dBm values]
- Tx power warnings: [list with dBm values]
- SFPs approaching end-of-life (rising bias current): [list]
UTILIZATION SUMMARY:
- Interfaces >75% utilized: [list with peak and average rates]
- Interfaces >90% utilized: [list — immediate attention required]
RECOMMENDATIONS:
- [Prioritized action list]
NEXT CHECK: [EMERGENCY: 1hr, CRITICAL: 4hr, WARNING: 24hr, NORMAL: 7d]
Troubleshooting
CRC Errors on Fiber with Normal Optical Power
Optical power within spec but CRC errors incrementing. Common causes:
wavelength mismatch between SFP types (e.g., SX connected to LR), dirty
connector on the inside of the SFP cage (not the fiber tip), or SFP
incompatibility with the switch (non-qualified optic). Try: clean the SFP
receptacle, verify both ends use the same SFP type, test with a
vendor-qualified optic.
Output Discards with Low Utilization
Interface shows <30% average utilization but output discards are climbing. This
is almost always microburst traffic — sub-second spikes that exceed link
capacity during the burst but average out below the utilization threshold.
Diagnose with: per-queue drop counters (shows which traffic class), interface
buffer allocation stats. Remediate with: QoS scheduling adjustments, increased
interface buffer depth, or traffic shaping at the ingress point.
Interface Stuck in Down/Down After Cable Swap
Admin up, operationally down after replacing a cable or SFP. Check: SFP is
fully seated (push firmly until click), fiber polarity is correct (Tx-to-Rx
crossover), SFP type matches remote end, speed/duplex is set to auto or
matches. On [Cisco], check show interfaces [intf] | include err-disabled
— the port may have been error-disabled by a protection feature (BPDU guard,
UDLD, link-flap detection). Recover with shutdown / no shutdown after
fixing the root cause.
Flapping Interface with No Errors
Interface cycles up/down every few seconds with zero error counters. This
suggests a negotiation or protocol issue, not a physical fault. Common causes:
auto-negotiation incompatibility (force speed/duplex on both ends), STP
topology changes causing repeated blocking/forwarding transitions, UDLD
aggressive mode detecting unidirectional link. Check spanning-tree state and
UDLD status on the interface.
Rising Laser Bias with Stable Tx Power
Laser bias current increasing over weeks/months while Tx power remains stable.
The SFP is compensating for laser degradation by driving more current. This is
normal aging but indicates the SFP will eventually fail — Tx power will drop
when the laser can no longer compensate. Plan proactive replacement before the
Tx power begins declining. Track the trend: if bias current exceeds 80% of the
manufacturer's max specification, schedule replacement within 30 days.
