// Copyright (c) 2017 Gerasimos Maropoulos. // All rights reserved. // // Redistribution and use in source and binary forms, with or without // modification, are permitted provided that the following conditions are // met: // // * Redistributions of source code must retain the above copyright // notice, this list of conditions and the following disclaimer. // * Redistributions in binary form must reproduce the above // copyright notice, this list of conditions and the following disclaimer // in the documentation and/or other materials provided with the // distribution. // * Neither the name of golog nor the names of its // contributors may be used to endorse or promote products derived from // this software without specific prior written permission. // // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. /* Package golog provides an easy to use foundation for your logging operations. Source code and other details for the project are available at GitHub: https://github.com/kataras/golog Current Version 0.0.8 Installation The only requirement is the Go Programming Language $ go get -u github.com/kataras/golog Overview Example code: package main import ( "github.com/kataras/golog" ) func main() { // Default Output is `os.Stdout`, // but you can change it: // golog.SetOutput(os.Stderr) // Time Format defaults to: "2006/01/02 15:04" // you can change it to something else or disable it with: golog.SetTimeFormat("") // Level defaults to "info", // but you can change it: golog.SetLevel("debug") golog.Println("This is a raw message, no levels, no colors.") golog.Info("This is an info message, with colors (if the output is terminal)") golog.Warn("This is a warning message") golog.Error("This is an error message") golog.Debug("This is a debug message") } New Golog has a default, package-level initialized instance for you, however you can choose to create and use a logger instance for a specific part of your application. Example Code: package main import ( "github.com/kataras/golog" ) func main() { log := golog.New() // Default Output is `os.Stdout`, // but you can change it: // log.SetOutput(os.Stderr) // Level defaults to "info", // but you can change it: log.SetLevel("debug") log.Println("This is a raw message, no levels, no colors.") log.Info("This is an info message, with colors (if the output is terminal)") log.Warn("This is a warning message") log.Error("This is an error message") log.Debug("This is a debug message") } Format Golog sets colors to levels when its `Printer.Output` is actual a compatible terminal which can renders colors, otherwise it will downgrade itself to a white foreground. Golog has functions to print a formatted log too. Example Code: golog.Infof("[%d] This is an info %s", 1, "formatted log") golog.Warnf("[%d] This is an info %s", 1, "formatted log") golog.Errorf("[%d] This is an info %s", 1, "formatted log") golog.Debugf("[%d] This is an info %s", 1, "formatted log") Output Golog takes a simple `io.Writer` as its underline Printer's Output. Example Code: golog.SetOutput(io.Writer) You can even override the default line braker, "\n", by using the `golog#NewLine` function at startup. Example Code: golog.NewLine("\r\n") Levels Golog is a leveled logger, therefore you can set a level and print whenever the print level is valid with the set-ed one. Available built'n levels are: // DisableLevel will disable printer DisableLevel Level = iota // ErrorLevel will print only errors ErrorLevel // WarnLevel will print errors and warnings WarnLevel // InfoLevel will print errors, warnings and infos InfoLevel // DebugLevel will print on any level, errors, warnings, infos and debug messages DebugLevel Below you'll learn a way to add a custom level or modify an existing level. The default colorful text(or raw text for unsupported outputs) for levels can be overridden by using the `golog#ErrorText, golog#WarnText, golog#InfoText and golog#DebugText` functions. Example Code: package main import ( "github.com/kataras/golog" ) func main() { // First argument is the raw text for outputs // that are not support colors, // second argument is the full colorful text (yes it can be different if you wish to). // // If the second argument is empty then golog will update the colorful text to the // default color (i.e red on ErrorText) based on the first argument. // Default is "[ERRO]" golog.ErrorText("|ERROR|", "") // Default is "[WARN]" golog.WarnText("|WARN|", "") // Default is "[INFO]" golog.InfoText("|INFO|", "") // Default is "[DBUG]" golog.DebugText("|DEBUG|", "") // Business as usual... golog.SetLevel("debug") golog.Println("This is a raw message, no levels, no colors.") golog.Info("This is an info message, with colors (if the output is terminal)") golog.Warn("This is a warning message") golog.Error("This is an error message") golog.Debug("This is a debug message") } Golog gives you the power to add or modify existing levels is via Level Metadata. Example Code: package main import ( "github.com/kataras/golog" ) func main() { // Let's add a custom level, // // It should be starting from level index 6, // because we have 6 built'n levels (0 is the start index): // disable, // fatal, // error, // warn, // info // debug // First we create our level to a golog.Level // in order to be used in the Log functions. var SuccessLevel golog.Level = 6 // Register our level, just three fields. golog.Levels[SuccessLevel] = &golog.LevelMetadata{ Name: "success", RawText: "[SUCC]", // ColorfulText (Green Color[SUCC]) ColorfulText: "\x1b[32m[SUCC]\x1b[0m", } // create a new golog logger myLogger := golog.New() // set its level to the higher in order to see it // ("success" is the name we gave to our level) myLogger.SetLevel("success") // and finally print a log message with our custom level myLogger.Logf(SuccessLevel, "This is a success log message with green color") } The logger's level can be changed via passing one of the level constants to the `Level` field or by passing its string representation to the `SetLevel` function. Example Code: golog.SetLevel("disable") golog.SetLevel("fatal") golog.SetLevel("error") golog.SetLevel("warn") golog.SetLevel("info") golog.SetLevel("debug") Integrations Transaction with your favorite, but deprecated logger is easy. Golog offers two basic interfaces, the `ExternalLogger` and the `StdLogger` that can be directly used as arguments to the `Install` function in order to adapt an external logger. Outline: // Install receives an external logger // and automatically adapts its print functions. // // Install adds a golog handler to support third-party integrations, // it can be used only once per `golog#Logger` instance. // // For example, if you want to print using a logrus // logger you can do the following: // `golog.Install(logrus.StandardLogger())` // // Look `golog#Handle` for more. Install(logger ExternalLogger) // InstallStd receives a standard logger // and automatically adapts its print functions. // // Install adds a golog handler to support third-party integrations, // it can be used only once per `golog#Logger` instance. // // Example Code: // import "log" // myLogger := log.New(os.Stdout, "", 0) // InstallStd(myLogger) // // Look `golog#Handle` for more. InstallStd(logger StdLogger) Logrus Integration Example Code: package main import ( "github.com/kataras/golog" "github.com/sirupsen/logrus" ) func main() { // outputOnly() full() } func full() { // simulate a logrus preparation: logrus.SetLevel(logrus.InfoLevel) logrus.SetFormatter(&logrus.JSONFormatter{}) // pass logrus.StandardLogger() to print logs using using the default, // package-level logrus' instance of Logger: golog.Install(logrus.StandardLogger()) golog.Debug(`this debug message will not be shown, because the logrus level is InfoLevel`) golog.Error("this error message will be visible as json") // simulate a change of the logrus formatter // as you see we have nothing more to change // on the golog, it works out of the box, // it will be adapt by this change, automatically. logrus.SetFormatter(&logrus.TextFormatter{}) golog.Error("this error message will be visible as text") golog.Info("this info message will be visible as text") } func outputOnly() { golog.SetOutput(logrus.StandardLogger().Out) golog.Info(`output only, this will print the same contents as golog but using the defined logrus' io.Writer`) golog.Error("this error message will be visible as text") } Standard `log.Logger` Integration Example Code: package main import ( "log" "os" "github.com/kataras/golog" ) // simulate a log.Logger preparation: var myLogger = log.New(os.Stdout, "", 0) func main() { golog.SetLevel("error") golog.InstallStd(myLogger) golog.Debug(`this debug message will not be shown, because the golog level is ErrorLevel`) golog.Error("this error message will be visible the only visible") golog.Warn("this info message will not be visible") } That's the basics But you should have a basic idea of the golog package by now, we just scratched the surface. If you enjoy what you just saw and want to learn more, please follow the below links: Examples: https://github.com/kataras/golog/tree/master/_examples */ package golog // import "github.com/kataras/golog" // Version is the version string representation of the "golog" package. const Version = "0.0.8"