search

mbugert / connectbox-prometheus

Prometheus exporter for Compal CH7465LG cable modems, commonly sold as "Connect Box"
Apache License 2.0
49 stars 9 forks source link
cable-modem connect-box prometheus prometheus-exporter pypi router unitymedia upc virgin-media ziggo

readme

Connectbox Prometheus

PyPI - License PyPI - Python Version PyPI Code style: black

A Prometheus exporter for monitoring Compal CH7465LG cable modems. These are sold under the name "Connect Box" by Unitymedia in Germany, Ziggo in the Netherlands and UPC in Switzerland/Austria/Poland. Or as "Virgin Media Super Hub 3" by Virgin Media.

Makes thorough use of compal_CH7465LG_py by @ties (thanks!).

Installation

On your Prometheus server host:

Using pip

  1. Create a virtual environment using python3.7 or higher
  2. Install the exporter via pip install connectbox-prometheus

Using Docker

Alternatively you could use the provided Dockerfile. We don't provide builds on Docker Hub or similar, so you need to git clone and build it yourself:

git clone https://github.com/mbugert/connectbox-prometheus.git

cd connectbox-prometheus

Choose either docker run or docker-compose.

docker run

To build your own local docker image run docker build -t connectbox-prometheus .

To actually create and run a container named connectbox-prometheus use the following command:

docker run -v connectbox-prometheus-volume:/data -p 9705:9705 --name connectbox-prometheus connectbox-prometheus

The example config.yml found in the root of this repo will be copied to the provided /data volume (e.g. connectbox-prometheus-volume, usually found under /var/lib/docker/volumes/connectbox-prometheus-volume and the container will stop, because you most likely need to modify the given config. See Usage.

After modifying, run docker start connectbox-prometheus to keep the container running.

docker-compose

docker-compose up will automatically build the docker image, start the container the first time to copy the example config.yml and exit again. Now there should be an directory named data where you can find your config.yml. Modify it to your needs. See Usage.

After modifying, run docker-compose up -d to keep the container running.

Usage

This exporter queries exactly one Connect Box as a remote target. To get started, modify config.yml from this repository or start out with the following content:

# Connect Box IP address
ip_address: 192.168.0.1

# Connect Box web interface password
password: WhatEverYourPasswordIs

Then run connectbox_exporter path/to/your/config.yml .

Prometheus Configuration

Add the following to your prometheus.yml:

scrape_configs:
  - job_name: 'connectbox'
    static_configs:
      - targets:
        - localhost:9705

One scrape takes roughly 6 seconds.

Exported Metrics

Metric name Description
connectbox_device_info Assorted device information
connectbox_provisioning_status Modem provisioning status
connectbox_uptime_seconds Device uptime in seconds
connectbox_tuner_temperature_celsius Tuner temperature
connectbox_temperature_celsius Temperature
connectbox_ethernet_client_speed_mbit Maximum speed of connected ethernet clients
connectbox_wifi_client_speed_mbit Maximum speed of connected Wi-Fi clients
connectbox_downstream_frequency_hz Downstream channel frequency
connectbox_downstream_power_level_dbmv Downstream channel power level
connectbox_downstream_snr_db Downstream channel signal-to-noise ratio (SNR)
connectbox_downstream_rxmer_db Downstream channel receive modulation error ratio (RxMER)
connectbox_downstream_codewords_unerrored_total Unerrored downstream codewords
connectbox_downstream_codewords_corrected_total Corrected downstream codewords
connectbox_downstream_codewords_uncorrectable_total Uncorrectable downstream codewords
connectbox_upstream_frequency_hz Upstream channel frequency
connectbox_upstream_power_level_dbmv Upstream channel power level
connectbox_upstream_symbol_rate_ksps Upstream channel symbol rate
connectbox_upstream_timeouts_total Upstream channel timeout occurrences
connectbox_scrape_duration_seconds Connect Box exporter scrape duration
connectbox_up Connect Box exporter scrape success

Grafana Dashboard

The above metrics can be monitored nicely in Grafana using this dashboard:

Grafana Dashboard

Contributing / Development

Pull requests are welcome. 😊

To install development dependencies, run:

pip install -r resources/requirements/development.txt