Deterministic golden fixtures and a trace-format gate - #47
Merged
Conversation
Jo5ta
force-pushed
the
feat/golden-version-gate
branch
9 times, most recently
from
July 28, 2026 13:39
05e645e to
790befb
Compare
Make golden trace-file generation byte-deterministic and add a CI gate that grows the fixture corpus only on real format changes. - frozen_info.c freezes timestamp/pid/tid (and the span-id salt derived from them); linked into the golden writer so a generated trace is byte-identical run to run. The core library is unchanged. - One C++ writer (writer.cpp) exercises every tracepoint kind -- printf, dump, dynamic, spans, and fmt -- into a single GOLDEN fixture. The same source, compiled as a relocatable object and a shared object, provides the ELF metadata fixtures for the 'clltk meta' test (both byte orders; the old source-less 1.3.0 blobs are kept only as a backward-compat anchor). Built by cmake targets behind the CLLTK_GOLDEN option and the golden preset; generate.sh runs it in a per-arch Fedora container. - step_golden.sh regenerates the fixture at HEAD for both byte orders and byte-compares it against the newest committed golden, masking only the library-version field (normalize.py, endianness-agnostic). A difference means the format changed; regenerate_golden.sh writes the new version's fixture and refuses to overwrite an existing same-version baseline. Wired as a CI job (qemu for le-aarch64 and be-s390x) and into run_all.sh. - Fixtures are laid out one folder per library version, <version>/<arch>.<ext>; old big-endian traces backfilled (era-adaptive) so every trace folder has both byte orders. - Deterministic 1.7.7 baselines for both byte orders; test_golden.py decodes every fixture with both decoders as the correctness oracle. Signed-off-by: Jo5ta <jo5ta@mail.de>
Jo5ta
force-pushed
the
feat/golden-version-gate
branch
from
July 28, 2026 13:51
790befb to
336bfff
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Makes golden trace-file generation byte-deterministic and adds a CI gate
that grows the fixture corpus only when the trace format actually changes.
Why
Golden fixtures let us test the decoders against known trace files, but until
now a fresh generation was non-deterministic (timestamps, pid, tid, span ids
vary per run), so nothing could tell "did the format change?" from "this is
just a new run". The result was a manual, easy-to-forget policy.
How
frozen_info.cdefines the three abstraction symbols the library uses tostamp entries (
info_get_timestamp_ns/process_id/thread_id) with fixedconstants. Linked ahead of the tracing static archive in the golden writer,
it satisfies those references so the archive's
info.ois never pulled —freezing timestamp, pid, tid, and (through the span-id salt derived from
them) span ids. A generated trace is then byte-identical run to run. The
core library is unchanged.
writer.cpp) exercises every tracepoint kind — printf,dump, dynamic (
CLLTK_DYN_TRACEPOINT), spans, and fmt — into a singleGOLDENfixture. It's C++ because fmt is C++20-only; the other kinds compileidentically from C and the on-disk format is language-independent, so one
writer covers the whole decoder surface. Built by the
golden-generatecmaketarget behind the
CLLTK_GOLDENoption and thegoldenpreset;generate.shruns it in a per-arch Fedora container.scripts/ci-cd/step_golden.sh) regenerates the fixture at HEADfor both byte orders and byte-compares it against the newest committed
golden, masking only the library-version field and its header crc
(
normalize.py, endianness-agnostic). Identical → the corpus already coversthis format. Different → the format changed;
regenerate_golden.shwrites anew version-named fixture (and refuses to overwrite an existing same-version
baseline, so old-format coverage can't be silently dropped). Runs as its own
CI job (qemu for
le-aarch64andbe-s390x) and inrun_all.sh(
--skip-golden, auto-skipped when no container engine is present).committed
golden-1.3.0-be-s390x.{o,so}blobs (for theclltk metaELF test)had no source. They're now regenerated from
writer.cppcompiled as arelocatable object + shared object (
generate.sh --elf,golden-1.7.7-be-s390x.{o,so}).A separate cmake target keeps the format gate from building them, so an ELF
build issue can't masquerade as a trace-format change.
test_golden.pydecodes every fixture with both decoders as the correctness oracle.
Testing
(
le-aarch64native,be-s390xunder qemu).decoders; the comprehensive fixture covers every tracepoint kind;
clltk metaextracts the metadata from the committed s390x ELF objects cross-endian.
changes are masked; a real payload change is caught.
-x) clean; CMake presets / CI YAML validated.