charmed-log
Structured, leveled, styled logging in Go with Charm Log v2 (charm.land/log/v2, the charmbracelet logger): package level and custom loggers, key value pairs, levels, text, JSON, and logfmt formatters, colored log output with Lip Gloss v2 styles, slog handler and standard log adapters, and logging from inside a Bubble Tea program to a debug log file. Use when adding, configuring, or restyling Charm Log output in a Go CLI or TUI, or migrating from github.com/charmbracelet/log. Not for other Go loggers such as zap or zerolog, or for printing UI (charmed-lipgloss).
tpscloud · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add tpscloud/charmedimsure --skill charmed-log技能说明
name: charmed-log description: "Structured, leveled, styled logging in Go with Charm Log v2 (charm.land/log/v2, the charmbracelet logger): package level and custom loggers, key value pairs, levels, text, JSON, and logfmt formatters, colored log output with Lip Gloss v2 styles, slog handler and standard log adapters, and logging from inside a Bubble Tea program to a debug log file. Use when adding, configuring, or restyling Charm Log output in a Go CLI or TUI, or migrating from github.com/charmbracelet/log. Not for other Go loggers such as zap or zerolog, or for printing UI (charmed-lipgloss)." license: "MIT"
Charm Log v2
Add structured, leveled, colored logging to a Go CLI or TUI with Charm Log v2, including JSON and logfmt output, slog adapters, and plain-text log files from inside Bubble Tea.
Import as "charm.land/log/v2". Go blocks are trimmed from
complete programs
that build against the pinned modules.
If the project's go.mod still requires github.com/charmbracelet/log
(pre-v2), the v2 APIs here do not apply. Use go doc against the
project's version and keep its import paths unless the user asks to
migrate.
Workflow
- Pick the logger: the package level
logfunctions for a small CLI, orlog.NewWithOptions(w, log.Options{...})for a dedicated one. - Set the level (
log.ParseLevelfor config text), the formatter, and the writer when you create the logger: the color profile comes from that writer. - Log a message followed by key value pairs in even numbers; use
Withfor pairs every line should carry. - Inside a Bubble Tea program, send logs to a file with
tea.LogToFileWith. For code that logs throughlog/slog, hand itslog.New(logger). - Run it and check level filtering, the output stream, and structured output with its consumer; in a TUI, confirm logs reach the file and not the screen. On a failure, compare against Mistakes below.
Basics
The package level logger writes to stderr at info level with timestamps (see the basic example):
// examples/charmed-log/basic/main.go
log.Info("starting", "project", "site")
log.Debug("hidden at info level")
log.Warn("disk almost full", "free", "1.2G")
log.Error("check failed", "err", errors.New("invalid configuration"))
log.Print("no level prefix, always printed")
log.SetLevel(log.DebugLevel)
log.SetReportCaller(true)
Fatal logs and calls os.Exit(1). Print ignores the level. A dedicated
logger:
// examples/charmed-log/basic/main.go
logger := log.NewWithOptions(os.Stderr, log.Options{
ReportTimestamp: true,
TimeFormat: time.Kitchen,
Prefix: "tasks",
Level: log.InfoLevel,
})
projectLog := logger.With("project", "site", "task", "build") // child with fixed pairs
projectLog.Info("completed")
logger.Infof("%d of %d done", 3, 6)
log.New(w) has no timestamp, unlike the package logger; call
SetReportTimestamp(true) for the same look.
Read references/api.md for the full setter list,
levels, caller and time options, context helpers, and every Styles field.
Formatters
The structured example includes formatters and custom styles. Run it from a repository checkout:
cd examples
go run ./charmed-log/structured
// examples/charmed-log/structured/main.go
jsonLogger := log.NewWithOptions(os.Stdout, log.Options{Formatter: log.JSONFormatter, ReportTimestamp: true})
jsonLogger.Info("json line", "project", "api", "ok", true)
fmtLogger := log.New(os.Stdout)
fmtLogger.SetFormatter(log.LogfmtFormatter)
TextFormatter (default, colored, human oriented), JSONFormatter, and
LogfmtFormatter. Colors are chosen from the output writer's profile,
detected once when the logger is created: a logger built on a file writes
plain text. Force a profile with
SetColorProfile(colorprofile.TrueColor) from
github.com/charmbracelet/colorprofile.
Styles
log.DefaultStyles() returns a *Styles of Lip Gloss v2 values with a style
per element, a Levels map, and Keys and Values maps for per field
overrides:
// examples/charmed-log/structured/main.go
styles := log.DefaultStyles()
styles.Levels[log.ErrorLevel] = lipgloss.NewStyle().
SetString("ERROR").
Padding(0, 1).
Background(lipgloss.Color("204")).
Foreground(lipgloss.Color("0"))
styles.Keys["err"] = lipgloss.NewStyle().Foreground(lipgloss.Color("204"))
styles.Values["err"] = lipgloss.NewStyle().Bold(true)
styled := log.New(os.Stderr)
styled.SetStyles(styles)
SetString on the level style changes the label text.
slog and the standard library
A *log.Logger is a slog.Handler, so libraries that log through
log/slog can be pointed at it. It also produces a standard *log.Logger
for APIs that demand one (see the adapter example):
// examples/charmed-log/slog/main.go
handler := log.NewWithOptions(os.Stderr, log.Options{ReportTimestamp: true, Level: log.DebugLevel})
sl := slog.New(handler)
sl.Info("from slog", "project", "worker")
// Only code that receives sl logs through Charm. Package level calls such
// as slog.Info still use slog's own default until slog.SetDefault(sl).
std := handler.StandardLog(log.StandardLogOptions{ForceLevel: log.WarnLevel})
std.Println("from the standard logger, forced to warn")
slog.New(handler) builds one logger; pass it to the code that should use
it. Redirecting every package level slog call in the process is a
separate, global decision: slog.SetDefault(sl), which also captures the
standard library log package. Do that in main, not in a library.
Inside Bubble Tea
The renderer owns the
阅读完整来源 ↗