Prometheus Metrics

Prometheus Metrics

Since v2026-03-03 -- DOCSight exposes a /metrics endpoint in Prometheus text exposition format for integration with Prometheus, Grafana, and other monitoring systems.

Quick Start

curl -s http://localhost:8765/metrics

No configuration required. The endpoint is always available and reads from in-memory state -- it never triggers modem queries.

Endpoint Details

Property	Value
Path	GET /metrics
Auth	Not required (same as /health)
Content-Type	text/plain; version=0.0.4; charset=utf-8
Response time	< 5 ms (in-memory only)

The endpoint works without authentication even when an admin password is configured. POST requests return 405 Method Not Allowed.

Metrics Reference

Health & Summary

Metric	Type	Description
docsight_health_status	gauge	Overall signal health: 0=good, 1=tolerated, 2=marginal, 3=critical
docsight_downstream_channels_total	gauge	Number of active downstream channels
docsight_upstream_channels_total	gauge	Number of active upstream channels

Downstream Channels

All downstream metrics use channel_id and frequency labels. The frequency label is normalized to MHz (e.g. 474000000 → 474, 44 MHz → 44). It is omitted when the modem does not report a frequency.

Metric	Type	Description
docsight_downstream_power_dbmv	gauge	Receive power level in dBmV
docsight_downstream_snr_db	gauge	Signal-to-noise ratio in dB
docsight_downstream_corrected_errors_total	counter	Correctable codeword errors (cumulative)
docsight_downstream_uncorrected_errors_total	counter	Uncorrectable codeword errors (cumulative)
docsight_downstream_modulation	gauge	QAM modulation order (e.g. 256 for 256-QAM, 4096 for OFDM)

Upstream Channels

All upstream metrics use channel_id and frequency labels (same normalization as downstream).

Metric	Type	Description
docsight_upstream_power_dbmv	gauge	Transmit power level in dBmV
docsight_upstream_modulation	gauge	QAM modulation order (e.g. 64 for 64-QAM)

Device Information

Metric	Type	Labels	Description
docsight_device_info	gauge	model, sw_version	Always 1 when device info is available
docsight_device_uptime_seconds	gauge	--	Modem uptime in seconds

Connection Information

Metric	Type	Description
docsight_connection_max_downstream_kbps	gauge	Maximum downstream speed in kbps (from modem)
docsight_connection_max_upstream_kbps	gauge	Maximum upstream speed in kbps (from modem)

Polling

Metric	Type	Description
docsight_last_poll_timestamp_seconds	gauge	Unix epoch timestamp of last successful poll

Example Output

# HELP docsight_health_status DOCSIS signal health status: 0=good 1=tolerated 2=marginal 3=critical
# TYPE docsight_health_status gauge
docsight_health_status 0

# HELP docsight_downstream_channels_total Number of active downstream channels
# TYPE docsight_downstream_channels_total gauge
docsight_downstream_channels_total 33

# HELP docsight_upstream_channels_total Number of active upstream channels
# TYPE docsight_upstream_channels_total gauge
docsight_upstream_channels_total 4

# HELP docsight_downstream_power_dbmv Downstream channel receive power level in dBmV
# TYPE docsight_downstream_power_dbmv gauge
docsight_downstream_power_dbmv{channel_id="1",frequency="474"} 3.2
docsight_downstream_power_dbmv{channel_id="2",frequency="482"} 4.5

# HELP docsight_downstream_snr_db Downstream channel signal-to-noise ratio in dB
# TYPE docsight_downstream_snr_db gauge
docsight_downstream_snr_db{channel_id="1",frequency="474"} 38.5
docsight_downstream_snr_db{channel_id="2",frequency="482"} 39.0

# HELP docsight_device_info Device information (model, firmware version)
# TYPE docsight_device_info gauge
docsight_device_info{model="FRITZ!Box 6690 Cable",sw_version="7.57"} 1

# HELP docsight_last_poll_timestamp_seconds Unix timestamp of the last successful modem data poll
# TYPE docsight_last_poll_timestamp_seconds gauge
docsight_last_poll_timestamp_seconds 1709500800.0

Prometheus Configuration

Add DOCSight as a scrape target in your prometheus.yml:

scrape_configs:
  - job_name: 'docsight'
    static_configs:
      - targets: ['localhost:8765']
    metrics_path: '/metrics'
    scrape_interval: 30s

Adjust targets to match your DOCSight host (e.g. 192.168.178.15:8765 if running on a NAS).

Grafana Dashboard

Use docsight_* metrics to build Grafana dashboards. Some useful panels:

Health status over time:

docsight_health_status

Downstream power range:

min(docsight_downstream_power_dbmv)
max(docsight_downstream_power_dbmv)

Error rate (uncorrectable per hour):

increase(docsight_downstream_uncorrected_errors_total[1h])

Time since last poll:

time() - docsight_last_poll_timestamp_seconds

Example Alerts

groups:
  - name: docsight
    rules:
      - alert: DocSightHealthDegraded
        expr: docsight_health_status > 0
        for: 5m
        annotations:
          summary: "DOCSIS signal health degraded (status={{ $value }})"

      - alert: HighUncorrectableErrors
        expr: increase(docsight_downstream_uncorrected_errors_total[1h]) > 100
        for: 5m
        annotations:
          summary: "High uncorrectable error rate on channel {{ $labels.channel_id }}"

      - alert: DocSightPollingStalled
        expr: (time() - docsight_last_poll_timestamp_seconds) > 3600
        for: 5m
        annotations:
          summary: "DOCSight hasn't polled modem in over 1 hour"

Edge Cases

• No data yet (modem not polled): docsight_health_status returns 3 (unknown), channel metrics are omitted, docsight_last_poll_timestamp_seconds returns 0.0. HTTP status is still 200 with valid Prometheus output.
• Generic Router mode: No downstream/upstream channel metrics are emitted. Health, device info, connection info, and poll timestamp are still available.
• Null values: Channel metrics with null power or SNR are silently skipped. Unparseable modulation strings are omitted. The output is always valid Prometheus format.