Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/google/deck

Deck provides a flexible logging framework for Go apps.
https://github.com/google/deck

logging

Last synced: about 2 months ago
JSON representation

Deck provides a flexible logging framework for Go apps.

Awesome Lists containing this project

README 

        
# Deck - Flexible Logging Framework for Go



The Deck package provides a flexible logging framework for Go apps. Deck

supports Windows Event Log, syslog, Go's standard logging, logging to file, and

log replays for testing. Deck is extensible, so new log backends can integrate

seamlessly into existing application code.



## Standard Logging



Deck can be a drop in replacement for some other logging packages, with support

for common functions like Info, Error, & Warning. The standard logging functions

write their outputs immediately and don't support additional attributes.



```

deck.Info("an info message")

```



```

deck.Errorf("an %v message", errors.New("error!"))

```



## Extensible Logging with Attributes



Sometimes we want to be able to pass more complex inputs to our log messages.

Deck facilitates this by allowing custom attributes to be attached to log

messages.



When using the `A`ttribute-supporting log functions, the message isn't output

immediately. We use the `With()` function to attach additional metadata to the

message first. The metadata can be anything supported by an attached

[backend](#backends). Once fully marked up with attributes, the `Go()` function

then performs the final write of the message.



In this example, a log message is marked with *Verbosity* level 2.

[Verbosity](#message-verbosity) can be used to dynamically show or hide log

events at runtime.



```

deck.InfoA("a verbose message").With(deck.V(2)).Go()

```



The EventLog backend for Windows supports Event IDs:



```

deck.InfoA("a windows event").With(eventlog.EventID(123)).Go()

```



Multiple attributes can be attributed to the same message:



```

deck.InfoA("a verbose windows event").With(eventlog.EventID(123), deck.V(3)).Go()

```



## Backends



Deck's logging functionality revolves around **backends**. A backend is any

logging destination that deck should write messages to. Backends are

plug-and-play, so you can reconfigure your application's logging behavior simply

by adding and removing different backends.



```

import (

  "github.com/google/deck"

  "github.com/google/deck/backends/logger"

)



deck.Add(logger.Init(os.Stdout, 0))

```



Cross-platform builds can support platform-specific log outputs by calling `Add`

from platform-specific source files.



```

// my_app_windows.go



func init() {

  evt, err := eventlog.Init("My App")

  if err != nil {

    panic(err)

  }

  deck.Add(evt)

}

```



```

// my_app_linux.go



func init() {

  sl, err := syslog.Init("my-app", syslog.LOG_USER)

  if err != nil {

    panic(err)

  }

  deck.Add(sl)

}

```



### eventlog Backend



The eventlog backend is for Windows only. This backend supports logging to the

Windows Event Log. It exports the `EventID` attribute that allows logging

messages with custom Event IDs.



[eventlog Documentation](backends/eventlog/README.md).



### logger Backend



The logger backend is based on Go's core `log` package. It can take any

io.Writer, including os.Stdout, os.Stderr, io.Multiwriter, and any open file

handles.



[logger Documentation](backends/logger/README.md).



### syslog Backend



The syslog backend is based on Go's core `syslog` package for Linux/Unix.



[syslog Documentation](backends/syslog/README.md).



### discard Backend



The discard backend discards all log events. Deck requires at least one backend

to be registered to handle logs. To suppress all output, add the discard

backend.



[discard Documentation](backends/discard/README.md).



### glog Backend



The glog backend provides support for logging to the glog package from

github.com/golang/glog. This backend supports the Depth attribute as well as

exporting a V() attribute for glog's V-style logging.



[glog Documentation](backends/glog/README.md).



### replay Backend



The replay backend provides the ability to record and replay log events for use

in testing.



[replay Documentation](backends/replay/README.md).



## Message Verbosity



Verbosity is a special attribute implemented by the deck core package. The `V()`

function decorates logs with a custom verbosity, and the `SetVerbosity()`

function determines which verbosity levels get output. This allows the verbosity

level to be changed at runtime, such as via a flag or setting.



```

deck.SetVerbosity(*verbosityFlag)

...

log.InfoA("a level one message").With(deck.V(1)).Go()

log.InfoA("a level three message").With(deck.V(3)).Go()

```



In this example, if verbosityFlag is 2 or lower, only *"a level one message"*

will print. If it's 3 or higher, both messages will print. Verbosity defaults to

0, and all non-`A`ttribute functions will be at verbosity 0.



## Custom Decks



The `deck` package builds a global deck whenever it's imported, and most

implementations can just use this deck directly via the package-level logging

functions. For more advanced use cases, multiple decks can be constructed using

`deck.New()`. Each deck can have its own set of attached backends, and supports

the same functionality as the global deck.