Your team publishes a slog.Handler other teams import. What do you freeze in its contract before tagging?

## What is actually being frozen When a handler ships as a module that a dozen services import, three different audiences depend on it and only one of them is the compiler. - **The importing engineer** depends on the constructor and options. - **The service on call** depends on its failure behaviour: does a stalled sink stall requests? - **The log pipeline** depends on the bytes: field names, nesting, framing. A change that keeps every signature identical can break the second and third audiences completely. That is why the API freeze conversation has to be about behaviour, and why it is a decision a platform or architecture owner can legitimately overrule before the tag exists — and cannot afterwards. ## The commitments worth making explicit **The record's shape.** The key names for time, level and message, the nesting rule for groups, and the framing (one record per line). Downstream, someone has built an alert on a field name. Publishing the shape as part of the contract means a rename is treated as the breaking change it is, rather than a formatting tweak that ships on a Tuesday. Following the conventional `time`/`level`/`msg` keys is worth doing here precisely because it makes your handler interchangeable with the standard ones. **Blocking behaviour.** A handler that writes synchronously under a lock will make a slow sink into request latency. A handler that hands records to a background goroutine will not, but must then define its queue bound and what it drops when full, and must clone anything it retains beyond `Handle`. Whichever you choose, importers build their capacity assumptions on it, so it goes in the contract. "Never blocks" is the more dangerous promise, because it forecloses ever making the path synchronous again. **What `Enabled` promises.** If it is a level comparison against a `slog.LevelVar`, consumers can reason about it and use their own `Logger.Enabled` guard before assembling expensive arguments. If it also samples or rate-limits, that guard becomes a coin flip and debugging a missing log line becomes an escalation to your team. Sampling can still be right — but it is a published property, not an implementation detail. **Write failures.** `slog.Logger`'s logging methods discard the error `Handle` returns, so nothing observes it by default. Decide and publish what your handler does: count failures in a metric, fall back to a second sink, or fail silently. Leaving it undefined means every consumer discovers your answer during an incident. **Concurrency and derivation.** Safe for concurrent use, and derived handlers independent of each other and of the parent, are properties you promise, not features. They are also cheap to guarantee and expensive to retrofit. ## What to leave unspecified, deliberately Every property you document, you own. Field ordering within a record, internal buffer sizing, whether `WithAttrs` pre-formats its attributes, the exact allocation profile, the internal type names — say plainly that these may change. Keep struct fields unexported and prefer a constructor with option functions over an exported options struct, so adding a knob later is additive. Returning the concrete `*Handler` type from the constructor is usually right — it lets you add methods without breaking anyone — but understand that every exported method you add is then permanent, so add none you do not need. ## How the decision gets made and enforced The judgment is not purely technical. Two things push it: - **Who absorbs a change later.** If you can migrate every consumer yourself in an afternoon, you can afford a looser contract; if consumers are twelve teams on their own release schedules, the contract must be tight and additive-only, and a behaviour change needs a new option defaulted to the old behaviour. - **Who is paged.** If your team is not on call for the services that import this, you cannot unilaterally choose a failure mode that turns a sink outage into their latency incident. Enforcement is what makes the commitment real: run the standard contract suite in CI so the structural rules cannot regress, add a test that derives sibling loggers and asserts they do not share attributes, add a test that logs concurrently under the race detector, and add a golden test over the emitted field names so a rename cannot land accidentally. A contract nobody tests is a comment. ## The failure this avoids The bad version of this story is a handler that ships quietly, twelve services adopt it, and eight months later a well-meaning optimisation changes a key name, buffers output, or starts dropping under load. Each of those is invisible in code review, invisible to the type checker, and visible at 3am. Writing the four commitments down before the tag costs an afternoon and is the difference between a shared library and a shared liability.