Add readme

2 files changed, 99 insertions, 0 deletions

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..3050c2d
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Felix Hanley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f43ba06
--- /dev/null
+++ b/README.md
@@ -0,0 +1,78 @@
+# logger
+
+A simple logger package that provides levels, a number of output formats, and
+named sub-logs.  Output formats include plain text, key/value, JSON and
+AMQP/RabbitMQ
+
+## Installation
+
+Install using `go get github.com/felix/logger`.
+
+Documentation is available at http://godoc.org/github.com/felix/logger
+
+## Usage
+
+### Create a normal logger
+
+```go
+log := logger.New(&logger.Options{
+	Name:  "app",
+	Level: logger.Debug,
+})
+log.Error("unable to do anything")
+```
+
+```text
+... [INFO ] app: unable to do anything
+```
+
+### Create a key/value logger
+
+```go
+import "github.com/felix/logger/outputs/keyvalue"
+
+log := logger.New(&logger.Options{
+	Name:      "app",
+	Level:     logger.Debug,
+    Formatter: keyvalue.New(),
+})
+log.Warn("invalid something", "id", 344, "error", "generally broken")
+```
+
+```text
+... [WARN ] app: invalid something id=344 error="generally broken"
+```
+
+```text
+... [WARN ] app: invalid something id=344 error="generally broken"
+```
+
+### Create a sub-logger
+
+```go
+sublog := log.Named("database")
+sublog.Info("connection initialised")
+```
+
+```text
+... [INFO ] app.database: connection initialised
+```
+
+### Create a new Logger with pre-defined values
+
+For major sub-systems there is no need to repeat values for each log call:
+
+```go
+reqID := "555"
+msgLog := sublog.WithFields("request", reqID)
+msgLog.Error("failed to process message")
+```
+
+```text
+... [INFO ] app.database: failed to process message request=555
+```
+
+## Credits
+
+Solidly based on all the other loggers around, particularly Hashicorp's simple
+hclog with additions and modifications as required.