Debug template sensors

Similar to debugging automations, it would be nice to be able to debug template sensors.

You could then see the resulting state/availability, and all individual entities that were used in those template(s). It could also be usefull to get an insight in how often a template sensor is recalculated.

Edit (making the request more specific); I’m especially interested in previous calculated states/availabilities of a template sensor. The developer tools only allow to play with templates as they are now.

Developer Tools → Templates

Totally agree. I really want to review traces for template sensors. Especially trigger template sensors as they can get quite complicated. I want to see the details of the trigger that caused its state to update as well as the result of each template that was recalculated by that trigger in a trace like I can with an automation. :+1:

@tom_l it’s more then just that. Like yea I do that too but trigger template sensors in particular can get complicated. And you can’t test them there because the trigger object doesn’t exist. When having a problem with a trigger template sensor what I often do is turn it into an automation with the same trigger and a single variables step. It would be much better if you could just review traces for them directly.

2 Likes

@tom_l That works indeed to fiddle around, especially for when you’re creating such sensors.

However, I can’t do that with previous states. Let’s assume I noticed my template sensor is showing an unexpected error sometimes. With the developer tools I can see what its value will be at this moment, but that would be the same as the sensor itself will be at this moment.

However, I might miss the fact that 10 minutes ago, one of the used entities was unavailable, which resulted in an incorrect calculation or sth like that.

With an automation, you can browse to the last few executions, and see what exactly was going on at that moment.

My inition question was indeed a bit vague, I’ll update it to make it more clear.

2 Likes

Whenever an entity referenced by the template undergoes a state-change.

Exceptions are now() and when referencing the entire state-machine (states) or entire domains (states.light). Those situations are throttled.

Developer Tools → States allow you to set an entity’s state to whatever you want. A simpler technique is to specify the desired value directly in the template during its development/testing phase in the Template Editor.

When designing a template, after confirming it handles nominal values, one should progress to ensuring it handles non-nominal values including unavailable, unknown and none. Several filters accept default values and there’s even an explicit default filter.

In addition, if a Template Sensor’s template fails with an error, that error is recorded in the Log thereby revealing the cause.

Yep, that’s how my development/debug process is now.

But I have a few binary template sensors that make a bunch of calculations and then decide whether something needs to happen. One example is whether cooling is desired or not, based on various temperature sensors in the house, overall energy usage/production, what the solar irradiation is, etc.

This binary sensor is shown in dashboards and used as triggers.

However, I might sometimes be like “heh, I wonder why this sensor is still off” or “I wonder why it turned on so early this morning”. And that’s where this feature would shine.

At that point I might not have a laptop at hand to easily start copy pasting my complex templates from the yaml files into developer tools and in other tabs browse through various entites’ history or temporarily override states (which might cause other side effects). A “debug this sensor” could be used even on my phone; open the entity, choose debug or something, select the desired time, and quickly see what everything was at this moment :blush:.

In any case, thanks for all extra information

Definitely a good ask - I’ve struggled a lot recently trying to assume that I know the shape and value in template sensor triggers!

The shape of triggers is described in the trigger template documentation. There’s no guessing needed.

I don’t think the values themself are always known at that point. An integration might respond with a value that isn’t documented.

The values are described in the documentation. Integrations don’t create triggers, so that’s not true.

There are a few triggers which have variable shape, those triggers can be debugged with the developer tools → events tab.

You can have a state trigger in a template sensor if I’m correct. That state can have any value that this sensor can have right?

Right, state objects are covered and linked from the trigger template documentation. So there’s no question to the shape of the trigger.

Ah, I think there was a misunderstanding here :blush:. I was talking about the value there. E.g. in Template - Home Assistant I don’t know the humidity value that was send. If that webhook would pass in some enum, I would have a hard time figuring out the enum value that caused some unexpected result.

But this trigger could just be some random other sensor with a string value. And while I know how to get this value, I don’t know what it was 5 hours ago when my template sensor suddenly yielded some defaul fallback value.

Webhooks accept any shaped data, so if you’re sending the data you should know the shape.

FYI the templating documentation for that is here

here for the non-templating documenation

I did an edit of my reply which you might have missed. Sorry.

The webhook was an example. It could also be a state trigger from an entity that some random custom integration provided. That value might be unknown. It would be nice if the integration author documented it, but sometimes it’s not.

No, that’s not possible. state triggers look at state change events which are generated by HA, not integrations. This is 100% false and you’re just going to keep confusing yourself if you think this way. The only odd shape in a state object is the attributes dictionary, which is set by the entity (i.e. the integration). You can see that shape by looking at developer tools → states page. Every other aspect of the state trigger will always be the same shape and that shape is documented in the link above.

I have to say this is a very much needed feature for a variety of reasons:

  • While the trigger structure provided by HA is well documented the actual data coming in might not be, for example if the trigger is a webhook or an MQTT message the data could be in any format.
  • When you have a variety of actions to do things like run actions (services), call an API, calculate variables, etc. it is not always clear where things broke down, especially if it was working but suddenly stops or randomly fails.
  • When building the sensor the variables will be in the format of variable_name: “{{ some template }}” but in dev tools you need to do {% set variable_name = {{ some template }} %} which makes switching back and forth messy
  • If you have a variable being assigned by the result of an action you can’t easily put that into dev tools
  • If you have logic based on the trigger data you have to try and build that all out as JSON in dev tools before being able to use it
  • Probably more reasons I am not thinking about at the moment

What I have found as the easiest way to handle this missing feature is to build a “test” automation that has all of the actions I am putting in the sensor and variables that use the actual template I will use in the value of the sensor and then trigger that automation so I can see the trace and figure out what I screwed up.

1 Like