fix(trace): emit kernel TIDs and thread-name metadata

[olantwin]

Summary

ui.perfetto.dev was rendering all trace spans on a single thread track
even when the underlying JSON had distinct `tid` values per worker.

Root cause: `chrome_trace.hpp` used `std::hashstd::thread::id` for
the tid, which produces values around 10¹⁸. Perfetto UI parses the
Chrome trace JSON in JavaScript, where the safe-integer limit is
2⁵³ ≈ 9 × 10¹⁵. Our tids were ~1000× past that — JS rounded them
inexactly and Perfetto bucketed the distinct threads into one track.

Fix:

• Use `syscall(SYS_gettid)` for the tid. Kernel TIDs are 32-bit, well
  within JavaScript's safe range, and match what `perf`, `ps`, and
  `top` show, so cross-referencing with sampling profilers is now
  trivial.
• Add a `set_thread_name(name)` helper that emits a `ph:"M"` metadata
  event (Chrome Trace "thread_name"), exposed via an
  `AEGIR_TRACE_THREAD_NAME` macro.
• Label the G4 master and workers from `geant4_module.cpp`: tracks now
  appear in Perfetto as `g4_master` and `g4_worker_0..N` instead of
  bare integers.

Linux-only path (the project is Linux-only). No behavioural change
when `AEGIR_ENABLE_TRACE` is OFF.

Test plan

• `pixi run -e bench build` with `-DAEGIR_ENABLE_TRACE=ON`
  succeeds.
• 4-worker run on `gun_mt_noop` (8 events, concurrency=4) produces
  5 distinct small kernel TIDs (260528, 260529, 260534, 260536,
  260541 in the local smoke run) instead of five ~10¹⁸ hash values.
• Five `thread_name` metadata events appear: `g4_master`,
  `g4_worker_0`, `g4_worker_1`, `g4_worker_2`, `g4_worker_3`.
• On the VM: open a new MT trace in ui.perfetto.dev and confirm
  five threads with the expected labels (follow-up to existing
  investigation; not a CI gate).

Summary by CodeRabbit

• New Features
  • Enhanced thread identification in trace output using kernel thread identifiers for improved clarity
  • Added support for naming threads in trace output
  • Labeled simulation threads for better traceability in trace data

[coderabbitai]

📝 Walkthrough

Walkthrough

Chrome Trace thread identification now uses kernel thread IDs (via syscall(SYS_gettid)) instead of hashed std::thread::id values. A new thread-naming API (set_thread_name) writes metadata events to the trace output, with a corresponding macro that disables safely when tracing is off. Geant4 simulation threads are now labeled "g4_master" and "g4_worker_<id>" in trace output.

Changes

Thread identification and naming in trace output

Layer / File(s)	Summary
Kernel thread ID and headers src/chrome_trace.hpp	Added syscall headers (<sys/syscall.h>, <unistd.h>) and <string> support; updated thread_id() to emit kernel TID via SYS_gettid with precision documentation comments.
Thread naming API and macro src/chrome_trace.hpp	Introduced set_thread_name(std::string const& name) function that writes ph="M" thread-name metadata events to the trace JSON file, and AEGIR_TRACE_THREAD_NAME(name) macro that becomes a no-op when tracing is disabled.
Geant4 master and worker thread labeling src/geant4_module.cpp	Applied new thread-naming API to label the Geant4 master thread "g4_master" in init_master and each worker thread "g4_worker_<id>" in init_worker.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main changes: switching from hashed thread IDs to kernel TIDs and adding thread-name metadata support for better trace visualization.
Description check	✅ Passed	The description includes a comprehensive summary, root cause analysis, detailed fix explanation, scope clarification, and completed test plan, though it does not explicitly address the conventional commits checklist items.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/trace-thread-ids

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[olantwin]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/chrome_trace.hpp`:
- Around line 103-112: The set_thread_name function writes the raw name into
JSON; add a JSON-escaping helper (e.g., escape_json_string or json_escape) and
call it from set_thread_name so that quotes, backslashes, and control characters
are escaped (use \\\", \\\\, \\n, \\r, \\t, and \\uXXXX for others) before
passing to std::fprintf; update references inside set_thread_name (alongside
file_handle(), write_mutex(), first_event(), thread_id()) to use the escaped
string to ensure well-formed output.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 506a73c5-7077-431a-bee7-efb9c0969a70

📥 Commits

Reviewing files that changed from the base of the PR and between b3c4bbe and a432d4e.

📒 Files selected for processing (2)

• src/chrome_trace.hpp
• src/geant4_module.cpp