logcopter

README

logcopter

logcopter is a small zerolog-backed logging utility for Go projects. It adds stable area names, hierarchical per-area levels, reload-aware package loggers, and code generation for package-local log variables.

The intended application integration point is Glazed: applications keep using github.com/go-go-golems/glazed/pkg/cmds/logging, and Glazed's logging section configures logcopter behind the scenes.

Runtime usage

Create package-local loggers with stable area names:

package render

import "github.com/go-go-golems/logcopter/pkg/logcopter"

var log = logcopter.Package("app.view.render")

func Render() {
    log.Debug().Msg("rendering view")
}

Configure the default manager once during application startup:

base := logcopter.NewLogger(logcopter.OutputConfig{
    Output:    logcopter.OutputStderr,
    Format:    logcopter.FormatText,
    Timestamp: true,
})

err := logcopter.Configure(base, logcopter.Config{
    Level: "info",
    Areas: map[string]string{
        "app.view": "debug",
        "app.view.render": "trace",
        "app.db": "warn",
    },
})

Area lookup uses longest-prefix matching. app.view.render.partial inherits app.view.render, while app.db.sql inherits app.db.

Generated package loggers

logcopter-gen writes a small generated file into each package:

// Code generated by logcopter-gen; DO NOT EDIT.
package render

import logcopter "github.com/go-go-golems/logcopter/pkg/logcopter"

var log = logcopter.Package("app.view.render")

Example generator invocation:

go run ./cmd/logcopter-gen \
  -area-prefix app \
  -strip-prefix github.com/acme/server/internal \
  ./internal/...

Useful CI mode:

go run ./cmd/logcopter-gen \
  -area-prefix app \
  -strip-prefix github.com/acme/server/internal \
  -check \
  ./internal/...

A package can also record the generator invocation with go generate:

//go:generate go run github.com/go-go-golems/logcopter/cmd/logcopter-gen -area-prefix app -strip-prefix github.com/acme/server/internal ./...

This repository's CI includes a small generated-file check for the examples/library-prefix tree.

Glazed configuration

Glazed applications use the existing logging helpers. No separate logcopter adapter package is needed.

logging.AddLoggingSectionToRootCommand(rootCmd, "my-app")
// later, after Cobra parsed flags:
logging.InitLoggerFromCobra(cmd)

YAML application config:

logging:
  log-level: info
  log-format: text
  areas:
    app.view.render: trace
    app.db: warn

CLI overrides support both colon and equals syntax:

my-app --log-area app.view:debug --log-area app.db=warn

Reusable logcopter profile files can be passed explicitly:

my-app --log-config ~/.config/logcopter/profiles/dev.yaml

Wrapped profile shape:

logging:
  log-level: info
  areas:
    app.view.render: trace
    lib.protocol: debug

Direct logcopter-only profile shape:

level: info
format: text
areas:
  app.view.render: trace
  lib.protocol: debug

Merge order in the Glazed Cobra path is: defaults, explicit --log-config files in command-line order, then direct CLI flags.

Raw logger caveat

Logger.Raw() returns a zerolog logger for interop, but a captured raw logger is not reload-aware. Prefer the wrapper methods (Info, Debug, Trace, etc.) for package-local loggers that should observe future configuration reloads.

Zerolog global level interaction

Logcopter area filtering works by setting levels on per-area child loggers. A process-wide zerolog global level that is too restrictive can suppress those children. Glazed keeps zerolog's global gate open and applies normal filtering to the conventional global logger plus logcopter's area children.

Examples

• examples/basic shows direct runtime configuration.
• examples/library-prefix shows a reusable library-style area prefix.
• Glazed CLI configuration examples live in glazed/pkg/doc/topics/logging-section.md.