log

README

log

import "github.com/ardanlabs/kit/log"

• Overview
• Index
• Examples

Overview

Package log provides a simple layer above the standard library logging package. The base API provides two logging levels, DEV and USER. The DEV level logs things developers need and can be verbose. The USER level logs things for users need and should not be verbose. There is an Error call which falls under USER.

To initialize the logging system from your application, call Init:

logLevel := func() int {
	ll, err := cfg.Int("LOGGING_LEVEL")
	if err != nil {
		return log.DEV
	}
	return ll
}

log.Init(os.Stderr, logLevel, log.Ldefault)

To write to the log you can make calls like this:

log.Dev(ctx, "CreateUser", "Started : Email[%s]", nu.Email)
log.Error(ctx, "CreateUser", err, "Completed")

The API for Dev and User follow this convention:

log.User(ctx, "funcName", "formatted message %s", values)

ctx

A ctx is a unique id that can be used to trace an entire session or request. This value should be generated as early as possible and passed through out the different calls.

funcName

Provide the name of the function the log statement is being declared in. This can take on a type name in the case of the method (type.method).

formatted message, values

Any string can be provided but it does support a formatted message. Values would be substituted if provided. This messaging is up to you.

Index

• Constants
• func Dev(traceID string, funcName string, format string, a ...interface{})
• func DevOffset(traceID string, offset int, funcName string, format string, a ...interface{})
• func Error(traceID string, funcName string, err error, format string, a ...interface{})
• func ErrorOffset(traceID string, offset int, funcName string, err error, format string, a ...interface{})
• func Fatal(traceID string, funcName string, format string, a ...interface{})
• func FatalOffset(traceID string, offset int, funcName string, format string, a ...interface{})
• func Init(w io.Writer, level func() int, flags int)
• func User(traceID string, funcName string, format string, a ...interface{})
• func UserOffset(traceID string, offset int, funcName string, format string, a ...interface{})
• type Logger
  • func New(w io.Writer, levelHandler func() int, flags int) *Logger
  • func (l *Logger) Dev(traceID string, funcName string, format string, a ...interface{})
  • func (l *Logger) DevOffset(traceID string, offset int, funcName string, format string, a ...interface{})
  • func (l *Logger) Error(traceID string, funcName string, err error, format string, a ...interface{})
  • func (l *Logger) ErrorOffset(traceID string, offset int, funcName string, err error, format string, a ...interface{})
  • func (l *Logger) Fatal(traceID string, funcName string, format string, a ...interface{})
  • func (l *Logger) FatalOffset(traceID string, offset int, funcName string, format string, a ...interface{})
  • func (l *Logger) User(traceID string, funcName string, format string, a ...interface{})
  • func (l *Logger) UserOffset(traceID string, offset int, funcName string, format string, a ...interface{})

Examples

• Dev

Package files

doc.go log.go log_default.go

Constants

const (
    NONE int = iota
    DEV
    USER
)

Level constants that define the supported usable LogLevel.

const (
    // Ldate enables the date in the local time zone: 2009/01/23
    Ldate = 1 << iota
    // Ltime enables the time in the local time zone: 01:23:23
    Ltime
    // Lmicroseconds enables microsecond resolution: 01:23:23.123123.  assumes Ltime.
    Lmicroseconds
    // Llongfile enables full file name and line number: /a/b/c/d.go:23
    Llongfile
    // Lshortfile enables final file name element and line number: d.go:23. overrides Llongfile
    Lshortfile
    // LUTC enables if Ldate or Ltime is set, use UTC rather than the local time zone
    LUTC
    // LstdFlags enables initial values for the standard logger
    LstdFlags = Ldate | Ltime
    // Ldefault enables intial values for the default kit logger
    Ldefault = log.Ldate | log.Ltime | log.Lshortfile
)

func Dev

func Dev(traceID string, funcName string, format string, a ...interface{})

Dev logs trace information for developers.

func DevOffset

func DevOffset(traceID string, offset int, funcName string, format string, a ...interface{})

DevOffset logs trace information for developers with a offset option to expand the caller level.

func Error

func Error(traceID string, funcName string, err error, format string, a ...interface{})

Error logs trace information that are errors.

func ErrorOffset

func ErrorOffset(traceID string, offset int, funcName string, err error, format string, a ...interface{})

ErrorOffset logs trace information that are errors with a offset option to expand the caller level.

func Fatal

func Fatal(traceID string, funcName string, format string, a ...interface{})

Fatal logs trace information for users and terminates the app.

func FatalOffset

func FatalOffset(traceID string, offset int, funcName string, format string, a ...interface{})

FatalOffset logs trace information for users and terminates the app with a offset expand the caller level.

func Init

func Init(w io.Writer, level func() int, flags int)

Init initializes the default logger to allow usage of the global log functions.

func User

func User(traceID string, funcName string, format string, a ...interface{})

User logs trace information for users.

func UserOffset

func UserOffset(traceID string, offset int, funcName string, format string, a ...interface{})

UserOffset logs trace information for users with a offset option to expand the caller level.

type Logger

type Logger struct {
    *log.Logger
    // contains filtered or unexported fields
}

Logger contains a standard logger for all logging.

func New

func New(w io.Writer, levelHandler func() int, flags int) *Logger

New returns a instance of a logger.

func (*Logger) Dev

func (l *Logger) Dev(traceID string, funcName string, format string, a ...interface{})

Dev logs trace information for developers.

func (*Logger) DevOffset

func (l *Logger) DevOffset(traceID string, offset int, funcName string, format string, a ...interface{})

DevOffset logs trace information for developers with a offset option to expand the caller level.

func (*Logger) Error

func (l *Logger) Error(traceID string, funcName string, err error, format string, a ...interface{})

Error logs trace information that are errors.

func (*Logger) ErrorOffset

func (l *Logger) ErrorOffset(traceID string, offset int, funcName string, err error, format string, a ...interface{})

ErrorOffset logs trace information that are errors with a offset option to expand the caller level.

func (*Logger) Fatal

func (l *Logger) Fatal(traceID string, funcName string, format string, a ...interface{})

Fatal logs trace information for users and terminates the app.

func (*Logger) FatalOffset

func (l *Logger) FatalOffset(traceID string, offset int, funcName string, format string, a ...interface{})

FatalOffset logs trace information for users and terminates the app with a offset expand the caller level.

func (*Logger) User

func (l *Logger) User(traceID string, funcName string, format string, a ...interface{})

User logs trace information for users.

func (*Logger) UserOffset

func (l *Logger) UserOffset(traceID string, offset int, funcName string, format string, a ...interface{})

UserOffset logs trace information for users with a offset option to expand the caller level.

---

Generated by godoc2md

Documentation

Overview

Package log provides a simple layer above the standard library logging package. The base API provides two logging levels, DEV and USER. The DEV level logs things developers need and can be verbose. The USER level logs things for users need and should not be verbose. There is an Error call which falls under USER.

To initialize the logging system from your application, call Init:

logLevel := func() int {
	ll, err := cfg.Int("LOGGING_LEVEL")
	if err != nil {
		return log.DEV
	}
	return ll
}

log.Init(os.Stderr, logLevel, log.Ldefault)

To write to the log you can make calls like this:

log.Dev(ctx, "CreateUser", "Started : Email[%s]", nu.Email)
log.Error(ctx, "CreateUser", err, "Completed")

The API for Dev and User follow this convention:

log.User(ctx, "funcName", "formatted message %s", values)

ctx

A ctx is a unique id that can be used to trace an entire session or request. This value should be generated as early as possible and passed through out the different calls.

funcName

Provide the name of the function the log statement is being declared in. This can take on a type name in the case of the method (type.method).

formatted message, values

Any string can be provided but it does support a formatted message. Values would be substituted if provided. This messaging is up to you.

Index

• Constants
• func Dev(traceID string, funcName string, format string, a ...interface{})
• func DevOffset(traceID string, offset int, funcName string, format string, a ...interface{})
• func Error(traceID string, funcName string, err error, format string, a ...interface{})
• func ErrorOffset(traceID string, offset int, funcName string, err error, format string, ...)
• func Fatal(traceID string, funcName string, format string, a ...interface{})
• func FatalOffset(traceID string, offset int, funcName string, format string, a ...interface{})
• func Init(w io.Writer, level func() int, flags int)
• func User(traceID string, funcName string, format string, a ...interface{})
• func UserOffset(traceID string, offset int, funcName string, format string, a ...interface{})
• type Logger
  • func New(w io.Writer, levelHandler func() int, flags int) *Logger
  • func (l *Logger) Dev(traceID string, funcName string, format string, a ...interface{})
  • func (l *Logger) DevOffset(traceID string, offset int, funcName string, format string, a ...interface{})
  • func (l *Logger) Error(traceID string, funcName string, err error, format string, a ...interface{})
  • func (l *Logger) ErrorOffset(traceID string, offset int, funcName string, err error, format string, ...)
  • func (l *Logger) Fatal(traceID string, funcName string, format string, a ...interface{})
  • func (l *Logger) FatalOffset(traceID string, offset int, funcName string, format string, a ...interface{})
  • func (l *Logger) User(traceID string, funcName string, format string, a ...interface{})
  • func (l *Logger) UserOffset(traceID string, offset int, funcName string, format string, a ...interface{})

Examples

• Dev

Constants

const (
	NONE int = iota
	DEV
	USER
)

Level constants that define the supported usable LogLevel.

const (
	// Ldate enables the date in the local time zone: 2009/01/23
	Ldate = 1 << iota
	// Ltime enables the time in the local time zone: 01:23:23
	Ltime
	// Lmicroseconds enables microsecond resolution: 01:23:23.123123.  assumes Ltime.
	Lmicroseconds
	// Llongfile enables full file name and line number: /a/b/c/d.go:23
	Llongfile
	// Lshortfile enables final file name element and line number: d.go:23. overrides Llongfile
	Lshortfile
	// LUTC enables if Ldate or Ltime is set, use UTC rather than the local time zone
	LUTC
	// LstdFlags enables initial values for the standard logger
	LstdFlags = Ldate | Ltime
	// Ldefault enables intial values for the default kit logger
	Ldefault = log.Ldate | log.Ltime | log.Lshortfile
)

Functions

func Dev

func Dev(traceID string, funcName string, format string, a ...interface{})

Dev logs trace information for developers.

Example

ExampleDev shows how to use the log package.

package main

import (
	"errors"
	"os"

	"github.com/ardanlabs/kit/log"
)

func main() {

	// Init the log package for stdout. Hardcode the logging level
	// function to use USER level logging.
	log.Init(os.Stdout, func() int { return log.USER }, log.Ldefault)

	// Write a simple log line with no formatting.
	log.User("traceID", "ExampleDev", "This is a simple line with no formatting")

	// Write a simple log line with formatting.
	log.User("traceID", "ExampleDev", "This is a simple line with no formatting %d", 10)

	// Write a message error for the user.
	log.Error("traceID", "ExampleDev", errors.New("A user error"), "testing error")

	// Write a message error for the user with formatting.
	log.Error("traceID", "ExampleDev", errors.New("A user error"), "testing error %s", "value")

	// Write a message error for the developer only.
	log.Dev("traceID", "ExampleDev", "Formatting %v", 42)

	// Write a simple log line with no formatting.
	log.UserOffset("traceID", 3, "ExampleDev", "This is a simple line with no formatting")

	// Write a simple log line with formatting.
	log.UserOffset("traceID", 3, "ExampleDev", "This is a simple line with no formatting %d", 10)

	// Write a message error for the user.
	log.ErrorOffset("traceID", 3, "ExampleDev", errors.New("A user error"), "testing error")

	// Write a message error for the user with formatting.
	log.ErrorOffset("traceID", 3, "ExampleDev", errors.New("A user error"), "testing error %s", "value")

	// Write a message error for the developer only.
	log.DevOffset("traceID", 3, "ExampleDev", "Formatting %v", 42)
}

func DevOffset

func DevOffset(traceID string, offset int, funcName string, format string, a ...interface{})

DevOffset logs trace information for developers with a offset option to expand the caller level.

func Error

func Error(traceID string, funcName string, err error, format string, a ...interface{})

Error logs trace information that are errors.

func ErrorOffset

func ErrorOffset(traceID string, offset int, funcName string, err error, format string, a ...interface{})

ErrorOffset logs trace information that are errors with a offset option to expand the caller level.

func Fatal

func Fatal(traceID string, funcName string, format string, a ...interface{})

Fatal logs trace information for users and terminates the app.

func FatalOffset

func FatalOffset(traceID string, offset int, funcName string, format string, a ...interface{})

FatalOffset logs trace information for users and terminates the app with a offset expand the caller level.

func Init

func Init(w io.Writer, level func() int, flags int)

Init initializes the default logger to allow usage of the global log functions.

func User

func User(traceID string, funcName string, format string, a ...interface{})

User logs trace information for users.

func UserOffset

func UserOffset(traceID string, offset int, funcName string, format string, a ...interface{})

UserOffset logs trace information for users with a offset option to expand the caller level.

Types

type Logger

type Logger struct {
	*log.Logger
	// contains filtered or unexported fields
}

Logger contains a standard logger for all logging.

func New

func New(w io.Writer, levelHandler func() int, flags int) *Logger

New returns a instance of a logger.

func (*Logger) Dev

func (l *Logger) Dev(traceID string, funcName string, format string, a ...interface{})

Dev logs trace information for developers.

func (*Logger) DevOffset

func (l *Logger) DevOffset(traceID string, offset int, funcName string, format string, a ...interface{})

DevOffset logs trace information for developers with a offset option to expand the caller level.

func (*Logger) Error

func (l *Logger) Error(traceID string, funcName string, err error, format string, a ...interface{})

Error logs trace information that are errors.

func (*Logger) ErrorOffset

func (l *Logger) ErrorOffset(traceID string, offset int, funcName string, err error, format string, a ...interface{})

ErrorOffset logs trace information that are errors with a offset option to expand the caller level.

func (*Logger) Fatal

func (l *Logger) Fatal(traceID string, funcName string, format string, a ...interface{})

Fatal logs trace information for users and terminates the app.

func (*Logger) FatalOffset

func (l *Logger) FatalOffset(traceID string, offset int, funcName string, format string, a ...interface{})

FatalOffset logs trace information for users and terminates the app with a offset expand the caller level.

func (*Logger) User

func (l *Logger) User(traceID string, funcName string, format string, a ...interface{})

User logs trace information for users.

func (*Logger) UserOffset

func (l *Logger) UserOffset(traceID string, offset int, funcName string, format string, a ...interface{})

UserOffset logs trace information for users with a offset option to expand the caller level.