Add implicit events: less application code, more uniform events

README.md

@@ -231,11 +231,17 @@ Because the discovery mechanism involves multiple HTTP queries, it is recommende
 
 A House service typically keeps two logs: traces (for maintainer) and events (for users). This history is separate for each application.
 
+Deciding when to generate an event or else a trace is not always obvious. After trials and errors, it is recommended to follow a few basic rules:
+- If the message indicates a problem that would be resolved only by changing the software, then it should be a trace.
+- If the message indicates a problem that the user can resolve without rebuilding the software, then it should be an event.
+- If interpreting the message requires knowledge of the source code, then it should be a trace.
+- If the message provides information that is meaningful to the user without requiring knowledge of the source code, then it should be an event.
+
 All logs are stored in daily files (see later for more details).
 
 The 256 latest events are also kept in a memory buffer. If the /{app}/log/events URI is used with no parameter, all events present in memory are returned.
 
-The log API is used to record events and traces inside the application and save then to permanent storeage. It also implements the web API used to update an event web page.
+The log API is used to record events and traces inside the application and to save then to permanent storeage. It also implements the web API used to update an event web page.
 
 First the application must include the client header file:
 ```

houseconfig.c

@@ -76,6 +76,7 @@
 
 #include <echttp_json.h>
 
+#include "houselog.h"
 #include "houseconfig.h"
 
 #define CONFIGMAXSIZE 1024
@@ -93,6 +94,7 @@ static const char *ConfigFile = HOUSECONFIG_PATH "portal" HOUSECONFIG_EXT;
 
 static const char *houseconfig_refresh (const char *file) {
 
+ houselog_event ("CONFIG", "DATA", "LOADING", "FROM %s", file);
  if (ConfigText) echttp_parser_free (ConfigText);
  ConfigText = echttp_parser_load (file);
  if (!ConfigText) {
@@ -160,12 +162,16 @@ const char *houseconfig_update (const char *text) {
  ConfigText = 0;
  ConfigTextLength = 0;
  ConfigTokenCount = 0;
+ houselog_trace (HOUSE_FAILURE, "CONFIG", "ERROR %s", error);
  return error;
  }
  fd = open (ConfigFile, O_WRONLY|O_TRUNC|O_CREAT, 0777);
  if (fd >= 0) {
  write (fd, text, ConfigTextLength);
  close (fd);
+ houselog_event ("CONFIG", "DATA", "SAVED", "TO %s", ConfigFile);
+ } else {
+ houselog_event ("CONFIG", "FILE", "ERROR", "CANNOT OPEN %s", ConfigFile);
  }
  return 0;
 }

houselog.c

@@ -25,7 +25,8 @@
  * void houselog_initialize (const char *application,
  * int argc, const char **argv);
  *
- * Initialize the environment required to record logs.
+ * Initialize the environment required to record logs. This must be
+ * the first function that the application calls.
  *
  * void houselog_trace (const char *file, int line, const char *level,
  * const char *object,
@@ -46,6 +47,10 @@
  * This function must be called a regular intervals for background
  * processing, e.g. cleanup of expired resources, file backup, etc.
  *
+ * const char *houselog_host (void);
+ *
+ * Return the name of the local machine, as used in the logs.
+ *
  * In order to avoid writing frequently to SD cards, the active logs are
  * written to /dev/shm, moved to permanent storage at the end of the day.
  * To limit loss of data on power outage, the logs are also saved to
@@ -521,6 +526,8 @@ void houselog_initialize (const char *name, int argc, const char **argv) {
  houselog_restore (&local, LogTypes[i]);
  }
  houselog_background (now); // Initial state.
+
+ houselog_event ("SERVICE", LogName, "STARTING", "ON %s", LocalHost);
 }
 
 void houselog_background (time_t now) {
@@ -568,3 +575,7 @@ void houselog_background (time_t now) {
  }
 }
 
+const char *houselog_host (void) {
+ return LocalHost;
+}
+

houselog.h

@@ -43,3 +43,5 @@ void houselog_event (const char *category,
 
 void houselog_background (time_t now);
 
+const char *houselog_host (void);
+