README
¶
Simple logging overlay for Arcalot
This is a very simple API abstracting away other logging libraries, such as Go log and the Go test logger. You can use it by running:
go get go.arcalot.io/log
Why create a custom logging library?
Why create a custom logging library, when there are a ton of them already out there?
The answer is simple: to create a clean API we can rely on. Even the log and testing packages in Go don't implement a common API for logging, not to mention the myriad libraries out there. We don't proscribe what library an application should use, but we do wish to standardize how we communicate with these libraries.
Should I use this library for my project?
You can! However, keep in mind, this library is intended for Arcalot, and especially the Arcaflow use case. Features that are not needed here will not be added.
You can always use this library on an as-is basis if you are happy with the feature set and we won't be breaking backwards compatibility in minor versions, but if we need a major change, we may move on from the current API in the next major version.
Using the logger
The easiest way to create a logger is to use the Config struct:
package yourapplication
import "go.arcalot.io/log"
func main() {
logConfig := log.Config{
Level: log.LevelInfo,
Destination: log.DestinationStdout,
Stdout: os.Stdout,
}
logger := log.New(logConfig)
logger.Infof("Hello world!")
}
You should now see a log message on your console. If you wish to log from a test utility, you can do so like this:
package yourapplication_test
import "go.arcalot.io/log"
func TestSomething(t *testing.T) {
logConfig := log.Config{
Level: log.LevelInfo,
Destination: log.DestinationTest,
T: t,
}
logger := log.New(logConfig)
logger.Infof("Hello world!")
}
You can also apply labels to the log messages. This will add metadata to your log messages. Extending the previous example:
package yourapplication_test
import "go.arcalot.io/log"
func TestSomething(t *testing.T) {
logConfig := log.Config{
Level: log.LevelInfo,
Destination: log.DestinationTest,
T: t,
}
logger := log.New(logConfig)
logger = logger.WithLabel("source", "mytest")
logger.Infof("Hello world!")
}
For a more detailed explanation please see our documentation.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BufferWriter ¶
BufferWriter provides a writer that records all log messages. This logger is most useful for tests.
func NewBufferWriter ¶
func NewBufferWriter() BufferWriter
type Config ¶
type Config struct {
// Level sets the minimum log level for the logger.
Level Level `json:"level"`
// Destination is the place the logger writes to.
Destination Destination `json:"destination"`
// T is the Go test for logging purposes.
T *testing.T `json:"-" yaml:"-"`
// Stdout is the standard output used by the DestinationStdout destination. If not set, os.Stdout is used.
Stdout io.Writer `json:"-" yaml:"-"`
}
Config is the configuration for the logger.
type Destination ¶
type Destination string
Destination is the place a LogWriter writes to.
const ( // DestinationStdout writes to the standard output. DestinationStdout Destination = "stdout" // DestinationTest writes the logs to the *testing.T facility. DestinationTest Destination = "test" )
func (Destination) Validate ¶
func (d Destination) Validate() error
type Labels ¶
Labels are applied to a message to indicate where they are coming from or other relevant data.
type Level ¶
type Level string
Level is the logging level.
const ( // LevelDebug logs for debugging purposes. These logs are likely to contain excessive amounts of information. LevelDebug Level = "debug" // LevelInfo logs informational messages. LevelInfo Level = "info" // LevelWarning logs warning messages. LevelWarning Level = "warning" // LevelError logs error messages. LevelError Level = "error" )
func (Level) ShouldPrint ¶
ShouldPrint returns true if the a message at messageLevel should be printed if l is the current minimum level.
type Logger ¶
type Logger interface {
// Debugf logs with the debug log level. This is the finest and least-consequential log type.
Debugf(format string, args ...interface{})
// Infof logs with the Info log level.
Infof(format string, args ...interface{})
// Warningf logs with the Warning log level.
Warningf(format string, args ...interface{})
// Errorf logs with the Error log level.
Errorf(format string, args ...interface{})
// Writef allows logging with convenient programmatic setting of level
Writef(level Level, format string, args ...interface{})
// WithLabel creates a child logger with this label attached.
WithLabel(name string, value string) Logger
}
Logger provides pluggable logging for Arcalot.
func NewGoLogger ¶
NewGoLogger writes to the Go log facility. If no logger is passed, the standard logger is used.
func NewTestLogger ¶
NewTestLogger creates a logger that writes to the Go test output.
type Message ¶
type Message struct {
Timestamp time.Time `json:"timestamp"`
Level Level `json:"level"`
Labels Labels `json:"labels"`
Message string `json:"message"`
}
Message is a single log message.
type Writer ¶
type Writer interface {
// Write writes a message to the output.
Write(Message) error
// Rotate gets called if logs need to be rotated.
Rotate()
io.Closer
}
Writer is an abstraction over the possible logging targets.
func NewGoLogWriter ¶
NewGoLogWriter creates a log writer that writes to the Go log facility. The optional logger parameter can be used to pass one scoped logger, otherwise the global logger is used. If multiple loggers are passed the function will panic.
func NewTestWriter ¶
NewTestWriter returns a writer that logs via the Go test facility.
Source Files