logging/CLAUDE.md

logging

Shared Go library with logging primitives for all Shiny backend services.

Shared Documentation

@../docs/claude/architecture.md @../docs/claude/go-services.md @../docs/claude/conventions.md

Library Information

Purpose

Single home for the slog setup, context-logger helpers, request-logging middleware and the MockLogger test helper that were previously copied (with drift) into every backend service.

Usage

import (
    "gitea.unbound.se/shiny/logging"
    logmw "gitea.unbound.se/shiny/logging/middleware"
)

// Configure the slog default logger (format: text | json | otel).
logger := logging.SetupLogger(cli.LogLevel, cli.LogFormat, serviceName, buildVersion)

// Carry a logger on the request context.
ctx = logging.ContextWithLogger(ctx, logger)
logger = logging.LoggerFromContext(ctx)

// Debug-log request/response bodies.
handler = logmw.RequestLogger(logger)(handler)

In tests:

m := logging.NewMockLogger()
// ... exercise code with m.Logger() ...
m.Check(t, []string{"level=INFO msg=\"...\""})

Exported API

• SetupLogger(logLevel, logFormat, serviceName, buildVersion string) *slog.Logger
• ContextWithLogger(ctx, *slog.Logger) context.Context / LoggerFromContext(ctx) *slog.Logger
• Logger interface; NewMockLogger() *MockLogger (+ MockLogger.Logger(), MockLogger.Check(t, want)).
• logging/middleware.RequestLogger(logger) func(http.Handler) http.Handler.

Notes

• MockLogger currently lives in the main package, so testify is a non-test dependency of the module. Moving it to a logging/logtest sub-package is a tracked low-priority follow-up — it's a breaking import change for the ~13 services that reference logging.NewMockLogger, so it is deferred until a coordinated bump (Ambix 019ecabc).

Conventions

Standard Shiny library scaffolding: gofumpt/goimports -local, golangci-lint, gitleaks and conventional-commit checks via pre-commit; coverage-regression gate in CI (.testcoverage.yml); releases auto-tagged from conventional commits by the shared Release workflow. Bump the consuming services' go.mod after a release.