zotregistry.io/zot@v1.4.4-0.20231124084042-02a8ed785457/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.