# Log
A minimal and colorful Go logging library.
It provides a leveled structured human readable logger with a small API. Unlike
[standard `log`][stdlog], the Charm logger provides customizable colorful human
readable logging with batteries included.
- Uses [Lip Gloss][lipgloss] to style and colorize the output.
- Colorful, human readable format.
- Ability to customize the time stamp format.
- Skips caller frames and marks function as helpers.
- Leveled logging.
- Text, JSON, and Logfmt formatters.
- Store and retrieve logger in and from context.
- Slog handler.
- Standard log adapter.
## Usage
Use `go get` to download the dependency.
```bash
go get charm.land/log/v2@latest
```
Then, `import` it in your Go files:
```go
import "charm.land/log/v2"
```
The Charm logger comes with a global package-wise logger with timestamps turned
on, and the logging level set to `info`.
```go
log.Debug("Cookie ") // won't print anything
log.Info("Hello World!")
```
All logging levels accept optional key/value pairs to be printed along with a
message.
```go
err := fmt.Errorf("too much sugar")
log.Error("failed to bake cookies", "err", err)
```
You can use `log.Print()` to print messages without a level prefix.
```go
log.Print("Baking 101")
// 2023/01/04 10:04:06 Baking 101
```
### New loggers
Use `New()` to create new loggers.
```go
logger := log.New(os.Stderr)
if butter {
logger.Warn("chewy!", "butter", true)
}
```
### Levels
Log offers multiple levels to filter your logs on. Available levels are:
```go
log.DebugLevel
log.InfoLevel
log.WarnLevel
log.ErrorLevel
log.FatalLevel
```
Use `log.SetLevel()` to set the log level. You can also create a new logger with
a specific log level using `log.Options{Level: }`.
Use the corresponding function to log a message:
```go
err := errors.New("Baking error 101")
log.Debug(err)
log.Info(err)
log.Warn(err)
log.Error(err)
log.Fatal(err) // this calls os.Exit(1)
log.Print(err) // prints regardless of log level
```
Or use the formatter variant:
```go
format := "%s %d"
log.Debugf(format, "chocolate", 10)
log.Warnf(format, "adding more", 5)
log.Errorf(format, "increasing temp", 420)
log.Fatalf(format, "too hot!", 500) // this calls os.Exit(1)
log.Printf(format, "baking cookies") // prints regardless of log level
// Use these in conjunction with `With(...)` to add more context
log.With("err", err).Errorf("unable to start %s", "oven")
```
### Structured
All the functions above take a message and key-value pairs of anything. The
message can also be of type any.
```go
ingredients := []string{"flour", "butter", "sugar", "chocolate"}
log.Debug("Available ingredients", "ingredients", ingredients)
// DEBUG Available ingredients ingredients="[flour butter sugar chocolate]"
```
### Options
You can customize the logger with options. Use `log.NewWithOptions()` and
`log.Options{}` to customize your new logger.
```go
logger := log.NewWithOptions(os.Stderr, log.Options{
ReportCaller: true,
ReportTimestamp: true,
TimeFormat: time.Kitchen,
Prefix: "Baking ",
})
logger.Info("Starting oven!", "degree", 375)
time.Sleep(10 * time.Minute)
logger.Info("Finished baking")
```
You can also use logger setters to customize the logger.
```go
logger := log.New(os.Stderr)
logger.SetReportTimestamp(false)
logger.SetReportCaller(false)
logger.SetLevel(log.DebugLevel)
```
Use `log.SetFormatter()` or `log.Options{Formatter: }` to change the output
format. Available options are:
- `log.TextFormatter` (_default_)
- `log.JSONFormatter`
- `log.LogfmtFormatter`
> **Note** styling only affects the `TextFormatter`. Styling is disabled if the
> output is not a TTY.
For a list of available options, refer to [options.go](./options.go).
### Styles
You can customize the logger styles using [Lipgloss][lipgloss]. The styles are
defined at a global level in [styles.go](./styles.go).
```go
// Override the default error level style.
styles := log.DefaultStyles()
styles.Levels[log.ErrorLevel] = lipgloss.NewStyle().
SetString("ERROR!!").
Padding(0, 1, 0, 1).
Background(lipgloss.Color("204")).
Foreground(lipgloss.Color("0"))
// Add a custom style for key `err`
styles.Keys["err"] = lipgloss.NewStyle().Foreground(lipgloss.Color("204"))
styles.Values["err"] = lipgloss.NewStyle().Bold(true)
logger := log.New(os.Stderr)
logger.SetStyles(styles)
logger.Error("Whoops!", "err", "kitchen on fire")
```
### Sub-logger
Create sub-loggers with their specific fields.
```go
logger := log.NewWithOptions(os.Stderr, log.Options{
Prefix: "Baking "
})
batch2 := logger.With("batch", 2, "chocolateChips", true)
batch2.Debug("Preparing batch 2...")
batch2.Debug("Adding chocolate chips")
```
### Format Messages
You can use `fmt.Sprintf()` to format messages.
```go
for item := 1; i <= 100; i++ {
log.Info(fmt.Sprintf("Baking %d/100...", item))
}
```
Or arguments:
```go
for temp := 375; temp <= 400; temp++ {
log.Info("Increasing temperature", "degree", fmt.Sprintf("%d°F", temp))
}
```
### Helper Functions
Skip caller frames in helper functions. Similar to what you can do with
`testing.TB().Helper()`.
```go
func startOven(degree int) {
log.Helper()
log.Info("Starting oven", "degree", degree)
}
log.SetReportCaller(true)
startOven(400) // INFO Starting oven degree=400
```
This will use the _caller_ function (`startOven`) line number instead of the
logging function (`log.Info`) to report the source location.
### Slog Handler
You can use Log as an [`log/slog`](https://pkg.go.dev/log/slog) handler. Just
pass a logger instance to Slog and you're good to go.
```go
handler := log.New(os.Stderr)
logger := slog.New(handler)
logger.Error("meow?")
```
### Standard Log Adapter
Some Go libraries, especially the ones in the standard library, will only accept
the [standard logger][stdlog] interface. For instance, the HTTP Server from
`net/http` will only take a `*log.Logger` for its `ErrorLog` field.
For this, you can use the standard log adapter, which simply wraps the logger in
a `*log.Logger` interface.
```go
logger := log.NewWithOptions(os.Stderr, log.Options{Prefix: "http"})
stdlog := logger.StandardLog(log.StandardLogOptions{
ForceLevel: log.ErrorLevel,
})
s := &http.Server{
Addr: ":8080",
Handler: handler,
ErrorLog: stdlog,
}
stdlog.Printf("Failed to make bake request, %s", fmt.Errorf("temperature is too low"))
// ERROR http: Failed to make bake request, temperature is too low
```
## Gum
Log integrates with [Gum][gum] to log messages to output. Use `gum log [flags]
[message]` to handle logging in your shell scripts. See
[charmbracelet/gum](https://github.com/charmbracelet/gum#log) for more
information.
[gum]: https://github.com/charmbracelet/gum
[lipgloss]: https://github.com/charmbracelet/lipgloss
[stdlog]: https://pkg.go.dev/log
## License
[MIT](https://github.com/charmbracelet/log/raw/master/LICENSE)
---
Part of [Charm](https://charm.sh).
Charm热爱开源 • Charm loves open source • نحنُ نحب المصادر المفتوحة