Tint slog Handler Migration Notes For Data Services

lmittmann/tint had a small but useful activity burst this week: three commits, seven files changed, 139 insertions, and 33 deletions. For Go data services that use slog in workers, loaders, and admin CLIs, the main point is naming clarity around the text handler plus a fix for []byte log values.

The visible API change is that tint renamed NewHandler to NewTextHandler. This is a refactor, but it touches the public surface. The old constructor remains as NewHandler, now marked deprecated and wired through to NewTextHandler.

That matters because slog.Handler is an interface, and the old name did not say much about the concrete output shape. NewTextHandler is more explicit. It tells readers that this handler writes tinted text output, not JSON and not a transport specific format. In data platform code, that distinction is not cosmetic. Batch jobs often emit logs for humans during local runs, while production workers may send JSON to a collector.

The top changed files show the intent. handler.go gets the new constructor and the compatibility wrapper. README.md updates the examples so new users copy the new name. handler_test.go updates examples and tests, which is the part that keeps documentation and behavior from drifting apart.

For existing code, this is not an urgent break. tint.NewHandler(w, opts) still works. The more useful action is to move new code and touched files to tint.NewTextHandler(w, opts) so internal examples match the upstream API before the old name becomes a larger migration.

The other behavior change is smaller but closer to day to day debugging. tint fixed formatting for []byte values. The staged summary does not include the full patch, so the safe read is narrow: []byte values logged through the handler had formatting that was wrong enough to warrant a fix and test coverage.

That is still relevant for data engineering. Byte slices show up in message keys, compact payload samples, encoded offsets, checksums, and protocol fields. In a pipeline failure, the difference between a readable byte value and a confusing rendered value can decide whether the first response is a quick replay or a longer trace session.

The useful guardrail is to avoid treating tinted text logs as canonical data. Use them for operator reading and local diagnosis. Keep machine parsing on structured sinks where bytes have a stable encoding policy. This tint fix improves the human path, but it does not replace a deliberate decision about how binary fields should appear in logs across services.

The NewTextHandler rename is not only a symbol change. The examples in README.md were updated across common setup paths: default logger setup, trace level examples, time removal, error coloring, terminal detection, and Windows color support.

That broad example update is worth calling out because logging code is often pasted once and left alone for years. A data service might have one logger setup in a shared package, while one off backfill tools carry their own setup in small main packages. If those snippets drift, teams end up with mixed conventions that make review harder than it needs to be.

The practical migration is simple. When touching Go services that import tint, search for NewHandler. Replace it with NewTextHandler unless the code intentionally keeps the deprecated form for compatibility tests. Then run normal logging tests or at least a small command path that emits a byte slice and an error value. This is low risk, but it is still logging, and logging regressions usually appear during incidents rather than during happy path tests.

The remaining commit removed Go Report Card. The changed file list includes .github/workflows/go.yml, so this looks like maintenance around project checks rather than runtime behavior.

For operators, the direct impact is close to zero. It does not change the handler API, formatting behavior, or dependency model based on the staged data. The value is in reducing stale or noisy quality signals. Small libraries benefit from checks that reflect actual release risk: tests, formatting, static analysis where it catches real defects, and examples that compile.

This is also a reminder to treat badges and scorecards as weak signals when selecting libraries for production services. A small Go dependency with clear tests around output behavior may be easier to reason about than a project with many external status badges and little coverage for the exact formatting cases users hit.

  1. Track whether NewHandler stays as a deprecated wrapper through the next tagged release. The staged patch keeps source compatibility, but deprecation is still a migration signal.

  2. Add one local test if your service logs binary fields through tint. The upstream []byte fix is useful, but each pipeline has its own expectations for payload samples and identifiers.

  3. Keep text logs in their lane. tint is good for readable slog output, especially in CLIs and local worker runs. For collector ingestion, keep using structured output with an explicit policy for byte values.