Openebs: conventions for log message across different modules.

[kmova]

Let us use a example of volume provisioning workflow in maya-apiserver to understand and define the different log levels that should be used.

Fatal -- maya-apiserver is unable to determine the orchestration provider, so there is no point in continuing further. log the message and exit
Error -- maya-apiserver is unable to contact the kuberentes-apiserver at the moment, log the message and return error to the caller
Warn -- maya-apiserver volume is being provisioned with values that are not optimal
Info -- maya-apiserver was able to successfully provision an volume - display the name of the volume.
Info(V2) -- log the messages that show the various stages in the volume provisioning
Info(V3) -- log the code level entry/exit and print data/variables

[kmova]

Once finalized, the logging convention should be recorded in the following link:
https://github.com/openebs/openebs/blob/master/contribute/design/code-structuring.md

[AmitKumarDas]

Let us use a example of volume provisioning workflow in maya-apiserver to understand and define the different log levels that should be used.

A request lifecycle in maya api service:

• volume provisioning request arrives at api service
• volume endpoint intercepts this request
• endpoint marshalls the request into volume structure
• endpoint passes the volume struct to policy enforcement logic
• endpoint receives the updated volume struct from policy enforcement logic
• endpoint checks the volume type & passes the volume struct to corresponding volume type provisioner
• volume type provisioner check the volume orch provider & pass the volume struct to appropriate orch provider

Fatal -- for exiting when an unexpected unrecoverable error fault

• Need to find out areas where this is applicable w.r.t maya api service

Fatal -- maya-apiserver is unable to determine the orchestration provider, so there is no point in continuing further. log the message and exit

• Fatal will stop maya service.
• Rather error & exit is appropriate here.
• It should not stop maya api service.
• The endpoint should verify & either pass through or tune the error message before giving it to http handler.

Error -- maya-apiserver is unable to contact the kuberentes-apiserver at the moment, log the message and return error to the caller

• Same as above

WARN -- maya-apiserver volume is being provisioned with values that are not optimal
WARN -- is usually when some threshold situations are seen or borderline situations .. like long time to provision or running low on memory .. or about to perform some operation that shouldn't be done

• Should it log & proceed ?
• This will be tricky & will have a direct coupling with business logic & policies.
• Below are some items that fall outside the scope of logging:
  
  
  
  • If yes, how to notify admin ?
  
  
  • How to state that warn is resolved ?
  
  
  • How to state that warn still exists ?
  
  

Info -- maya-apiserver was able to successfully provision an volume - display the name of the volume.

• This should be only for successfully done actions
• This applies only to following actions:
  
  
  
  • volume create
  
  
  • volume delete
  
  
  • snapshot create
  
  
  • snapshot delete
  
  
  • snapshot revert
  
  
  • clone create
  
  
  • clone delete
  
  
• This does not apply to following actions:
  
  
  
  • volume read
  
  
  • volume list
  
  
  • volume watch
  
  
  • volume stats
  
  
  • snapshot read
  
  
  • snapshot list
  
  
  • snapshot watch
  
  
  • snapshot stats
  
  

Info(V2) -- log the messages that show the various stages in the volume provisioning

Info(V3) -- log the code level entry/exit and print data structure

• I would like to merge V2 & V3. Else it will be too difficult to maintain.
  
  
  
  • So INFO will have V(1) & V(2) & nothing else
  
  

Other Notes

• Can logging levels be provided on a per request basis else it defaults to app launch log level?
  
  
  
  • Will it be good to do so ?
  
  
• WARNINGS do not do any good if there is no corrective mechanisms involved.
  
  
  
  • What should be done to eliminate the WARNINGS ?
  
  

[kmova]

An example of warning could be running the service or exposing the service on a non-secure port. This message will not appear if the user only runs the service with secure port.

[prateekpandey14]

The following conventions for the glog levels to use.
glog.Errorf() - Always an error

glog.Warningf() - Something unexpected, but probably not an error

glog.Infof() has multiple levels:

glog.V(0) - Generally useful for this to ALWAYS be visible to an operator
Programmer errors
Logging extra info about a panic
CLI argument handling
glog.V(1) - A reasonable default log level if you don't want verbosity.
Information about config (listening on X, watching Y)
Errors that repeat frequently that relate to conditions that can be corrected (pod detected as unhealthy)
glog.V(2) - Useful steady state information about the service and important log messages that may correlate to significant changes in the system. This is the recommended default log level for most systems.
Logging HTTP requests and their exit code
System state changing (killing pod)
Controller state change events (starting pods)
Scheduler log messages
glog.V(3) - Extended information about changes
More info about system state changes
glog.V(4) - Debug level verbosity (for now)
Logging in particularly thorny parts of code where you may want to come back later and check it
As per the comments, the practical default level is V(2). Developers and QE environments may wish to run at V(3) or V(4). If you wish to change the log level, you can pass in -v=X where X is the desired maximum level to log.

[github-actions[bot]]

Issues go stale after 90d of inactivity.