extended doc with extra fields

Author: sy-c

doc/README.md

@@ -120,6 +120,8 @@ collected centrally.
   `/opt/o2-InfoLogger/bin/log test`
     * See command line options with `/opt/o2-InfoLogger/bin/log -h`
     * It can be used to redirect output of a process to InfoLogger with e.g. `myProcess | /opt/o2-InfoLogger/bin/log -x`.
+    * This utility uses pid/username of parent process to identify message source. In case of pipe redirection, it detects pid/username of process injecting logs, for a better tagging of messages.
+    * Most message fields can be explicitely set with the -o command line option.      
 
 * Archive table of messages and create fresh one:
   `/opt/o2-InfoLogger/bin/infoLoggerAdminDB -c archive`
@@ -171,8 +173,48 @@ The InfoLogger library allows to inject messages directly from programs, as show
  * More information on the API can be found in the headers /opt/o2-InfoLogger/include and the corresponding
  documentation generated by Doxygen.
  
- * Current list of user-defined tags is limited to severity (Info (default), Error, Fatal, Warning, Debug), but will be expanded soon, through a 'context' option
-   which can be specified with each message, to allow setting the other log fields.
+ * Some example calls are available in [the source code](/test/testInfoLogger.cxx)
+ 
+ * The tags associated to a message consist of the following fields:
+   ** Severity: the kind of message, one of: Info (default), Error, Fatal, Warning, Debug
+   ** Level: the relative visibility of the message and associated target audience to whom is addressed the message: from 1 (important, visible to all) to 99 (low-level debug message, for experts only).
+      For ALICE Run 2, the following ranges were used to categorize messages in DAQ/ECS: operations (1-5) support (6-10) developer (11-20) debug (21-99) 
+   ** Timestamp: time at which message was injected (Unix time in seconds since 1.1.1970). Precision goes to the microsecond.
+   ** Hostname: the name of the machine where the message is issued. For concision, the domain name is excluded from this tag, only the base IP host name is kept.
+   ** Rolename: the role name associated to the entity running the process. The same host might run several different roles. Example role name: FLP-TPC-1, EPN-223.
+   ** PID: the system process ID injecting the message.
+   ** Username: the system user name running the process injecting the message.
+   ** System: the name of the system running the process. In Run 2, it would be ECS,DAQ,HLT,TRG, ... To be adapted/defined for Run 3.
+   ** Facility: the name of the module/library injecting the message. It should give an indication about the component issuing the message or feature associated to it, e.g. readout, dataSampling, monitoring, ...
+   ** Detector: the 3-letter code of the detector associated to the message, e.g. TPC, MCH, TRI, ...
+   ** Partition: the name of the partition running the process, e.g. PHYSICS_1. To be adapted to run 3 depending on control system.
+   ** Run: the run number associated to the process. To be adapted to run 3 depending on control system.
+   ** ErrorCode: an error code associated to the message. Useful. A unique O2-wide namespace should be used to allocate error code ranges to different components, so that they are unique
+   and can be associated to documentation. An error code can also be associated to an information or other severity message, to give (if necessary) operators details about a given message.
+   ** ErrorSource: the name of the file from which the message is injected (meaningful in case of native c/c++ interface calls).
+   ** ErrorLine: the source line number from which message is injected. Useful to trace back low-level debug messages.
+   ** Message: the message content itself. Free text. Multiple-line messages are split at each end-of-line. Some characters are not allowed and replaced (\* and \#).
+   
+   It is important to set the fields as precisely as possible, so that messages can be searched and filtered efficiently.   
+   The initial list of fields has been taken from the Run 2 vocabulary. It may be adapted, in particular depending on the implementation and naming conventions of the control system.
+   
+   The fields are grouped in different categories.
+   ** The base 'message' field. It's the message content, and needs to be explicitely specified for each message.
+   ** The timestamp is set automatically with sub-second precision at time of message creation, and never needs to be specified.
+   ** The 'dynamic' fields, which are likely different and unique from one message to the other, are grouped in a 'messageOptions' struct which can be specified for each message. It includes:
+      Severity, Level, ErrorCode, ErrorSource, ErrorLine. There are macros defined to help concisely set them in the C++ interface function calls.
+   ** The 'static' fields, usually stable for the lifetime of the process, are grouped in a 'Context' object. These fields are automatically set from runtime environment.
+      Some of them can be explicitely redefined by user: Facility, Role, System, Detector, Partition, Run.
+      Some of them can not be redefined by user: PID, Hostname, Username.
+      A default context can be defined for all messages, but it can also be specified on a message-by-message base.
+      The context can be explicitely refreshed when necessary, in case of runtime environment has changed.
+      At the moment, the following environment variables are used as input: O2_ROLE, O2_SYSTEM, O2_DETECTOR, O2_PARTITION, O2_RUN... but it will be adapted to the conventions of the run control system when
+      defined.
+      
+    Usually, one will only take care of defining the per-message messageOptions struct and a context with appropriate Facility field set, all other being set automatically.
+   
+   
+  
  
 
 
@@ -199,7 +241,7 @@ achieved on CentOS 7 with e.g. (as root):
   Behavior of infoLogger library can be configured with INFOLOGGER_MODE environment variable.
   This defines where to inject messages at runtime.
   Possible values are:
-  * infoLoggerD = inject messages to infoLogger system, through infoLoggerD process (this is the default mode)
+  * infoLoggerD = inject messages to infoLogger system, through infoLoggerD process (this is the default mode). If infoLoggerD is not found, an error message is printed on stderr and further logs are output to stdout.
   * stdout = print messages to stdout/stderr (severity error and fatal)
   * file = print messages to a file. By default, "./log.txt". Specific file can be set with e.g. INFOLOGGER_MODE=file:/path/to/my/logfile.txt
   * none = messages are discarded