Repository navigation
Releases
v0.9.0
v0.8.0
A smaller Options before 1.0: the four deprecated fields are gone. Breaking: code that sets any of them no longer compiles; the migration for each is below.
Modules released: core v0.8.0 only. The submodules are unchanged and work with it.
Removed
- The deprecated
Optionsfields. Each removal is a compile error, not a silent change:PassLevelandBufferLevel: usePassLevelerandBufferLeveler. The old fields ignoredslog.LevelInfo, their zero value, and used the defaults (Warn and Debug) instead. If you set either toslog.LevelInfo, delete the line to keep your behaviour; writingPassLeveler: slog.LevelInfowould now take effect.IgnoreRequestTraceIDsandDisableFlushMarker: both are the default since v0.7.0. Delete the line. Each overrode its partner, so also deleteTrustRequestTraceIDsif you setIgnoreRequestTraceIDs, andEnableFlushMarkerif you setDisableFlushMarker.
notifier/natsnotifier/v0.4.1
Modules released: grpcflightrec/v0.4.1 and notifier/natsnotifier/v0.4.1, each requiring core v0.7.0. The core module is unchanged at v0.8.0.
Security
natsnotifierrequiresgolang.org/x/cryptov0.59.0, which includes the fix for GO-2026-5932. Previously the minimum was v0.58.0.grpcflightrecrequiresgolang.org/x/netv0.62.0, which fixes GO-2026-6866 and GO-2026-6860 in thehtmlpackage. Previously the minimum was v0.60.0.
grpcflightrec/v0.4.1
Modules released: grpcflightrec/v0.4.1 and notifier/natsnotifier/v0.4.1, each requiring core v0.7.0. The core module is unchanged at v0.8.0.
Security
natsnotifierrequiresgolang.org/x/cryptov0.59.0, which includes the fix for GO-2026-5932. Previously the minimum was v0.58.0.grpcflightrecrequiresgolang.org/x/netv0.62.0, which fixes GO-2026-6866 and GO-2026-6860 in thehtmlpackage. Previously the minimum was v0.60.0.
v0.7.0
Safe defaults: a client can no longer choose trace IDs or learn from responses that an error was logged, and a notifier no longer starts unauthenticated by accident. Breaking: internal services that rely on forwarded request IDs or flush markers must opt in, and StartNotifier needs a signing option; see the migration note below.
Modules released: core v0.7.0, grpcflightrec/v0.4.0, notifier/redisnotifier/v0.4.0 and notifier/natsnotifier/v0.4.0 (each requiring core v0.7.0). otelflightrec is unchanged at v0.3.1.
Changed
-
Safe defaults. Each was an opt-out before; services that only your own services call opt back in:
- Request headers and gRPC metadata (
traceparent,X-Trace-Id,X-Request-Id) no longer choose trace IDs. SetOptions.TrustRequestTraceIDs. - Triggered scopes no longer mark responses with
Flightrec-Flush(gRPC: a trailer). SetOptions.EnableFlushMarker. StartNotifierpanics withoutWithSigningKey. PassWithoutSigning()for a channel that only trusted processes can publish on.
Migration: add
TrustRequestTraceIDs: true, EnableFlushMarker: trueto theOptionsof internal services that use cross-service flush or forward request IDs, and passWithSigningKey(key)(the same key in every service) orWithoutSigning()toStartNotifier. Without the opt-ins, a customGRPCMetadataExtractoris not called, and the notifier and callers match requests only by an OpenTelemetry trace ID, never by a forwardedX-Request-Id. Without a signing option,StartNotifierpanics at startup. Public-facing services that setIgnoreRequestTraceIDsandDisableFlushMarkerneed no change. - Request headers and gRPC metadata (
Added
Options.TrustRequestTraceIDs,Options.EnableFlushMarkerand theWithoutSigningnotifier option.
Deprecated
Options.IgnoreRequestTraceIDsandOptions.DisableFlushMarker: they are the default now. They still override the new options.
Security
- CI runs OpenSSF Scorecard and every fuzz target on each change, and CodeQL scans Go and the workflows.
notifier/redisnotifier/v0.4.0
Requires core v0.7.0, which turns request trust, flush markers and unsigned notifiers into opt-ins. See its migration note.
notifier/natsnotifier/v0.4.0
Requires core v0.7.0, which turns request trust, flush markers and unsigned notifiers into opt-ins. See its migration note.
grpcflightrec/v0.4.0
Requires core v0.7.0, which turns request trust, flush markers and unsigned notifiers into opt-ins. See its migration note.
v0.6.0
Security hardening from a review of the whole package, and a cleaner repository layout. The layout change moves no exported identifier: import paths, the API and every log line are unchanged.
Modules released: core v0.6.0, otelflightrec/v0.3.1 and grpcflightrec/v0.3.2 (READMEs for pkg.go.dev only). notifier/redisnotifier and notifier/natsnotifier are unchanged at v0.3.0.
Changed
- With OpenTelemetry middleware inside
HTTPMiddleware, a scope keyed by a request header (traceparent,X-Trace-Id,X-Request-Id) takes the server span's trace ID when the span starts, as a generated ID already did, so logs and spans agree in either middleware order. The header ID stays an alias: notifier notices for it still reach the scope (and its child scopes), failures are announced under both IDs, the per-trace cap of retained scopes applies to both, and flushed records and the summary line carry it asflightrec.request_id. The adoption is journaled, so recovered records carry the same IDs (#96). - Repository layout: the root package is organised by concern in 10 files, with machinery in
internal/(traceid,snapshot,notify,journal); community files moved to.github/,RELEASING.mdtodocs/, and the demo toexamples/demo.
Security
StartJournalrefuses a lock file (path.lock) that is not a private regular file of the current user with one link, instead of locking a file another user planted.- New guide, Running flightrec safely: settings for public-facing services, notifier authentication and channel permissions, sensitive data, where to put the journal, and resource limits.
- With
RetainorStartJournal,slog.Anyvalues were copied as JSON only, soslog.TextHandlerand other handlers that print values withStringorMarshalTextshowed the raw value: a type that redacts itself inString(a password type printing***) leaked once either feature was on. Copies now keep both renderings, made as slog's handlers make them (a nil pointer prints<nil>instead of panicking). Journals written by this version store both; an earlier version cannot recover records withslog.Anyvalues from them, so recover before rolling back. - Copied
slog.Anyvalues are capped at 64 KB each, and copying forRetainstops once a scope's copies exceedMaxRetained, so large values cannot make retention allocate far beyond its limits. WithSigningKeyauthenticates notifier messages with HMAC-SHA256 and a timestamp; unsigned, forged and stale messages are rejected. Without it, anyone who can publish on the notifier channel can trigger flushes in every service.
v0.5.0
Fixes from the first end-to-end test of the released modules: three services under load, with Redis, NATS, OpenTelemetry export and kill -9 (see docs/e2e-report.md). Three changes alter behaviour, listed under Changed.
Modules released: core v0.5.0, otelflightrec/v0.3.0 and grpcflightrec/v0.3.1 (documentation only). notifier/redisnotifier and notifier/natsnotifier are unchanged at v0.3.0.
Also new: an animated walkthrough and architecture diagrams in the README, and benchmarks of otelflightrec against a real OTLP export path (#30).
Changed
- A local failure is announced to the notifier even when the trace ID was generated by flightrec. Services forward generated IDs to the services they call (in
X-Request-Id, for example), so those services know them; before, the failure of a request that entered without a trace header never reached them. Services whose IDs are mostly generated (edge services withIgnoreRequestTraceIDs) now publish a notice for each local failure; the publish rate limit still applies (#83). HTTPMiddlewareand the gRPC interceptors take the trace ID from the trace already in the request context (an OpenTelemetry span, as reported byOptions.TraceExtractoror the registered bridge) before request headers. Before, a header such as theX-Request-Ida proxy adds overrode the span, so logs carried a different trace ID than the spans and cross-service flush matched the wrong trace. A customGRPCMetadataExtractoris no longer consulted when the context carries a trace, andOptions.TraceExtractornow ranks above headers instead of below them. Put OpenTelemetry middleware outside flightrec's for the two to agree (#84).traceparentvalues are accepted only when valid as the W3C Trace Context specification defines them: lowercase hex, non-zero trace and parent IDs, no versionff, and exactly four fields for version00. Other values are skipped like an invalidX-Request-Id(#84).otelflightrec.SpanProcessorno longer triggers on an error status or exception event of a client or producer span that records the remote's answer as a client error:rpc.grpc.status_codeother than the server-fault codes, orhttp.response.status_codebelow 500. Instrumentation such as otelgrpc marks client spans as errors for answers likeNotFound, so a 404 flushed every service in the trace, against the documented gRPC rules. Outbound errors without such an answer (connection failures, timeouts, database and third-party calls) still trigger (#85).
Fixed
- A failed request whose buffered records were all dropped (evicted by
MaxTotal, or a single record larger thanMaxPerScope) writes onebuffered records droppedline withflightrec.truncatedandflightrec.dropped_records. Before, it wrote nothing, and the loss showed only inStats(#86). - A record too large for a journal entry (about 64 KB encoded) now leaves a marker, so its request is recovered marked
flightrec.truncated, withflightrec.dropped_recordson the summary line. Before, the record was left out silently (#87).