A Prometheus exporter for Juniper Mist API metrics.
This exporter collects metrics from the Mist API, focusing on the operational state of wireless devices (APs) and their connected clients. It is designed for organizations using Prometheus and Grafana to monitor their Juniper Mist wireless environment.
- Hybrid Data Collection: Uses a combination of real-time streaming and periodic scraping for efficiency and data freshness.
- Real-time Streaming: Leverages the Mist WebSocket API to stream high-frequency updates for device (AP) and client statistics.
- Periodic Scraping: Gathers organization-level metrics (e.g., alarm/ticket counts) during each Prometheus scrape.
- Automatic Org ID Discovery: Automatically discovers the Organization ID from the API key if not specified, simplifying configuration.
- Dynamic Site Management: Automatically discovers new sites and stops collecting metrics for sites that are removed from the organization.
- Configurable via YAML file or environment variables.
- Graceful shutdown and robust server lifecycle management.
The exporter employs a hybrid strategy to gather metrics efficiently:
-
Streaming (WebSocket): On startup, the exporter establishes a WebSocket connection to the Mist API for each site in the organization. It subscribes to real-time updates for device (AP) and client statistics. These metrics are held in memory and are served instantly when Prometheus scrapes the exporter. This provides near real-time data without overwhelming the REST API.
-
Scraping (REST API): For less volatile, organization-wide data (like the total number of sites or the count of open alarms), the exporter queries the Mist REST API directly at the time of the Prometheus scrape.
- A Juniper Mist API token with at least
Read-Onlyaccess to your organization. You can generate one from the Mist Dashboard underMy Account > API Tokens. - Go 1.21+ (for building from source).
- Docker (for running as a container).
The exporter is configured via a config.yaml file.
---
# Mist Prometheus Exporter Configuration
# The ID of the Mist Organization to scrape.
# If omitted, the exporter will attempt to discover it from the API key.
# This is required if the API key has access to multiple organizations.
# Can be set with MIST_ORG_ID environment variable.
org_id: "${MIST_ORG_ID}"
mist_api:
# Mist API base URL.
base_url: "https://api.mist.com"
# Mist API token for authentication.
# It is strongly recommended to set this via an environment variable.
api_key: "${MIST_API_KEY}"
# Timeout for individual REST API requests.
timeout: 10s
exporter:
# Exporter bind address.
address: 0.0.0.0
# Port on which to expose the /metrics endpoint.
port: 10038
collector:
# Timeout for the REST API portion of a Prometheus scrape. This should be
# less than your Prometheus scrape_timeout setting.
collect_timeout: 15s
# Enable scrape-time organization metrics (REST API): mist_org_*
# default is true
enable_org_metrics: true
# Enable scrape-time site metrics (REST API): mist_site_*
# default is true
enable_site_metrics: true
# Enable streaming client metrics: mist_client_*
# default is true
enable_client_metrics: true
# How often to update device MAC to name mappings for the organization.
device_name_refresh_interval: 1m
# How often to check for new or removed sites in the organization.
site_refresh_interval: 1m
# Optional: Filter which sites to collect metrics from.
# The filter will match site names using glob patterns and is case-sensitive.
# 'include' sites with names matching the glob patterns, exlude all others.
# 'exclude' sites with names matching the glob patterns, include all others.
# If a site matches both include and exclude, it will be excluded.
# See [here](https://pkg.go.dev/path/filepath#Match) for an explanation of the supported pattern syntax.
site_filter:
include:
- "US-*"
- "EU-*"
exclude:
- "*-Test"A Docker image can be used to run the exporter.
- Create your
config.yaml. - Run the container:
docker run -d \
--name mistexporter \
-p 10038:10038 \
-v $(pwd)/config.yaml:/app/config.yaml \
<your-docker-image-name>:latest- Clone the repository:
git clone https://github.com/gregwight/mistexporter.git cd mistexporter - Build the binary:
go build -o mistexporter ./cmd/main.go
- Run the exporter:
./mistexporter --config config.yaml
Pre-built binaries for major platforms (Linux, Windows, macOS) are available on the project's GitHub Releases page. The release archives contain the exporter binary and an example config.yaml.
This is the recommended way to deploy the exporter without setting up a Go development environment.
Example for Linux:
# Replace <version> with the latest release version (e.g., v1.0.0)
VERSION="<latest_version>"
ARCH="amd64" # or arm64
# Download and extract the release archive
curl -sSL https://github.com/gregwight/mistexporter/releases/download/${VERSION}/mistexporter-${VERSION}-linux-${ARCH}.tar.gz | tar -xz
# Copy the example config and edit it with your API key and org ID
cp config.yaml.dist config.yaml
vim config.yaml # Or your favorite editor
# Run the exporter
./mistexporter --config config.yamlTo run the Mist exporter as a long-running service on a Linux system with systemd, you can create a unit file. This ensures the exporter starts on boot and is restarted if it fails.
-
Install the exporter: Follow the steps in "Running from a Pre-built Binary" to download and extract the exporter. Then, move the files to standard locations.
sudo mv mistexporter /usr/local/bin/ sudo mkdir -p /etc/mistexporter sudo mv config.yaml /etc/mistexporter/ sudo chmod +x /usr/local/bin/mistexporter
-
Create a dedicated user (Recommended): It is a security best practice to run services as a non-root user.
sudo useradd --no-create-home --shell /bin/false prometheus sudo chown -R prometheus:prometheus /etc/mistexporter
-
Create the systemd unit file: Create a file at
/etc/systemd/system/mistexporter.servicewith the following content:[Unit] Description=Mist Prometheus Exporter Wants=network-online.target After=network-online.target [Service] User=prometheus Group=prometheus Type=simple ExecStart=/usr/local/bin/mistexporter --config /etc/mistexporter/config.yaml Restart=on-failure [Install] WantedBy=multi-user.target
-
Enable and start the service:
# Reload the systemd daemon to recognize the new service sudo systemctl daemon-reload # Enable the service to start on boot sudo systemctl enable mistexporter.service # Start the service now sudo systemctl start mistexporter.service # Check the status sudo systemctl status mistexporter.service
The exporter exposes the following metrics at the /metrics endpoint.
These metrics are fetched from the Mist REST API each time Prometheus scrapes the exporter. They are suitable for data that changes infrequently.
| Metric | Description | Type |
|---|---|---|
mist_org_alarms |
The total number of alarms in the organization. | Counter |
mist_org_tickets |
The total number of tickets in the organization. | Counter |
| Metric | Description | Type |
|---|---|---|
mist_site_modified_time |
The last time site was modified, as a Unix timestamp. | Gauge |
mist_site_num_ap |
Total number of APs configured for the site. | Gauge |
mist_site_num_ap_connected |
Number of APs currently online at the site. | Gauge |
mist_site_num_clients |
Total number of clients currently connected to the site. | Gauge |
mist_site_num_devices |
Total number of Mist devices (APs, switches, gateways) at the site. | Gauge |
mist_site_num_devices_connected |
Number of Mist devices (APs, switches, gateways) currently online at the site. | Gauge |
mist_site_num_gateway |
Total number of gateways configured for the site. | Gauge |
mist_site_num_gateway_connected |
Number of gateways currently online at the site. | Gauge |
mist_site_num_switch |
Total number of switches configured for the site. | Gauge |
mist_site_num_switch_connected |
Number of switches currently online at the site. | Gauge |
These metrics are continuously updated in the background via a WebSocket connection to the Mist API. This provides the most up-to-date information for dynamic operational data.
All device metrics are gauges and share a common set of labels identifying the site and device (site_name, device_name). Metrics specific to a radio also include a radio label (e.g., 2.4GHz, 5GHz).
| Metric | Description | Type |
|---|---|---|
mist_device_cpu_utilization_system_percent |
Current system CPU utilization of the device. | Gauge |
mist_device_cpu_utilization_idle_percent |
Current idle CPU utilization of the device. | Gauge |
mist_device_cpu_utilization_interrupt_percent |
Current interrupt CPU utilization of the device. | Gauge |
mist_device_cpu_utilization_user_percent |
Current user CPU utilization of the device. | Gauge |
mist_device_last_seen_timestamp_seconds |
The last time the device was seen, as a Unix timestamp. | Gauge |
mist_device_load_average_1m |
Current 1m load average of the device. | Gauge |
mist_device_load_average_5m |
Current 5m load average of the device. | Gauge |
mist_device_load_average_15m |
Current 15m load average of the device. | Gauge |
mist_device_memory_utilization_percent |
Current memory utilization of the device. | Gauge |
mist_device_receive_bits_per_second |
Bits per second received by the device. | Gauge |
mist_device_transmit_bits_per_second |
Bits per second transmitted by the device. | Gauge |
mist_device_uptime_seconds |
Device uptime in seconds. | Gauge |
mist_device_radio_bandwidth_mhz |
Radio channel bandwidth in MHz. | Gauge |
mist_device_radio_channel |
The current radio channel. | Gauge |
mist_device_radio_clients |
Number of clients connected to this radio. | Gauge |
mist_device_radio_receive_bytes |
Total bytes received by the radio. | Gauge |
mist_device_radio_receive_packets |
Total packets received by the radio. | Gauge |
mist_device_radio_transmit_bytes |
Total bytes transmitted by the radio. | Gauge |
mist_device_radio_transmit_packets |
Total packets transmitted by the radio. | Gauge |
mist_device_radio_transmit_power_dbm |
The radio's transmit power in dBm. | Gauge |
All client metrics are gauges and share a common set of labels identifying the site, client, and connection details (site_name, device_name, device_mac, client_mac, client_username, client_hostname, client_os, client_manufacturer, client_family, client_model, device_id, proto, radio, ssid).
| Metric | Description | Type |
|---|---|---|
mist_client_channel |
The channel the client is connected on. | Gauge |
mist_client_dual_band_capable |
Whether the client is dual-band capable (1 for true, 0 for false). | Gauge |
mist_client_idle_seconds |
Time in seconds since the client was last active. | Gauge |
mist_client_is_guest_status |
Whether the client is a guest user (1 for true, 0 for false). | Gauge |
mist_client_last_seen_timestamp_seconds |
The last time the client was seen, as a Unix timestamp. | Gauge |
mist_client_locating_aps |
The number of APs that can hear the client. | Gauge |
mist_client_power_saving_mode_active |
Whether the client is in power-saving mode (1 for true, 0 for false). | Gauge |
mist_client_receive_bits_per_second |
Bits per second received from the client. | Gauge |
mist_client_receive_bytes |
Total bytes received from the client. | Gauge |
mist_client_receive_packets |
Total packets received from the client. | Gauge |
mist_client_receive_rate_mbps |
The receive data rate in Mbps. | Gauge |
mist_client_receive_retries |
Total number of receive retries. | Gauge |
mist_client_rssi_dbm |
The client's Received Signal Strength Indicator in dBm. | Gauge |
mist_client_snr_db |
The client's Signal-to-Noise Ratio in dB. | Gauge |
mist_client_transmit_bits_per_second |
Bits per second transmitted to the client. | Gauge |
mist_client_transmit_bytes |
Total bytes transmitted to the client. | Gauge |
mist_client_transmit_packets |
Total packets transmitted to the client. | Gauge |
mist_client_transmit_rate_mbps |
The transmit data rate in Mbps. | Gauge |
mist_client_transmit_retries |
Total number of transmit retries. | Gauge |
mist_client_uptime_seconds |
The client's session uptime in seconds. | Gauge |
Contributions are welcome! Please see CONTRIBUTING.md for details.
This project is licensed under the Apache 2.0 License. See the LICENSE file for details.