econet-exporter/pkg/econet/econetmetrics/gauges.go

package econetmetrics

import (
	"context"

	rheemcloud "github.com/kevinburke/rheemcloud-go"
	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/metric"
)

// registerLive wires the per-device live-state gauges to a single callback
// that snapshots client.Devices() once per scrape (cheap, in-memory).
func (c *Collector) registerLive() error {
	b := &gaugeBuilder{m: c.meter}
	g := &liveGauges{
		setpoint:    b.i64("econet_setpoint_fahrenheit", "Target water temperature (°F)"),
		setpointMin: b.i64("econet_setpoint_min_fahrenheit", "Minimum allowed setpoint (°F)"),
		setpointMax: b.i64("econet_setpoint_max_fahrenheit", "Maximum allowed setpoint (°F)"),
		connected:   b.i64("econet_connected", "1 if the device is connected"),
		running:     b.i64("econet_running", "1 if the device is actively heating"),
		enabled:     b.i64("econet_enabled", "1 if the device is enabled"),
		away:        b.i64("econet_away", "1 if away mode is on"),
		hotWater:    b.i64("econet_hot_water_availability_percent", "Hot water availability (%)"),
		alerts:      b.i64("econet_alert_count", "Number of active alerts"),
		wifi:        b.i64("econet_wifi_signal_db", "WiFi signal strength (dB)"),
		lastUpdated: b.i64("econet_last_updated_seconds", "Unix time of last MQTT state update"),
		info:        b.i64("econet_device_info", "Device metadata (value is always 1)"),
	}
	if b.err != nil {
		return b.err
	}
	_, err := c.meter.RegisterCallback(func(_ context.Context, o metric.Observer) error {
		for _, d := range c.client.Devices() {
			g.observe(o, d)
		}
		return nil
	}, b.obs...)
	return err
}

// registerUsage wires the polled energy/water gauges, reading the cache the
// poller refreshes (the underlying REST calls are too slow for a callback).
func (c *Collector) registerUsage() error {
	b := &gaugeBuilder{m: c.meter}
	g := &usageGauges{
		energy: b.f64("econet_energy_usage_kwh", "Energy used today (kWh)"),
		cost:   b.f64("econet_energy_cost_dollars", "Energy cost today in US dollars (kWh * costPerKWH)"),
		water:  b.f64("econet_water_usage_gallons", "Water used today (gallons)"),
	}
	if b.err != nil {
		return b.err
	}
	_, err := c.meter.RegisterCallback(func(_ context.Context, o metric.Observer) error {
		c.mu.RLock()
		defer c.mu.RUnlock()
		for serial, u := range c.usage {
			g.observe(o, serial, u, c.cfg.CostPerKWH)
		}
		return nil
	}, b.obs...)
	return err
}

type liveGauges struct {
	setpoint, setpointMin, setpointMax  metric.Int64ObservableGauge
	connected, running, enabled, away   metric.Int64ObservableGauge
	hotWater, alerts, wifi, lastUpdated metric.Int64ObservableGauge
	info                                metric.Int64ObservableGauge
}

func (g *liveGauges) observe(o metric.Observer, d *rheemcloud.Device) {
	set := metric.WithAttributes(deviceAttrs(d)...)
	min, max := d.SetpointLimits()
	o.ObserveInt64(g.setpoint, int64(d.Setpoint()), set)
	o.ObserveInt64(g.setpointMin, int64(min), set)
	o.ObserveInt64(g.setpointMax, int64(max), set)
	o.ObserveInt64(g.connected, b2i(d.Connected()), set)
	o.ObserveInt64(g.running, b2i(d.Running()), set)
	o.ObserveInt64(g.enabled, b2i(d.Enabled()), set)
	o.ObserveInt64(g.away, b2i(d.Away()), set)
	o.ObserveInt64(g.hotWater, int64(d.HotWaterAvailability()), set)
	o.ObserveInt64(g.alerts, int64(d.AlertCount()), set)
	o.ObserveInt64(g.wifi, int64(d.WiFiSignal()), set)
	// LastUpdated is zero until the first MQTT update lands; skip it then
	// rather than emit a nonsensical negative epoch.
	if !d.LastUpdated.IsZero() {
		o.ObserveInt64(g.lastUpdated, d.LastUpdated.Unix(), set)
	}
	o.ObserveInt64(g.info, 1, metric.WithAttributes(infoAttrs(d)...))
}

type usageGauges struct {
	energy, cost, water metric.Float64ObservableGauge
}

func (g *usageGauges) observe(o metric.Observer, serial string, u usage, costPerKWH float64) {
	set := metric.WithAttributes(attribute.String("econet.serial", serial))
	o.ObserveFloat64(g.energy, u.energyKWH, metric.WithAttributes(
		attribute.String("econet.serial", serial),
		attribute.String("econet.energy_type", u.energyType),
	))
	o.ObserveFloat64(g.water, u.waterGallons, set)
	if u.energyType == "KWH" {
		o.ObserveFloat64(g.cost, u.energyKWH*costPerKWH, set)
	}
}

// deviceAttrs are low-cardinality identity attributes safe for every series.
// They follow OTEL semantic-convention style (namespaced, dotted keys) and
// deliberately exclude anything that changes over time (e.g. timestamps).
func deviceAttrs(d *rheemcloud.Device) []attribute.KeyValue {
	return []attribute.KeyValue{
		attribute.String("econet.serial", d.SerialNumber()),
		attribute.String("econet.device_id", d.DeviceID()),
		attribute.String("econet.friendly_name", d.FriendlyName()),
	}
}

func infoAttrs(d *rheemcloud.Device) []attribute.KeyValue {
	return append(deviceAttrs(d),
		attribute.String("econet.type", d.Type().String()),
		attribute.String("econet.generic_type", d.GenericType()),
		attribute.String("econet.mode", d.Mode().String()),
	)
}

func b2i(b bool) int64 {
	if b {
		return 1
	}
	return 0
}