-
Notifications
You must be signed in to change notification settings - Fork 0
Debugging
When something looks wrong, there are two things you can hand over: a diagnostics report and a debug log.
A diagnostics report is a snapshot of what the integration currently knows — which meters it found, what units it resolved them to, whether the last update succeeded. It takes one click and never contains your password.
A debug log is a recording of what the integration did over a period of time. You need it when the snapshot looks fine but something still misbehaves, or when the integration fails before there is anything to snapshot.
| What you're seeing | What to attach |
|---|---|
| A meter is missing from Home Assistant entirely | Debug log — see Why a meter might be missing |
| A meter is there but has the wrong name, unit or number of decimals | Diagnostics |
| A sensor shows the wrong value, or a value that stopped updating | Diagnostics |
| A warning about a meter "reporting a decrease" | Neither — see A sensor stopped updating |
| Setup fails, or the integration keeps asking you to log in again | Debug log |
| The integration fails to start after a Home Assistant update | Debug log |
| Any other warning in the log that you don't understand | Debug log, plus the warning itself |
| Anything you can't categorise | Both |
- Go to Settings → Devices & services → Brunata
- Click the three-dot menu on the integration card
- Choose Download diagnostics
The same button also appears on each individual device. It produces the identical report — this integration provides one report for the whole account, and Home Assistant offers it in both places.
- Your Home Assistant version, operating system, architecture and Python version
- A list of every custom integration you have installed, with versions
- Whether the last update succeeded, the last error if there was one, and how many meters were found
- The full lookup tables fetched from Brunata: every meter type and every measurement unit Brunata can express, not only the ones your meters use
- Whether an access token and a refresh token are currently held — as yes/no, never the tokens themselves
- One entry per meter: internal meter ID, type, unit, latest value, reading date, placement (the room label from Brunata), mounting date, decimal places and whether the meter is transmitting
Your email address, your password and your meter numbers are replaced with **REDACTED** before the file is written.
What remains is the room labels you have in Brunata Online and your meter readings. That is not sensitive in the way a password is, but it is yours — have a look at the file before attaching it if you'd rather not publish it.
- Go to Settings → Devices & services → Brunata
- Click the three-dot menu on the integration card
- Choose Enable debug logging
- Reproduce the problem
- Open the same menu and choose Disable debug logging
Home Assistant downloads a file named home-assistant_brunata_<timestamp>.log when you turn it off. It covers everything logged while debug logging was on — including lines from other integrations, not only Brunata's.
Note
Nothing is logged between updates
This is the part that makes people think the button is broken. The integration only writes to the log when it fetches data from Brunata, and it does that once an hour, at a fixed time between 58 minutes 30 seconds and 59 minutes 30 seconds past — the exact second is chosen automatically per installation and stays the same afterwards. Turn debug logging on right after that window and the log stays silent for most of the next hour. That is not a fault — there is simply nothing happening.
To force an update immediately:
- Go to Settings → Tools → Actions
- Pick the action Home Assistant Core Integration: Update entity
- Choose any Brunata sensor as the target
- Click Perform action
Within a second or two the log should fill with lines like these:
DEBUG (MainThread) [custom_components.brunata.api] Brunata returned 8 raw item(s)
DEBUG (MainThread) [custom_components.brunata.api] Item 0: meterId=7822806 meterType=2 unit='8' decimals=3 transmitting=True has reading=True
DEBUG (MainThread) [custom_components.brunata.api] Parsed 8 meters from Brunata
DEBUG (MainThread) [custom_components.brunata] Finished fetching brunata data in 0.243 seconds (success: True)
If you see those, debug logging is working. Now reproduce whatever you were investigating.
Compare the two counts in the lines above:
Brunata returned 8 raw item(s)
Parsed 8 meters from Brunata
When they match, every meter Brunata sent became a sensor. When the second number is lower, some were skipped, and each one is named on its own line:
INFO (MainThread) [custom_components.brunata.api] Meter 9912345 has meterType 7,
which this integration does not support, so no entity is created for it.
Supported types are [1, 2, 5]. If this meter measures consumption you expected
to see in Home Assistant, please report it at
https://github.com/MSL-DA/brunata_online/issues with this line and what the
meter physically measures — the log can give the code, but only you can say
what the box on the wall is.
Brunata identifies each meter by a numeric type, and the integration only
creates entities for the codes it has seen on a real account: 1 for heat cost
allocators, 2 for water and 5 for electricity. Anything else is skipped
rather than guessed at.
If a meter you expect is missing, that line contains everything needed to add it — open an issue and paste the line, along with what the meter physically is.
Note that this is logged at INFO, not DEBUG, so it appears in your normal log as well. It is written once per meter per restart, not on every poll.
A skipped meter will not appear in a diagnostics report: it is dropped before the integration builds its list of meters, so there is nothing in the snapshot to look at. The debug log is the only place it shows up.
No password, no tokens and no email address are ever written to the log. Meter IDs, meter types, raw unit indexes and readings are. Your meter number appears only in the line logged when a meter is replaced.
You can then download the full log from Settings → System → Logs → Download logs.
Open an issue at MSL-DA/brunata_online/issues and include:
- What you expected to happen, and what happened instead
- Your Home Assistant version and the integration version
- The diagnostics report, the debug log, or both
- Whether it used to work, and what changed if you know
Issues are public. Check attached files before uploading them.