From 815b57fa0dd6cdc246c98d737a617468a59e8300 Mon Sep 17 00:00:00 2001 From: clawbot <35+clawbot@noreply.example.org> Date: Tue, 6 Oct 2026 14:04:18 +0000 Subject: [PATCH] Format the existing Markdown with prettier The one-time reformat of README.md and TODO.md, produced by make fmt with nothing else in it. REPO_POLICIES.md already matched prettier's output and is unchanged. Model: opus-5-5 --- README.md | 159 ++++++++++++++++++++++++++---------------------------- TODO.md | 147 +++++++++++++++++++++++++------------------------- 2 files changed, 149 insertions(+), 157 deletions(-) diff --git a/README.md b/README.md index 09ece22..5c402ae 100644 --- a/README.md +++ b/README.md @@ -3,35 +3,33 @@ ## Summary simplelog is an opinionated logging package designed to facilitate easy and -structured logging in Go applications with an absolute minimum of -boilerplate. +structured logging in Go applications with an absolute minimum of boilerplate. -The idea is that you can add a single import line which replaces the -stdlib `log/slog` default handler, and solve the 90% case for logging. +The idea is that you can add a single import line which replaces the stdlib +`log/slog` default handler, and solve the 90% case for logging. ## Current Status -Released v1.0.0 2024-06-14. Works as intended. No known bugs. +Released v1.0.0 2024-06-14. Works as intended. No known bugs. ## Features -- if output is a tty, outputs pretty color logs -- if output is not a tty, outputs json -- supports delivering each log message via a webhook -- emits every `slog` attribute: those passed to a log call, those - accumulated with `WithAttrs`, and those qualified by `WithGroup`. - `slog.Group` values nest, and `slog.LogValuer` values are resolved. In - json output attributes are object fields (groups become nested objects); - in console output they are appended as `key=value` pairs, with grouped - keys written as `group.key=value`. See - [Attribute output](#attribute-output) for the details worth knowing -- reports a record that could not be delivered as an error from the - handler's `Handle` method. See - [When delivery fails](#when-delivery-fails) for how to receive it +- if output is a tty, outputs pretty color logs +- if output is not a tty, outputs json +- supports delivering each log message via a webhook +- emits every `slog` attribute: those passed to a log call, those accumulated + with `WithAttrs`, and those qualified by `WithGroup`. `slog.Group` values + nest, and `slog.LogValuer` values are resolved. In json output attributes are + object fields (groups become nested objects); in console output they are + appended as `key=value` pairs, with grouped keys written as `group.key=value`. + See [Attribute output](#attribute-output) for the details worth knowing +- reports a record that could not be delivered as an error from the handler's + `Handle` method. See [When delivery fails](#when-delivery-fails) for how to + receive it ## Planned Features -- supports delivering logs via tcp RELP (e.g. to remote rsyslog using imrelp) +- supports delivering logs via tcp RELP (e.g. to remote rsyslog using imrelp) ## Installation @@ -49,9 +47,9 @@ go get sneak.berlin/go/simplelog ## Usage -Below is an example of how to use SimpleLog in a Go application. This -example is provided in the form of a `main.go` file, which demonstrates -logging at various levels using structured logging syntax. +Below is an example of how to use SimpleLog in a Go application. This example is +provided in the form of a `main.go` file, which demonstrates logging at various +levels using structured logging syntax. ```go package main @@ -73,63 +71,58 @@ func main() { ## Attribute output Attributes reach every handler: the ones passed to the log call, the ones -accumulated with `WithAttrs`, and the ones qualified by the groups open at -the time they were attached. `slog.Group` values nest, and -`slog.LogValuer` values are resolved to the value they stand for. A few -behaviours are worth knowing before you rely on them. +accumulated with `WithAttrs`, and the ones qualified by the groups open at the +time they were attached. `slog.Group` values nest, and `slog.LogValuer` values +are resolved to the value they stand for. A few behaviours are worth knowing +before you rely on them. -**Your values are never modified.** Whatever you log is read and rendered, -never written to. A map or a slice you pass to `slog.Any` comes back from -the logger exactly as you handed it over, even when a group later uses the -same key. +**Your values are never modified.** Whatever you log is read and rendered, never +written to. A map or a slice you pass to `slog.Any` comes back from the logger +exactly as you handed it over, even when a group later uses the same key. -**Durations are nanoseconds in json, and readable on the console.** The -json and webhook payloads emit a `slog.Duration` as a number of -nanoseconds, matching `slog.NewJSONHandler`, so a consumer can compare and -aggregate the field without parsing it. The console line emits the same -duration as `3s`, matching `slog.NewTextHandler`, because a person reads -it. +**Durations are nanoseconds in json, and readable on the console.** The json and +webhook payloads emit a `slog.Duration` as a number of nanoseconds, matching +`slog.NewJSONHandler`, so a consumer can compare and aggregate the field without +parsing it. The console line emits the same duration as `3s`, matching +`slog.NewTextHandler`, because a person reads it. -**The json payload is an object, with the consequences an object has.** -The record's own fields are named `Time`, `Level`, `Message` and `PC`, and -they own those names: an attribute keyed after one of them is dropped from -the json and webhook output. A key logged more than once keeps its last -value there for the same reason, with one exception: when both are -`slog.Group` values sharing a key, the two groups are merged into one -object holding the members of both, rather than the second replacing the -first. Neither the collision nor the merge applies to the console output, -which is a line of text: every pair appears, in order. If you need a field -called `message`, pick a key that does not collide - the collision is -silent. +**The json payload is an object, with the consequences an object has.** The +record's own fields are named `Time`, `Level`, `Message` and `PC`, and they own +those names: an attribute keyed after one of them is dropped from the json and +webhook output. A key logged more than once keeps its last value there for the +same reason, with one exception: when both are `slog.Group` values sharing a +key, the two groups are merged into one object holding the members of both, +rather than the second replacing the first. Neither the collision nor the merge +applies to the console output, which is a line of text: every pair appears, in +order. If you need a field called `message`, pick a key that does not collide - +the collision is silent. -**Empty things follow the `slog.Handler` contract.** An empty `Attr` is -ignored, an empty group is elided along with its key, a group with an -empty key is inlined into its parent, and `WithGroup("")` returns the -handler unchanged. +**Empty things follow the `slog.Handler` contract.** An empty `Attr` is ignored, +an empty group is elided along with its key, a group with an empty key is +inlined into its parent, and `WithGroup("")` returns the handler unchanged. ## When delivery fails -Every handler returns an error from `Handle` when it could not deliver -the record: +Every handler returns an error from `Handle` when it could not deliver the +record: -- `ConsoleHandler` and `JSONHandler` return the error from their write to - stdout, wrapped, so `errors.Is` still matches the original -- `WebhookHandler` returns an error when the request fails, and also when - the server answers with a status outside 2xx, a redirect included, - since it does not follow redirects. A request that has not finished - after 5 seconds fails with a timeout error, so a webhook server that - never answers holds up a log call for 5 seconds at most -- `MultiplexHandler`, which simplelog installs as the default, passes the - record to every handler it holds even after one of them fails, then - returns all their errors joined with `errors.Join` (nil if none failed) +- `ConsoleHandler` and `JSONHandler` return the error from their write to + stdout, wrapped, so `errors.Is` still matches the original +- `WebhookHandler` returns an error when the request fails, and also when the + server answers with a status outside 2xx, a redirect included, since it does + not follow redirects. A request that has not finished after 5 seconds fails + with a timeout error, so a webhook server that never answers holds up a log + call for 5 seconds at most +- `MultiplexHandler`, which simplelog installs as the default, passes the record + to every handler it holds even after one of them fails, then returns all their + errors joined with `errors.Join` (nil if none failed) -`slog.Info`, `slog.Error` and the other `slog.Logger` methods throw that -error away. That is how `log/slog` works, and simplelog cannot change it. -To find out whether a record was delivered, build a `slog.Record` and pass -it to the handler yourself, for example -`slog.Default().Handler().Handle(ctx, record)`, then check the error it -returns. Console output takes the file and line from the record's `PC`, -which you set with `runtime.Callers` as the `log/slog` documentation +`slog.Info`, `slog.Error` and the other `slog.Logger` methods throw that error +away. That is how `log/slog` works, and simplelog cannot change it. To find out +whether a record was delivered, build a `slog.Record` and pass it to the handler +yourself, for example `slog.Default().Handler().Handle(ctx, record)`, then check +the error it returns. Console output takes the file and line from the record's +`PC`, which you set with `runtime.Callers` as the `log/slog` documentation shows. A record whose `PC` is zero prints `???:0` instead. ## Entrypoints @@ -154,23 +147,23 @@ alpine. We provide: - `script/test` — run the test suite under the race detector in Docker by building only the `test` stage of the `Dockerfile`, without the build cache, so every run tests; the image is tagged `simplelog-test` -- `script/lint` — run golangci-lint in Docker by building only the `lint` - stage of the `Dockerfile`, without the build cache, so every run lints; the - image is tagged `simplelog-lint` +- `script/lint` — run golangci-lint in Docker by building only the `lint` stage + of the `Dockerfile`, without the build cache, so every run lints; the image is + tagged `simplelog-lint` - `script/fmt` — format all files (writes): Go with the goimports that `script/bootstrap` installs, then every `*.md` file with `prettier` -- `script/fmt-check` — check formatting (read-only); fails if `gofmt -l` - reports files, or if `prettier` would change any `*.md` file +- `script/fmt-check` — check formatting (read-only); fails if `gofmt -l` reports + files, or if `prettier` would change any `*.md` file - `script/check` — run all checks: `test`, `lint`, `fmt-check` (our own extension) -- `script/docker` — build the Docker image without the build cache, tagged - via `script/projectname` (byte-identical across repos); it also passes the - output of `git describe` as the `VERSION` build argument, which is ignored - because this `Dockerfile` does not declare it -- `script/cibuild` — what CI runs: `script/bootstrap`, then `script/check`, - then the same image build as `script/docker` (byte-identical across repos) -- `script/precommit` — run by the git pre-commit hook (our own extension); - runs a `go mod tidy` guard, then `script/check` +- `script/docker` — build the Docker image without the build cache, tagged via + `script/projectname` (byte-identical across repos); it also passes the output + of `git describe` as the `VERSION` build argument, which is ignored because + this `Dockerfile` does not declare it +- `script/cibuild` — what CI runs: `script/bootstrap`, then `script/check`, then + the same image build as `script/docker` (byte-identical across repos) +- `script/precommit` — run by the git pre-commit hook (our own extension); runs + a `go mod tidy` guard, then `script/check` - `script/install-precommit` — installs the git pre-commit hook (our own extension); `make hooks` shims to it diff --git a/TODO.md b/TODO.md index 72fb0f4..2baadad 100644 --- a/TODO.md +++ b/TODO.md @@ -1,90 +1,89 @@ # Workflow -* branch (from `main`) -* do the work in Next Step -* move Next Step to the top of Completed Steps -* move the top item of Future Steps into Next Step -* commit (`TODO.md` changes in the same commit as the work) -* merge to `main` if the branch is not protected, otherwise open a PR -* push +- branch (from `main`) +- do the work in Next Step +- move Next Step to the top of Completed Steps +- move the top item of Future Steps into Next Step +- commit (`TODO.md` changes in the same commit as the work) +- merge to `main` if the branch is not protected, otherwise open a PR +- push # Status 1.0+ -Tagged v1.0.0 (2024-06-14) and 1.0.1 (2026-02-08). In post-1.0 -maintenance; the library is referenced by the Go styleguide. +Tagged v1.0.0 (2024-06-14) and 1.0.1 (2026-02-08). In post-1.0 maintenance; the +library is referenced by the Go styleguide. # Next Step -Restructure README.md into the standard sections: Description, Getting -Started, Rationale, Design, TODO, License, Author +Restructure README.md into the standard sections: Description, Getting Started, +Rationale, Design, TODO, License, Author # Completed Steps -* 2026-10-06: `make fmt` and `make fmt-check` also format Markdown, with - `prettier` at the standard settings, pinned through `package.json` and - `yarn.lock`; `script/bootstrap` installs node and yarn for it, and the - existing Markdown was formatted once -* 2026-10-06: re-vendored the standard files from `sneak/prompts` at - commit `dd4027b`: `REPO_POLICIES.md`, the CI workflow, `.gitignore`, - and `.golangci.yml` together with the lint stage's new image, plus - the `.editorconfig` and `.dockerignore` this repo lacked, which - finishes the Makefile and policy-files step. `script/cibuild` now - bootstraps and runs `script/check` before building the image, the - format check runs only on the host, the last `Dockerfile` stage runs - `script/bootstrap`, which installs goimports at a pinned commit -* 2026-10-06: a webhook request now times out after 5 seconds, so a - server that never answers no longer stops every log call; the webhook - handler also reads each answer to the end so its connection is reused -* 2026-10-06: the console handler takes the file and line it prints from - the record's `PC` instead of counting stack frames, so they name the - call site whether the record came through a `slog.Logger` or straight - to `Handle` -* 2026-10-06: the tests run under the race detector, in Docker: - `script/test` builds the `test` stage of the `Dockerfile`, which runs - `go test -race`, and a new final stage makes a plain `docker build` - run both the `lint` and `test` stages -* 2026-10-06: the linter runs only in Docker: `script/lint` builds the - `lint` stage of the `Dockerfile`, every `docker build` in `script/` - runs without the build cache, and `script/bootstrap` no longer - installs golangci-lint -* 2026-10-06: every handler now returns a failed delivery from `Handle` - instead of discarding it: console and JSON return the stdout write - error, the webhook also fails on a non-2xx answer, and the multiplex - delivers to every handler and returns their errors joined -* 2026-08-10: fixed every handler discarding slog attributes: console, - JSON and webhook handlers now emit record attributes, accumulate - WithAttrs without mutating the receiver, and honour WithGroup; - slog.Group values nest and LogValuer values are resolved; console - keys and values holding invalid UTF-8 are quoted -* 2026-08-07: added canonical `.golangci.yml` (v2 schema), pinned the - `Dockerfile` lint stage to golangci-lint v2.12.2 (tag+digest), and - fixed all findings the v1→v2 jump surfaced without changing any - exported signatures or behavior -- 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints, - Makefile shims, README Entrypoints section -* 2026-02-08: fixed JSONHandler deadlock from recursive log.Println, - with regression test; tagged 1.0.1 -* 2024-06-14: 1.0 prep: lint and fmt enforced in Docker build, call - stack depth fix so log locations report correctly, example script, - removed non-building RELP code; tagged v1.0.0 -* 2024-05-22: module path moved to sneak.berlin/go/simplelog -* 2024-05-14: initial library: slog-based console, JSON, webhook, and - RELP handlers, MultiplexHandler, caller file/line info, UTC ISO - timestamps, level-colored output +- 2026-10-06: `make fmt` and `make fmt-check` also format Markdown, with + `prettier` at the standard settings, pinned through `package.json` and + `yarn.lock`; `script/bootstrap` installs node and yarn for it, and the + existing Markdown was formatted once +- 2026-10-06: re-vendored the standard files from `sneak/prompts` at commit + `dd4027b`: `REPO_POLICIES.md`, the CI workflow, `.gitignore`, and + `.golangci.yml` together with the lint stage's new image, plus the + `.editorconfig` and `.dockerignore` this repo lacked, which finishes the + Makefile and policy-files step. `script/cibuild` now bootstraps and runs + `script/check` before building the image, the format check runs only on the + host, the last `Dockerfile` stage runs `script/bootstrap`, which installs + goimports at a pinned commit +- 2026-10-06: a webhook request now times out after 5 seconds, so a server that + never answers no longer stops every log call; the webhook handler also reads + each answer to the end so its connection is reused +- 2026-10-06: the console handler takes the file and line it prints from the + record's `PC` instead of counting stack frames, so they name the call site + whether the record came through a `slog.Logger` or straight to `Handle` +- 2026-10-06: the tests run under the race detector, in Docker: `script/test` + builds the `test` stage of the `Dockerfile`, which runs `go test -race`, and a + new final stage makes a plain `docker build` run both the `lint` and `test` + stages +- 2026-10-06: the linter runs only in Docker: `script/lint` builds the `lint` + stage of the `Dockerfile`, every `docker build` in `script/` runs without the + build cache, and `script/bootstrap` no longer installs golangci-lint +- 2026-10-06: every handler now returns a failed delivery from `Handle` instead + of discarding it: console and JSON return the stdout write error, the webhook + also fails on a non-2xx answer, and the multiplex delivers to every handler + and returns their errors joined +- 2026-08-10: fixed every handler discarding slog attributes: console, JSON and + webhook handlers now emit record attributes, accumulate WithAttrs without + mutating the receiver, and honour WithGroup; slog.Group values nest and + LogValuer values are resolved; console keys and values holding invalid UTF-8 + are quoted +- 2026-08-07: added canonical `.golangci.yml` (v2 schema), pinned the + `Dockerfile` lint stage to golangci-lint v2.12.2 (tag+digest), and fixed all + findings the v1→v2 jump surfaced without changing any exported signatures or + behavior + +* 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints, Makefile + shims, README Entrypoints section + +- 2026-02-08: fixed JSONHandler deadlock from recursive log.Println, with + regression test; tagged 1.0.1 +- 2024-06-14: 1.0 prep: lint and fmt enforced in Docker build, call stack depth + fix so log locations report correctly, example script, removed non-building + RELP code; tagged v1.0.0 +- 2024-05-22: module path moved to sneak.berlin/go/simplelog +- 2024-05-14: initial library: slog-based console, JSON, webhook, and RELP + handlers, MultiplexHandler, caller file/line info, UTC ISO timestamps, + level-colored output # Future Steps -* Delete the old plain TODO file once this TODO.md lands -* Add .aider.* to .gitignore and remove the stray aider artifacts from - the working tree -* Pick one tag scheme before the next release (v1.0.0 vs 1.0.1 are - inconsistent) -* Tag v1.0.2, with the leading v, once the attribute fix lands, so - consuming repos can move off pseudo-version pins in one step -* Fix RELP output to cache (from old TODO) -* Re-add RELP delivery over TCP to remote rsyslog imrelp; removed - 2024-06-14 because it did not build (README planned feature) -* Add regex filtering for webhook logs (from old TODO) -* Better console output format (from old TODO) +- Delete the old plain TODO file once this TODO.md lands +- Add .aider.\* to .gitignore and remove the stray aider artifacts from the + working tree +- Pick one tag scheme before the next release (v1.0.0 vs 1.0.1 are inconsistent) +- Tag v1.0.2, with the leading v, once the attribute fix lands, so consuming + repos can move off pseudo-version pins in one step +- Fix RELP output to cache (from old TODO) +- Re-add RELP delivery over TCP to remote rsyslog imrelp; removed 2024-06-14 + because it did not build (README planned feature) +- Add regex filtering for webhook logs (from old TODO) +- Better console output format (from old TODO)