README
¶
Captain's Log
A simple logging library for Go
- cross-platform colors
- multiple log levels
- structured logging
- caller detection
Installation
go get github.com/vincentfiestada/captainslog/v2
Usage
This library is designed to provide a familiar yet powerful interface for logging. Each logging method accepts a format string and arguments. Structured logging is supported right out of the box. The Logger allows you to turn colors on/off, specify a datetime format, set the logging threshold, and even provide your own function to control how logs are written.
package main
import (
"github.com/vincentfiestada/captainslog/v2"
)
var log = captainslog.NewLogger()
func main() {
log.Trace("this is %s", "captainslog")
log.Debug("this is %s", "captainslog")
log.Info("this is %s", "captainslog")
log.Warn("this is %s", "captainslog")
log.Error("this is %s", "captainslog")
log.Fields(
log.I("captain", "picard"),
log.I("first officer", "riker"),
log.I("science officer", "data"),
log.I("medical officer", "crusher"),
log.I("chief engineer", "la forge"),
log.I("security officer", "worf"),
).Info("starship enterprise")
}
Format
There are several log formats included that you can choose from. It's also easy to write your own custom function to print logs just the way you want to.
Performance
The main goals of this library are convenience and familiarity for programmers, but it should have reasonable performance for most projects. To see for yourself, run the benchmarks using ./tools benchmark.
Development
Please read the Contribution Guide before you proceed. This project uses tools that run on Powershell Core. To get started,
./tools help
Copyright
Copyright 2019-2021 Vincent Fiestada. This project is released under a BSD-3-Clause License.
Icon made by Freepik.
Documentation
¶
Overview ¶
Package captainslog is a simple logging library with support for multiple levels and automatic caller name detection
Example ¶
log := captainslog.NewLogger()
log.Trace("%d", 1)
log.Debug("%d", 2)
log.Info("%d", 3)
log.Warn("%d", 4)
log.Error("%d", 5)
log.Field("captain", "picard").Trace("starship enterprise")
log.Field("captain", "picard").Debug("starship enterprise")
log.Field("captain", "picard").Info("starship enterprise")
log.Field("captain", "picard").Warn("starship enterprise")
log.Field("captain", "picard").Error("starship enterprise")
log.Fields(
log.I("captain", "picard"),
log.I("first officer", "riker"),
log.I("science officer", "data"),
log.I("medical officer", "crusher"),
log.I("chief engineer", "la forge"),
log.I("security officer", "worf"),
).Info("starship enterprise")
Output:
Index ¶
- Constants
- type Logger
- func (log *Logger) Debug(format string, args ...interface{})
- func (log *Logger) Error(format string, args ...interface{})
- func (log *Logger) Exit(code int, format string, args ...interface{})
- func (log *Logger) Fatal(format string, args ...interface{})
- func (log *Logger) Field(name string, value interface{}) *msg.Message
- func (log *Logger) Fields(fields ...msg.Field) *msg.Message
- func (log *Logger) I(name string, value interface{}) msg.Field
- func (log *Logger) Info(format string, args ...interface{})
- func (log *Logger) Panic(format string, args ...interface{})
- func (log *Logger) Trace(format string, args ...interface{})
- func (log *Logger) Warn(format string, args ...interface{})
Examples ¶
Constants ¶
const (
ISO8601 = "01-02-2006 15:04:05 MST"
)
Defaults
const (
Version = "2.4.3"
)
Package information
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Logger ¶
type Logger struct {
// name of the logger; leave empty to log the current function
Name string
Level int
HasColor bool
// layout string used to format the time. See https://pkg.go.dev/time?tab=doc#Time.Format
TimeFormat string
// maximum caller name length to display
NameCutoff int
Stdout *os.File
Stderr *os.File
Format msg.Format
}
Logger is an object for logging
Example ¶
log := captainslog.NewLogger()
// Specify a name to use instead of the calling function
log.Name = "picard"
// Specify a time format (see https://golang.org/pkg/time/#Time.Format)
log.TimeFormat = "Mon 2006 Jan 2 15:04:05"
// Turn colors on or off (default: true)
log.HasColor = true
// Set a maximum length for the name (default: 15)
// If the name is too long, captainslog will try
// first to remove the path, then the method parent,
// then truncate
log.NameCutoff = 100
// Use the output streams of your choice
_, log.Stdout, _ = os.Pipe()
_, log.Stderr, _ = os.Pipe()
// See also the 'captainslog/format' package
log.Info("engage")
Output:
func NewLogger ¶
func NewLogger() *Logger
NewLogger returns a new logger with the specified minimum logging level
func (*Logger) Field ¶
Field starts a message with a data field
Example ¶
log := captainslog.NewLogger()
// Perform structured logging by chaining calls to Field()
log.Field("phasers", 1).Field("photon torpedos", 1).Warn("weapons locked")
Output:
func (*Logger) Fields ¶
Fields starts a message with multiple data fields
Example ¶
log := captainslog.NewLogger()
// log.Fields() makes structured logging easier
// through key-value pairs
log.Fields(
[2]interface{}{"phasers", 1},
[2]interface{}{"photon torpedos", 1},
).Warn("weapons locked")
// log.I() conveniently returns a key-value pair
log.Fields(
log.I("phasers", 1),
log.I("photon torpedos", 1),
).Warn("weapons locked")
Output:
Source Files
Directories