cisco-wnc-exporter

A third-party Prometheus Exporter for Cisco C9800 Wireless Network Controller.

Overview

This exporter allows a Prometheus instance to scrape metrics from Cisco Catalyst 9800 Wireless Controllers.

• 🛡️ State Monitoring: Detects misconfigured APs and the enabled/disabled states of APs, radios and WLANs
• 🌐 Connectivity Tracking: Tracks client signal, speed, protocol, traffic, latency and associating APs
• 📊 Long-Term Observability: Extends metric retention beyond the builtin implementation
• ↩️ Pull-Based Telemetry: Scrapes via RESTCONF instead of push-based Streaming Telemetry

Architecture

Prometheus pulls from the exporter, and the exporter pulls from the controller on its own schedule.

flowchart TB
    P["Prometheus"] -- "scrapes /metrics" --> E
    subgraph E ["cisco-wnc-exporter"]
        M(["/metrics"])
        I[["Info cache<br>--collector.info-cache-ttl"]]
        S[["WNC data cache<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--wnc.cache-ttl&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"]]
        M -- "_info series" --> I
        M -- "other series" --> S
    end
    E -- "refreshes" --> R
    E -- "refreshes" --> C
    subgraph W ["Cisco C9800 RESTCONF"]
        R[("&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ap_radio_oper_data&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;")]
        C[("client_common_oper_data")]
    end

Supported Environment

Cisco Catalyst 9800 Wireless Network Controller running on:

• Cisco IOS-XE 17.12.5 or later – Last verified on 17.12.8
• Cisco IOS-XE 17.15.6 or later – Last verified on 17.15.6
• Cisco IOS-XE 17.18.4a or later – Last verified on 17.18.4a

Installation

This exporter supports container images and OS-specific binaries.

docker pull ghcr.io/umatare5/cisco-wnc-exporter

Or, download the binaries from Releases. (linux|darwin)_(amd64|arm64) and windows_amd64 are supported.

Quick Start

This exporter requires RESTCONF and HTTPS to be enabled on the Cisco Catalyst 9800 beforehand.

See the Programmability Configuration Guide, Cisco IOS XE 17.15.x - RESTCONF for enabling them.

1. Generate a Basic Auth token

# username:password → Base64 Encode
echo -n "admin:your-password" | base64
# Output: YWRtaW46eW91ci1wYXNzd29yZA==

2. Set the environment variables

export WNC_CONTROLLER="wnc1.example.internal"
export WNC_ACCESS_TOKEN="YWRtaW46eW91ci1wYXNzd29yZA=="

3. Run the exporter with Docker

docker run -p 10039:10039 -e WNC_CONTROLLER -e WNC_ACCESS_TOKEN \
  ghcr.io/umatare5/cisco-wnc-exporter:v0.15.1 --collector.ap.general

4. Scrape the metrics

curl http://localhost:10039/metrics

Configuration

This exporter uses command-line flags for all configuration.

Flags

cisco-wnc-exporter --help prints full flags. See Help for details.

Collectors

The --collector.* flags toggle these collectors. See the pages below for details.

Endpoints

The exporter exposes these endpoints. See Endpoints for what each status code means.

Metrics

This exporter exposes metrics for various aspects of the wireless network.

Collector Metrics

The following table summarizes the popular metrics. See Collectors for the complete metrics.

Exporter Health Metrics

The following table summarizes the health metrics of the exporter itself. See Exporter Health for details.

Examples

There are several operational examples below.

Exporter Configuration

The three patterns below cover the common use cases.

Minimal Pattern: By default, the exporter publishes wnc_build_info alone.

./cisco-wnc-exporter

Standard Pattern: The three general groups cover the APs, the clients and the WLANs.

./cisco-wnc-exporter --collector.ap.general --collector.client.general --collector.wlan.general

Complete Pattern: Every group registers, and each --collector.*.info-labels flag takes its widest set.

./cisco-wnc-exporter \
  --collector.ap.general \
    --collector.ap.radio --collector.ap.traffic --collector.ap.errors \
    --collector.ap.join --collector.ap.geolocation --collector.ap.spectrum \
    --collector.ap.info \
    --collector.ap.info-labels "name,ip,band,model,serial,sw_version,eth_mac" \
  --collector.client.general \
    --collector.client.radio --collector.client.traffic --collector.client.errors \
    --collector.client.info \
    --collector.client.info-labels "ap,band,wlan,wlan_id,name,device_type,username,ipv4,ipv6" \
  --collector.wlan.general \
    --collector.wlan.traffic --collector.wlan.config \
    --collector.wlan.info \
    --collector.wlan.info-labels "name" \
  --collector.controller.general

Prometheus Configuration

See the following Prometheus configuration examples:

• Example Job: Add from examples/prometheus.yml to your Prometheus.
• Example Alerting Rules: Add from examples/prometheus_alert_rules.yml to your Prometheus.

Grafana Dashboard

Two layer of dashboards are available: The admin-level dashboard and the user-level dashboard

Admin-level: Import examples/grafana_cisco-wnc-exporter-admin-dashboard.json and visualize the metrics.

User-level: Import examples/grafana_cisco-wnc-exporter-user-dashboard.json and visualize the metrics.

Documentation

The following pages detail additional information.

• Architecture – the scrape path, the absence rules and the design principles.
• Enumeration Values – the number each enumerated family reports.

Contributing

See CONTRIBUTING.md for development setup, test conventions and others.

License

MIT. The binary statically links Apache-2.0, MIT and BSD 3-Clause dependencies. Their notices are reproduced in NOTICE and shipped alongside LICENSE in every release archive and container image.