# 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

```go
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:

```go
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.