System Monitor

Automations are for responding to entity state changes. However, there are times when you need to observe other events in your system the ISystemMonitor can be used for getting different kinds of information. To use all the features, you should ensure your HaKafkaNet.yml in the Packages directory of Home Assistant is up to date.

public interface ISystemMonitor
{
    Task BadEntityStateDiscovered(BadEntityState badState);
    Task StateHandlerInitialized();
    Task UnhandledException(AutomationMetaData automationMetaData, Exception exception);
    Task HaApiResponse(HaServiceResponseArgs args, CancellationToken ct) => Task.CompletedTask;
    Task HaNotificationUpdate(HaNotification notification, CancellationToken ct) => Task.CompletedTask;
    Task HaStartUpShutDown(StartUpShutDownEvent evt, CancellationToken ct) => Task.CompletedTask;
}

Each of the above methods will be called by the framework at the appropriate time. You can inject IHaServices into your implementation for sending alerts or notifying you on any channel you choose.

See Example

BadEntityStateDiscovered

This method will be called for all entities used as triggers for your automations and for any entities you specify in an automation's AdditionalEntitiesToTrack property of its metadata. It will be called when the entity's state is set to one of the following values:

• null
• unknown
• unavailable

Specifically, the Bad() State Extension Method is used.

The BadEntityState model has two properties.

public record BadEntityState(string EntityId, HaEntityState? State = null);

The EntityId will always be set to the entity which is being with the bad state.

StateHandlerInitialized

During a restart, it can take up to a minute for the Kafkaflow consumers to become active. This method will be called once in the lifetime of your applicaiton when the State Handler becomes active.

UnhandledException

When an automation triggers and does not handle an exception, this method will be called with metadata associated with the automation and the exception that was thrown. Even if you do not specify metadata, your automation will be wrapped in an automation wrapper which will have information for you to inspect.

HaApiResponse

HA on occasion will error when you make a service call. When that happens for any reason, this method will be called to alert you. It will not be called for successful requests. The HaServiceResponseArgs have several properties for you to inspect. If you use an ILogger in this method, it will capture the scope of the automation that was running and will appear anywhere logs do, including the UI of the automation.

public record HaServiceResponseArgs(string Domain, string Service, object Data, HttpResponseMessage? Response, Exception? Exception);

HaNotificationUpdate

This method will be called every time there is a persistent notification update in Home Assistant. The HaNotification class has some very useful information. The author has used the ID property when sending notifications to HA. If you track that ID, you can use it to take action when the notification is cleared. For example, if you have a light that changes color based on notifications, you can reset the light when the notification is cleared.

HaStartUpShutDown

During start-up events, HA will often times reports several entities as unavailable when they simply haven't loaded yet. If you are using the BadEntityStateDiscovered method above, this can make for a very chatty system when it doesn't need to be. To help out, the StartUpShutDownEvent class has a ShutdownStartupActions extension method that is thread safe, which can be called to take actions such as mute notifications of "bad" entities. It takes in a timeout to take action after a shutdown event See the Example get some ideas.