Add ASYN_TRACE_USER1, ASYN_TRACE_USER2

[tboegi]

Sometimes it is useful to have a trace level between WARNING and FLOW
to debug drivers and hardware.
In case of a motor, for example, it will show when the motor starts or
stops, without all the poll() messages.

For a temperatur controller it may be new set points send to the device,
or information when the heater is turned on or off.

Note that these trace bits are highly user and application dependent.
Without the need to change asyn may developers the ASYN_TRACE_USER1
and/or ASYN_TRACE_USER2 to whatever they need.

These bits should be integrated into the different op/ files to be
more useful (but I don't have any of them)

[MarkRivers]

I don't like ASYN_TRACE_USER1 and ASYN_TRACE_USER2, or the previous suggestion of ASYN_TRACE_INFO because they don't really describe what that debugging is enabling.

I do see that there is a need for something that is not covered by the existing mask bits. How about ASYN_TRACE_STATE? This would be added to the documentation as follows:

• ASYN_TRACE_ERROR Run time errors are reported, e.g. timeouts.
• ASYN_TRACEIO_DEVICE Device support reports I/O activity.
• ASYN_TRACEIO_FILTER Any layer between device support and the low level driver reports any filtering it does on I/O.
• ASYN_TRACEIO_DRIVER Low level driver reports I/O activity.
• ASYN_TRACE_FLOW Report logic flow. Device support should report all queue requests, callbacks entered, and all calls to drivers. Layers between device support and low level drivers should report all calls they make to lower level drivers. Low level drivers report calls they make to other support.
• ASYN_TRACE_WARNING Report warnings, i.e. conditions that are between ASYN_TRACE_ERROR and ASYN_TRACE_FLOW.
• ASYN_TRACE_STATE Report changes in state that are not covered by ASYN_TRACE_WARNING or ASYN_TRACE_FLOW.

It seems like this would cover the use cases you have described?

[anjohnson]

The name INFO comes from the original Unix syslog API which has a number of standard log levels, which the Linux documentation describes as being:

       #define KERN_EMERG    "<0>"  /* system is unusable               */
       #define KERN_ALERT    "<1>"  /* action must be taken immediately */
       #define KERN_CRIT     "<2>"  /* critical conditions              */
       #define KERN_ERR      "<3>"  /* error conditions                 */
       #define KERN_WARNING  "<4>"  /* warning conditions               */
       #define KERN_NOTICE   "<5>"  /* normal but significant condition */
       #define KERN_INFO     "<6>"  /* informational                    */
       #define KERN_DEBUG    "<7>"  /* debug-level messages             */

The ASYN_TRACEIO_* bits are really something different to the loglevel.

I'm not saying that we should adopt those levels, but they are a standard that has been re-used in many other logging subsystems since. It appears to me that ASYN_TRACE_FLOW is more like KERN_INFO, so I wonder if the new level should be ASYN_TRACE_NOTICE? If you do add that and want to try to adapt the naming standard maybe ASYN_TRACE_INFO could be added as a synonym for ASYN_TRACE_FLOW, with the correspondence documented?

[prjemian]

Similar level names (different values) in Python's logging package:

Level	Numeric value
CRITICAL	50
ERROR	40
WARNING	30
INFO	20
DEBUG	10
NOTSET	0

[tboegi]

Replaced by #67, which uses the appropriate branch name
It seems that "STATE" make most sense as a new trace bit.

[ralphlange]

The underlying problem is of conceptual nature.
Unix and Python log API levels, as well as ASYN's WARNING and ERROR levels are about severity of the event to be logged.
ASYN's DEVICE/FILTER/DRIVER bits are about the origin of the event.
ASYN's FLOW bit (and the proposed STATE) are about the type of event.

Merging these partially orthogonal concepts into a single enumeration or a flat mask does not really work. Severity is probably a number (ordered enumeration), the other two are probably enumerations or bitmasks.

Implementations would often put the severity in the MSBs to allow severity filtering by simple numerical comparison.

[tboegi]

@ralphlange: Thanks for the clarification.
In this sense we would need INFO (for severity) and STATE for
"not generated by asyn itself, but from an application using asyn".
In this case asyn is nice enough to offer it's tracing framework to others.