github.com/adnan-c/fabric_e2e_couchdb@v0.6.1-preview.0.20170228180935-21ce6b23cf91/docs/Setup/logging-control.md (about)

     1  # Logging Control
     2  
     3  ## Overview
     4  
     5  Logging in the `peer` application and in the `shim` interface to chaincodes is programmed using facilities provided by the `github.com/op/go-logging` package. This package supports
     6  
     7  - Logging control based on the severity of the message
     8  - Logging control based on the software _module_ generating the message
     9  - Different pretty-printing options based on the severity of the message
    10  
    11  All logs are currently directed to `stderr`, and the pretty-printing is currently fixed. However global and module-level control of logging by severity is provided for both users and developers. There are currently no formalized rules for the types of information provided at each severity level, however when submitting bug reports the developers may want to see full logs down to the DEBUG level.
    12  
    13  In pretty-printed logs the logging level is indicated both by color and by a 4-character code, e.g, "ERRO" for ERROR, "DEBU" for DEBUG, etc. In the logging context a _module_ is an arbitrary name (string) given by developers to groups of related messages. In the pretty-printed example below, the logging modules "peer", "rest" and "main" are generating logs.
    14  
    15      16:47:09.634 [peer] GetLocalAddress -> INFO 033 Auto detected peer address: 9.3.158.178:7051
    16      16:47:09.635 [rest] StartOpenchainRESTServer -> INFO 035 Initializing the REST service...
    17      16:47:09.635 [main] serve -> INFO 036 Starting peer with id=name:"vp1" , network id=dev, address=9.3.158.178:7051, discovery.rootnode=, validator=true
    18  
    19  An arbitrary number of logging modules can be created at runtime, therefore
    20  there is no "master list" of modules, and logging control constructs can not
    21  check whether logging modules actually do or will exist. Also note that the
    22  logging module system does not understand hierarchy or wildcarding: You may
    23  see module names like "foo/bar" in the code, but the logging system only sees
    24  a flat string. It doesn't understand that "foo/bar" is related to "foo" in any
    25  way, or that "foo/\*" might indicate all "submodules" of foo.
    26  
    27  ## peer
    28  
    29  The logging level of the `peer` command can be controlled from the command line for each invocation using the `--logging-level` flag, for example
    30  
    31      peer node start --logging-level=debug
    32  
    33  The default logging level for each individual `peer` subcommand can also be
    34  set in the
    35  [core.yaml](https://github.com/hyperledger/fabric/blob/master/peer/core.yaml)
    36  file. For example the key `logging.node` sets the default level for the `node`
    37  subcommmand. Comments in the file also explain how the logging level can be
    38  overridden in various ways by using environment varaibles.
    39  
    40  Logging severity levels are specified using case-insensitive strings chosen from
    41  
    42      CRITICAL | ERROR | WARNING | NOTICE | INFO | DEBUG
    43  
    44  The full logging level specification for the `peer` is of the form
    45  
    46      [<module>[,<module>...]=]<level>[:[<module>[,<module>...]=]<level>...]
    47  
    48  A logging level by itself is taken as the overall default. Otherwise, overrides for individual or groups of modules can be specified using the
    49  
    50      <module>[,<module>...]=<level>
    51  
    52  syntax. Examples of <level> specifications (valid for all of
    53  `--logging-level`, environment variable and
    54  [core.yaml](https://github.com/hyperledger/fabric/blob/master/peer/core.yaml)
    55  settings):
    56  
    57      info                                       - Set default to INFO
    58      warning:main,db=debug:chaincode=info       - Default WARNING; Override for main,db,chaincode
    59      chaincode=info:main=debug:db=debug:warning - Same as above
    60  
    61  ## Go chaincodes
    62  
    63  The standard mechanism to log within a chaincode application is to integrate with the logging transport exposed to each chaincode instance via the peer.  The chaincode `shim` package provides APIs that allow a chaincode to create and manage logging objects whose logs will be formatted and interleaved consistently with the `shim` logs.
    64  
    65  As independently executed programs, user-provided chaincodes may technically also produce output on stdout/stderr.  While naturally useful for "devmode", these channels are normally disabled on a production network to mitigate abuse from broken or malicious code.  However, it is possible to enable this output even for peer-managed containers (e.g. "netmode") on a per-peer basis via the CORE_VM_DOCKER_ATTACHSTDOUT=true configuration option.
    66  
    67  Once enabled, each chaincode will receive its own logging channel keyed by its container-id.  Any output written to either stdout or stderr will be integrated with the peer's log on a per-line basis.  It is not recommended to enable this for production.
    68  
    69  ### API
    70  
    71  `NewLogger(name string) *ChaincodeLogger` - Create a logging object for use by a chaincode
    72  
    73  `(c *ChaincodeLogger) SetLevel(level LoggingLevel)` - Set the logging level of the logger
    74  
    75  `(c *ChaincodeLogger) IsEnabledFor(level LoggingLevel) bool` - Return true if logs will be generated at the given level
    76  
    77  `LogLevel(levelString string) (LoggingLevel, error)` - Convert a string to a `LoggingLevel`
    78  
    79  A `LoggingLevel` is a member of the enumeration
    80  
    81  ```
    82  LogDebug, LogInfo, LogNotice, LogWarning, LogError, LogCritical
    83  ```
    84  
    85  which can be used directly, or generated by passing a case-insensitive version of the strings
    86  
    87  ```
    88  DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL
    89  ```
    90  
    91  to the `LogLevel` API.
    92  
    93  Formatted logging at various severity levels is provided by the functions
    94  
    95  ```
    96  (c *ChaincodeLogger) Debug(args ...interface{})
    97  (c *ChaincodeLogger) Info(args ...interface{})
    98  (c *ChaincodeLogger) Notice(args ...interface{})
    99  (c *ChaincodeLogger) Warning(args ...interface{})
   100  (c *ChaincodeLogger) Error(args ...interface{})
   101  (c *ChaincodeLogger) Critical(args ...interface{})
   102  
   103  (c *ChaincodeLogger) Debugf(format string, args ...interface{})
   104  (c *ChaincodeLogger) Infof(format string, args ...interface{})
   105  (c *ChaincodeLogger) Noticef(format string, args ...interface{})
   106  (c *ChaincodeLogger) Warningf(format string, args ...interface{})
   107  (c *ChaincodeLogger) Errorf(format string, args ...interface{})
   108  (c *ChaincodeLogger) Criticalf(format string, args ...interface{})
   109  ```
   110  
   111  The `f` forms of the logging APIs provide for precise control over the formatting of the logs. The non-`f` forms of the APIs currently insert a space between the printed representations of the arguments, and arbitrarily choose the formats to use.
   112  
   113  In the current implementation, the logs produced by the `shim` and a `ChaincodeLogger` are timestamped, marked with the logger *name* and severity level, and written to `stderr`. Note that logging level control is currently based on the *name* provided when the `ChaincodeLogger` is created. To avoid ambiguities, all `ChaincodeLogger` should be given unique names other than "shim". The logger *name* will appear in all log messages created by the logger. The `shim` logs as "shim".
   114  
   115  
   116  Go language chaincodes can also control the logging level of the chaincode `shim` interface through the `SetLoggingLevel` API.
   117  
   118  `SetLoggingLevel(LoggingLevel level)` - Control the logging level of the shim
   119  
   120  The default logging level for the shim is `LogDebug`.
   121  
   122  Below is a simple example of how a chaincode might create a private logging object logging at the `LogInfo` level, and also control the amount of logging provided by the `shim` based on an environment variable.
   123  
   124  ```
   125  var logger = shim.NewLogger("myChaincode")
   126  
   127  func main() {
   128  
   129  	logger.SetLevel(shim.LogInfo)
   130  
   131  	logLevel, _ := shim.LogLevel(os.Getenv("SHIM_LOGGING_LEVEL"))
   132  	shim.SetLoggingLevel(logLevel)
   133  	...
   134  }
   135  ```