github.com/quay/claircore@v1.5.28/docs/contributor/logging.md (about)

     1  # Logging
     2  All the logging in claircore is done with [zerolog][doc] via `context.Context`
     3  values. The `zlog` package takes OpenTelemetry labels and attaches them to
     4  `zerolog` events.
     5  
     6  This allows for claircore's logging to be used consistently throughout all the
     7  packages without having unintended prints to stderr.
     8  
     9  ## How to Log
    10  
    11  ### Adding Context
    12  In a function, use `zlog` to add key-value pairs of any relevant context:
    13  ```go
    14  {{#include ../logger_test.go:kvs}}
    15  ```
    16  
    17  Alternatively, the `go.opentelemetry.io/otel/baggage` package can be used for
    18  more explicit control around the baggage values.
    19  
    20  ### Logging style
    21  
    22  #### Constant Messages
    23  Zerolog emits lines when the `Msg` or `Msgf` methods are called. Project style
    24  is to _not_ use `Msgf`. Any variable data should be set as key-value pairs on
    25  the Event object.
    26  
    27  For example, don't do this:
    28  ```go
    29  {{#include ../logger_test.go:bad_example}}
    30  ```
    31  Do this instead:
    32  ```go
    33  {{#include ../logger_test.go:good_example}}
    34  ```
    35  
    36  #### Grammar
    37  When noting the change during a chunk of work, make sure that the
    38  log messages scan as visually similar. Usually, this means formatting messages
    39  into "${process} ${event}". For example:
    40  
    41  ```
    42  frob start
    43  frob initialized
    44  frob ready
    45  frob success
    46  frob done
    47  ```
    48  
    49  Is much easier to scan than:
    50  
    51  ```
    52  starting to frob
    53  initialized frobber
    54  ready for frobbing
    55  did frob
    56  done with frobing
    57  ```
    58  
    59  #### Don't log _and_ return
    60  When handling an error, code should only log it if it does not propagate it. The
    61  code that ultimately handles the error is responsible for deciding what to do
    62  with it. Logging and returning ends up with the same message repeated multiple
    63  times in the logs.
    64  
    65  #### Levels
    66  Claircore attempts to have consistent leveled logging. The rules for figuring
    67  out what level to use is:
    68  
    69  * Panic
    70  
    71    There's some occurrence that means the process won't work correctly.
    72  
    73  * Fatal
    74  
    75    Unused, because it prevents defers from running.
    76  
    77  * Error
    78  
    79    Something unexpected occurred and the process can continue, but a
    80    human needs to be notified. An error will be returned for this request.
    81  
    82  * Warn
    83  
    84    Something unexpected occurred and the process can continue. An error will be
    85    returned for this request.
    86  
    87  * Info
    88  
    89    Some information that may be useful to an operator. Examples include
    90    a timer-based process starting and ending, a user request starting and
    91    ending, or a summary of work done.
    92  
    93  * Debug
    94  
    95    Some information that may be useful to a developer. Examples include entering
    96    and exiting functions, stepping through a function, or specific file paths
    97    used while work is being done.
    98  
    99  [doc]: https://pkg.go.dev/github.com/rs/zerolog@v1.26.0