Automatically retrieve device's room/function from CCU and pass as labels

[flammermann]

• Instead of just names, also get rooms and functions for channels.
• Aggregate rooms and functions to device level.
• Make aggregated rooms and functions available as metric labels.
• Change names of command line arguments to match new definition. [breaking change]
• Change keys of labels to make usage clearer. [breaking change]
• Add documentation in README.
• Update sample configuration to show expected format.

[sfudeus]

Oh, interesting one, thx for the contribution, I'll have a look, just not sure when I get to it. Don't hesitate to nudge me again if it takes too long.

[flammermann]

Labels for channels and devices

After fiddling around in Grafana a bit, I got a better understanding of parent device and device. Which makes sense because it is coming like that from XML RPC. From XML RPC you get

• either a device with a parent device -> in this case device = channel and parent device = device in the wording of CCU UI and HomeMatic Script Language
• or a device without a parent device -> in this case device = device in the wording of CCU UI and HomeMatic Script Language

The way this exporter is written, only metrics for devices with parent device are created. device without parent device are only used for logging and nothing else.

Therefore, I adjusted the naming of labels again to properly reflect which information belong to a channel which to a device. Also I differentiated the room and the function information for those two.

There are now the following metric labels:

• ccu (unchanged)
• channel_address (changed, used to be called device)
• channel_type (changed, used to be called device_type)
• channel_id (new, from the enhanced device mapping)
• channel_name (new, from the enhanced device mapping)
• channel_room_id (new, from the enhanced device mapping, there could be multiple rooms configured, this uses the first)
• channel_room_name (new, from the enhanced device mapping, there could be multiple rooms configured, this uses the first)
• channel_function_id (new, from the enhanced device mapping, there could be multiple functions configured, this uses the first)
• channel_function_name (new, from the enhanced device mapping, there could be multiple functions configured, this uses the
• device_address (new, the information was already available from the XML RPC but just not used)
• device_type (changed, used to be called parent_device_type)
• device_id (new, from the enhanced device mapping)
• device_name (changed, used to be called mapped_name)
• device_room_id (new, from the enhanced device mapping, there could be multiple rooms configured, this uses the most common one across all channels)
• device_room_name (new, from the enhanced device mapping, there could be multiple rooms configured, this uses the most common one across all channels)
• device_function_id (new, from the enhanced device mapping, there could be multiple functions configured, this uses the most common one across all channels)
• device_function_name (new, from the enhanced device mapping, there could be multiple functions configured, this uses the most common one across all channels)

Remove old metrics during runtime after mapping refresh

All these new labels make an already existing issue #30 more apparent. Whenever anything changes about this mapping/configuration of any channel/device, the old metric stays existent with the same value. This same value is scraped by Prometheus until eternity.

The second commit addresses this issue. Not 100% happy with the solution, but it works. The only downside is that the metric is unavailable for all devices (also those that are still existent) for a short period of time after resetting it. This means that in the time between reset and recreation of the metric for each device, the scrape from Prometheus would not find anything. This in turn causes missing values in Prometheus, but only if Prometheus scrapes exactly in those few second between reset and recreate. I checked in my own setup and I don't care about those few missing values.

If you have a better solution to this problem, feel free to adjust the code! I am sure there is, I just didn't have the time to find it.

[flammermann]

Update: Remove old metrics during runtime after mapping refresh

Found a better solution to this problem. Now I am storing all metrics that were added during a run and then every time the device mapping is refreshed all metrics in all collectors stored in self.metrics that are not in the list of metrics from the previous run, are removed from that collector.

before the whole collectors were removed from the registry, now only unused metrics are removed from the collectors. This still solves #30 but without the drawback of the earlier implementation (see comment above).