Skip to content

tp: implement perfetto_metadata clock/machine overrides#6188

Closed
LalitMaganti wants to merge 4 commits into
dev/lalitm/main.tp-implement-perfetto_metadata-clockmachine-overridesfrom
dev/lalitm/tp-implement-perfetto_metadata-clockmachine-overrides
Closed

tp: implement perfetto_metadata clock/machine overrides#6188
LalitMaganti wants to merge 4 commits into
dev/lalitm/main.tp-implement-perfetto_metadata-clockmachine-overridesfrom
dev/lalitm/tp-implement-perfetto_metadata-clockmachine-overrides

Conversation

@LalitMaganti

Copy link
Copy Markdown
Member

Add the perfetto_metadata sidecar: a JSON file inside a zip/tar
archive which overrides clock and machine handling for the other files
in the archive, together with a comprehensive diff test suite covering
every green and error path of the v1 schema.

The schema (v1):

  • detection via the top-level perfetto_metadata key; own trace type,
    processed before all other archive members (including proto)
  • top-level trace_time_clock (builtin clock names)
  • per-file entries matched by exact path with two section objects:
    machine ({id}) and clocks (native, offset_ns XOR anchor)
  • anchors are expressed as 'a ts as written in the file' (file-native
    units, e.g. us for JSON) paired with a value on a named builtin
    clock or a utc wall time; the source clock is always implicit
  • strict validation: hard errors for unknown fields, unknown clock
    names, unmatched/duplicated paths, mutually exclusive fields,
    standalone (non-archive) usage and multiple config files

The implementation:

  • kPerfettoMetadataTraceType is parsed before everything else in the
    archive. The file does NOT fork a per-trace context: it produces no
    events, and forking would create the per-machine state early and
    steal 'primary' status from the real traces, isolating their clock
    snapshots in private syncs.
  • PerfettoMetadataReader strictly parses/validates the config into the
    new global TraceMetadataState. trace_time_clock is applied directly
    on TraceTimeState with a sentinel owner id so no later trace file
    can override it.
  • ForwardingTraceParser::Init consults the entry matching the file's
    archive path: machine.id feeds ForkContextForTrace, clocks.native
    remaps the format's declared clock (new ClockTracker remap consulted
    in ToTraceTime), clocks.offset_ns becomes a per-file post-conversion
    shift and clocks.anchor is injected as a snapshot into the machine's
    shared ClockSynchronizer so it composes with snapshots from other
    traces. For proto traces a clocks override also routes packets
    without an explicit clock id through the trace default clock.
  • Overrides only apply to files which are single-clock/single-machine
    in practice; proto traces are checked optimistically and fail lazily
    (a ClockSnapshot or a packet with machine_id != 0 proves multi-ness).
    Entries whose path matches no archive member fail at end of file.
  • Fix SystraceTraceParser to write the clock-converted timestamp back
    into SystraceLine: previously the conversion was only used as the
    sorting key while tables were populated from the raw MONOTONIC
    value. This was masked by identity conversions and only diverged
    when a proto trace's snapshot actually linked MONOTONIC into the
    clock graph.

Created using spr 1.3.7
@LalitMaganti LalitMaganti requested a review from a team as a code owner June 10, 2026 12:20
@LalitMaganti LalitMaganti marked this pull request as draft June 10, 2026 12:21
@github-actions

github-actions Bot commented Jun 10, 2026

Copy link
Copy Markdown

Created using spr 1.3.7
Created using spr 1.3.7
Created using spr 1.3.7
@LalitMaganti LalitMaganti deleted the dev/lalitm/tp-implement-perfetto_metadata-clockmachine-overrides branch June 30, 2026 22:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant