Skip to content

Debugging

Jump to bottom
Jan edited this page Aug 26, 2026 · 7 revisions

Debugging and diagnostics

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.

Which one do I need?

What you're seeing What to attach
A meter is missing, or 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

Downloading diagnostics

  1. Go to Settings → Devices & services → Brunata
  2. Click the three-dot menu on the integration card
  3. 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.

What the report contains

  • 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

What is removed

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.

Enabling debug logging

  1. Go to Settings → Devices & services → Brunata
  2. Click the three-dot menu on the integration card
  3. Choose Enable debug logging
  4. Reproduce the problem
  5. 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 59 minutes and 30 seconds past. Turn debug logging on at ten past the hour and the log stays silent for the next fifty minutes. That is not a fault — there is simply nothing happening.

To force an update immediately:

  1. Go to Settings → Tools → Actions
  2. Pick the action Home Assistant Core Integration: Update entity
  3. Choose any Brunata sensor as the target
  4. 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.

What the debug log contains

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.

Debug logging that survives a restart

The button above is tied to a session and turns itself off when Home Assistant restarts. It also can't capture what happens during startup, which is exactly when a failure to load shows up.

For those cases, add this to configuration.yaml and restart:

logger:
  default: warning
  logs:
    custom_components.brunata: debug

This stays on until you remove it, and it captures the integration from the moment Home Assistant starts. Remember to take it out again — debug logging is noisy and will fill your log file.

You can then download the full log from Settings → System → Logs → Download logs.

Reporting a problem

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.

Clone this wiki locally