Merge pull request #120 from ipfs/doc/update-readme

Document environment variables

README.md

@@ -1,14 +1,8 @@
 # go-log
 
-[![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](http://ipn.io)
-[![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](http://ipfs.io/)
-[![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs)
-[![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
-[![GoDoc](https://godoc.org/github.com/ipfs/go-log?status.svg)](https://godoc.org/github.com/ipfs/go-log)
-[![CircleCI](https://img.shields.io/circleci/build/github/ipfs/go-log?style=flat-square)](https://circleci.com/gh/ipfs/go-log)
-
-<!---[![Coverage Status](https://coveralls.io/repos/github/ipfs/go-log/badge.svg?branch=master)](https://coveralls.io/github/ipfs/go-log?branch=master)--->
-
+[![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](https://protocol.ai)
+[![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.io/)
+[![GoDoc](https://pkg.go.dev/badge/github.com/ipfs/go-log/v2.svg)](https://pkg.go.dev/github.com/ipfs/go-log/v2)
 
 > The logging library used by go-ipfs
 
@@ -35,20 +29,97 @@ Levels may be set for all loggers:
 
 ```go
 lvl, err := logging.LevelFromString("error")
-  if err != nil {
-    panic(err)
-  }
+if err != nil {
+	panic(err)
+}
 logging.SetAllLoggers(lvl)
 ```
 
 or individually:
 
 ```go
-lvl, err := logging.LevelFromString("error")
-  if err != nil {
-    panic(err)
-  }
-logging.SetLogLevel("foo", "info")
+err := logging.SetLogLevel("net:pubsub", "info")
+if err != nil {
+	panic(err)
+}
+```
+
+or by regular expression:
+
+```go
+err := logging.SetLogLevelRegex("net:.*", "info")
+if err != nil {
+	panic(err)
+}
+```
+
+### Environment Variables
+
+This package can be configured through various environment variables.
+
+#### `GOLOG_LOG_LEVEL`
+
+Specifies the log-level, both globally and on a per-subsystem basis.
+
+For example, the following will set the global minimum log level to `error`, but reduce the minimum
+log level for `subsystem1` to `info` and reduce the minimum log level for `subsystem2` to debug.
+
+```bash
+export GOLOG_LOG_LEVEL="error,subsystem1=info,subsystem2=debug"
+```
+
+`IPFS_LOGGING` is a deprecated alias for this environment variable.
+
+#### `GOLOG_FILE`
+
+Specifies that logs should be written to the specified file. If this option is _not_ specified, logs are written to standard error.
+
+```bash
+export GOLOG_FILE="/path/to/my/file.log"
+```
+
+#### `GOLOG_OUTPUT`
+
+Specifies where logging output should be written. Can take one or more of the following values, combined with `+`:
+
+- `stdout` -- write logs to standard out.
+- `stderr` -- write logs to standard error.
+- `file` -- write logs to the file specified by `GOLOG_FILE`
+
+For example, if you want to log to both a file and standard error:
+
+```bash
+export GOLOG_FILE="/path/to/my/file.log"
+export GOLOG_OUTPUT="stderr+file"
+```
+
+Setting _only_ `GOLOG_FILE` will prevent logs from being written to standard error.
+
+#### `GOLOG_LOG_FMT`
+
+Specifies the log message format. It supports the following values:
+
+- `color` -- human readable, colorized (ANSI) output
+- `nocolor` -- human readable, plain-text output.
+- `json` -- structured JSON.
+
+For example, to log structured JSON (for easier parsing):
+
+```bash
+export GOLOG_LOG_FMT="json"
+```
+
+The logging format defaults to `color` when the output is a terminal, and `nocolor` otherwise.
+
+`IPFS_LOGGING_FMT` is a deprecated alias for this environment variable.
+
+#### `GOLOG_LOG_LABELS`
+
+Specifies a set of labels that should be added to all log messages as comma-separated key-value
+pairs. For example, the following add `{"app": "example_app", "dc": "sjc-1"}` to every log entry.
+
+```bash
+export GOLOG_LOG_LABELS="app=example_app,dc=sjc-1"
 ```
 
 ## Contribute