zotregistry.dev/zot@v1.4.4-0.20240314164342-eec277e14d20/pkg/log/guidelines.md (about)

     1  # Log Guidelines
     2  
     3  Logs from `zot` can be pushed to the popular ELK stack and therefore they
     4  become one of the service level indicators (SLI). It is therefore important to
     5  set guidelines about how we log in this project.
     6  
     7  ## Log Levels
     8  
     9  Depending on whether a log message is useful in development or production, set the appropriate level.
    10  Development code should use DEBUG level.
    11  
    12  ## Message Format
    13  
    14  We use structured logs (currently via the `zerolog` library).
    15  
    16  1. Use **lower-case** strings by default
    17  
    18  2. The "message" field **should not** have any formatting strings
    19  
    20  For example,
    21  
    22  ```
    23  log.Info().Msg(fmt.Sprintf("this is a %s message", "test"))
    24  ```
    25  
    26  So that exact string matches are possible on the "message" field.
    27  
    28  All parameters should be specified **separately** as part of the log.
    29  
    30  For example,
    31  
    32  ```
    33  log.Info().Str("stringParam", "stringValue").Msg("static message")
    34  ```
    35  
    36  ## Separate components
    37  
    38  Instead of: 
    39  
    40  ```
    41  log.Info().Msg("module: message")
    42  ```
    43  
    44  use:
    45  
    46  ```
    47  log.Info().Str("module", "module").Msg("message")
    48  ```
    49  
    50  _OR_ if you want to a reusable logger then:
    51  
    52  ```
    53  log.Info().With().Str("module", "module1").Logger().Msg("message")
    54  ```
    55  
    56  ## Errors
    57  
    58  Not all errors are really errors. 
    59  
    60  For example, lookup a cache (fast path) and it throws a not-found error, and we
    61  expect to handle it and perform a slow path lookup. Instead of logging the
    62  lookup failure at ERROR level, it may be more appropriate to log at DEBUG level
    63  and then handle the error.
    64  
    65  Also, instead of `Msg("error at something")` standardize on `Msg("failed at something")`.