Introduce `tracing` to boa

[jedel1043]

We're slowly approaching an eventual 1.0 release, and the scope of the project keeps getting bigger with each new feature and optimisation. However, this means that debugging using only dbg! and a debugger will get harder as the time passes.

With that said, I think it's time to add something like tracing to the repo, possibly using compile time filters to disable the tracing in release mode.

[jedel1043]

Could also be useful to use profiling instead, which is profiler-framework-agnostic
https://crates.io/crates/profiling

[Jayant-kernel]

Hi! @jedel1043
I'd love to take this on as part of GSoC 2026.

I read through both the original proposal and @jedel1043's follow-up about the profiling crate. I think there's a really nice path here, so let me lay out how I'd approach this:

Step 1 — Pick the right abstraction
→The profiling crate seems like the sweet spot over raw tracing. It's zero-cost when no backend is enabled, and it lets users choose their profiler (tracy, puffin, tracing, superluminal) via feature flags — no lock-in.
→ But I'd also like to hear if there's a preference here, since tracing gives richer structured logging (spans with fields, events, subscribers) while profiling is more focused on pure instrumentation.

Step 2 — Instrument the hot paths first
→ Start with the VM execution loop — bytecode dispatch, opcode handling
→ Then GC — trace/sweep timing, allocation counts, heap size
→ Then the parser and compiler passes
→ Each instrumented with profiling::scope!() or #[profiling::function] so it's lightweight and opt-in

Step 3 — Wire up feature flags
→ Add cargo features like profile-with-tracy, profile-with-tracing, etc. that pass through to the profiling crate
→ Use compile-time filters so release builds have zero overhead by default (as the original issue mentioned)

Step 4 — Make it actually useful
→ Add a section to the contributor docs: "How to profile Boa" with a concrete tracy/puffin walkthrough
→ Maybe a --trace flag on boa_cli that enables a default subscriber for quick local debugging
I'd like to start with a small proof-of-concept PR — maybe just instrumenting the VM dispatch loop with profiling and a tracy feature flag — so we can discuss the ergonomics before going wider. Would that be a reasonable first step?

Also — is there any concern about adding profiling as a dependency to the core engine crates, or would you prefer it stays in boa_cli / behind an optional feature only?

[jedel1043]

There are no preferences on the framework itself, but I don't think we've explored all options. IIRC we've only looked into profiling and tracing, so I would suggest first doing a deep dive on what our options are and comparing pros and cons before committing to any PR.

[Jayant-kernel]

Got it — research first, makes sense.
I'll put together a comparison of the available options (tracing, profiling, tracy-client directly, log + custom layer, etc.) with pros/cons for Boa's use case — things like compile-time overhead, runtime cost, backend flexibility, and how well each plays with feature flags.

I'll also look at how other Rust engines/runtimes (like Deno, swc, wasm-tools) handle observability to see if there's anything we can learn from.
I'll share it as a gist or discussion post — what would you prefer?

[jedel1043]

I'd suggest reserving a time for it as part of your GSoC proposal, since if you get selected, the initial research is a non-trivial amount of research work.

[Jayant-kernel]

Makes sense — I'll bake the research phase into my GSoC proposal timeline.