fortio.org/log@v1.12.2/README.md (about)

     1  [![codecov](https://codecov.io/github/fortio/log/branch/main/graph/badge.svg?token=LONYZDFQ7C)](https://codecov.io/github/fortio/log)
     2  
     3  # Log
     4  
     5  Fortio's log is simple logger built on top of go's default one with
     6  additional opinionated levels similar to glog but simpler to use and configure.
     7  
     8  It's been used for many years for Fortio's org Fortio project and more (under fortio.org/fortio/log package) but split out recently for standalone use, with the "flag polution" limited (as a library it doesn't include the flags, you configure it using apis).
     9  
    10  ```golang
    11  // On a cli tool (avoids file name and line numbers, stack traces on log.Fatalf etc)
    12  log.SetDefaultsForClientTools()
    13  log.LoggerStaticFlagSetup() // adds -loglevel flag to configure
    14  // Or on a server type, import fortio.org/dflag, then:
    15  dflag.LoggerFlagSetup()
    16  
    17  // Then, printf style leveled logging:
    18  log.Debugf(...) // Debug level
    19  log.LogVf(...)  // Verbose level
    20  log.Infof(...)  // Info/default level
    21  log.Warnf(...)  // Warning level
    22  log.Errf(...)   // Error level
    23  log.Critf(...)  // Critical level (always logged even if level is set to max)
    24  log.Fatalf(...) // Fatal level - program will panic/exit
    25  
    26  // for http servers there is also
    27  // access log type including user-agent, forwarded ip/proto (behind load balancer case),
    28  // TLS crypto used and CN of peer certificate if any.
    29  log.LogRequest(r, "some info")
    30  
    31  // Structured logging with attributes
    32  log.S(log.Info, "msg", log.Attr("key1", value1)...)
    33  ```
    34  
    35  See the `Config` object for options like whether to include line number and file name of caller or not etc
    36  
    37  New since 1.4 server logging (as used in [fortio.org/scli](https://pkg.go.dev/fortio.org/scli#ServerMain) for instance) is now structured (json), client logging (as setup by [fortio.org/cli](https://pkg.go.dev/fortio.org/scli#ServerMain) remains as before.
    38  
    39  One can also revert server to not be JSON through config.
    40  
    41  In JSON mode the output looks like this
    42  ```json
    43  {"ts":1683504169.239557,"level":"info","file":"logger.go","line":221,"msg":"Log level is now 1 Verbose (was 2 Info"}
    44  ```
    45  Which can be converted to JSONEntry but is also a fixed, optimized format (ie ts is always first etc)
    46  
    47  The timestamp `ts` is in seconds.microseconds since epoch (golang UnixMicro() split into seconds part before decimal and microseconds after)
    48  
    49  Since 1.8 the Go Routine ID is present in json (`r` field) or colorized log output (for multi threaded server types).
    50  
    51  Optional additional `KeyValue` pairs can be added to the base structure using the new `log.S` or passed to `log.LogRequest` using `log.Any` and `log.Str`. Note that numbers, as well as arrays of any type and maps of string keys to any type are supported (but more expensive to serialize recursively).
    52  
    53  If console output is detected (and ConsoleColor is true, which is the default) or if ForceColor is set, colorized output similar to `logc` will be done instead of JSON. [levelsDemo/levels.go](levelsDemo/levels.go) produces the following output:
    54  
    55  When output is redirected, JSON output:
    56  ```json
    57  {"ts":1689986143.463329,"level":"dbug","r":1,"file":"levels.go","line":16,"msg":"This is a debug message ending with backslash \\"}
    58  {"ts":1689986143.463374,"level":"trace","r":1,"file":"levels.go","line":17,"msg":"This is a verbose message"}
    59  {"ts":1689986143.463378,"level":"info","r":1,"msg":"This an always printed, file:line omitted message"}
    60  {"ts":1689986143.463382,"level":"info","r":1,"file":"levels.go","line":19,"msg":"This is an info message with no attributes but with \"quotes\"..."}
    61  {"ts":1689986143.463389,"level":"info","r":1,"file":"levels.go","line":20,"msg":"This is multi line\n\tstructured info message with 3 attributes","attr1":"value1","attr2":42,"attr3":"\"quoted\nvalue\""}
    62  {"ts":1689986143.463396,"level":"warn","r":1,"file":"levels.go","line":22,"msg":"This is a warning message"}
    63  {"ts":1689986143.4634,"level":"err","r":1,"file":"levels.go","line":23,"msg":"This is an error message"}
    64  {"ts":1689986143.463403,"level":"crit","r":1,"file":"levels.go","line":24,"msg":"This is a critical message"}
    65  {"ts":1689986143.463406,"level":"fatal","r":1,"file":"levels.go","line":25,"msg":"This is a fatal message"}
    66  This is a non json output, will get prefixed with a exclamation point with logc
    67  ```
    68  
    69  When on console:
    70  
    71  <!-- run make screenshot and capture screen area to update this -->
    72  ![Example console color output](color.png)
    73  
    74  JSON formatted logs can also be converted back to text later/after capture and similarly colorized using [fortio.org/logc](https://github.com/fortio/logc#logc)
    75  
    76  The `log.Colors` can be used by callers and they'll be empty string when not in color mode, and the ansi escape codes otherwise.
    77  
    78  # HTTP request/response logging
    79  
    80  `LogAndCall()` combines `LogRequest` and `LogResponse` for a light middleware recording what happens during serving of a request (both incoming and outgoing attributes).
    81  
    82  For instance (most attributes elided for brevity, also logs client cert and TLSInfo if applicable)
    83  ```json
    84  {"level":"info","msg":"test-log-and-call2","method":"GET","url":"/tea","status":418,"size":5,"microsec":100042}
    85  ```
    86  
    87  # Config
    88  
    89  You can either use `fortio.org/cli` or `fortio.org/scli` (or `dflags`) for configuration using flags (or dynamic flags and config map) or use the environment variables:
    90  
    91  ```bash
    92  LOGGER_LOG_PREFIX=' '
    93  LOGGER_LOG_FILE_AND_LINE=false
    94  LOGGER_FATAL_PANICS=false
    95  LOGGER_JSON=false
    96  LOGGER_NO_TIMESTAMP=false
    97  LOGGER_CONSOLE_COLOR=true
    98  LOGGER_FORCE_COLOR=false
    99  LOGGER_GOROUTINE_ID=false
   100  LOGGER_COMBINE_REQUEST_AND_RESPONSE=true
   101  LOGGER_LEVEL='Info'
   102  ```