Developer Tooling & Engine Observability

[kingsmen732]

From understanding what is the current issue:

• print statements and ad-hoc eprintln! calls are the only debugging mechanism today.No structured VM logging
• there is no way to capture a chronological record of bytecode execution, GC events, or scope resolution without modifying source and recompiling.No opt-in tracing
• allocation counts, GC pause durations, bytecode histogram data, and similar statistics are not collected or exposed
• the existing docs do not explain how to use debug builds, enable verbose output, or interpret engine internals

Rough idea on what to be done

• Logging — structured, levelled messages at key execution points
• Tracing — a step-by-step record of what the engine did and when
• Metrics — hard numbers: allocations, GC pauses, bytecode frequency

What we could be actually incorporating to make this work

• Replace ad-hoc debug output with structured, levelled log calls
• Add a DebugVM wrapper around the main interpreter loop that, when enabled via a builder option or environment variable (BOA_TRACE=1), emits per-instruction trace events
• Maybe introduce a lightweight BoaMetrics struct (hidden behind the metrics Cargo feature) that accumulates counters and histograms during execution
  -Mainly start making debugging.md and rustdocs examples to every public metrics type and how to attach the logs

this currently aligns close to #2736 , we can try to start creating a first level implementation so later it will be helpful to start with what parameters needs to be traced and logged.

[rajat552]

@kingsmen732

This looks like a very interesting direction for improving observability in the engine.

From what I understand, introducing tracing could help capture key execution events such as bytecode execution, GC activity, and scope resolution without relying on ad-hoc debug prints. It might also make debugging and performance analysis significantly easier.

I’m interested in exploring this further. A possible first step could be introducing a lightweight tracing layer around the main interpreter loop and emitting events for opcode execution, then gradually expanding it to GC and other subsystems.

Would it make sense to start with a minimal tracing implementation (possibly using the tracing crate) and iterate from there?

[shreyadesai20042009]

I’m interested in contributing to this. I would like to start by improving
the debugging documentation and developer tooling guides.

[Saksham1o]

Hi! This looks like a very useful improvement for the developer experience around Boa.

I'd be interested in working on a first minimal step here, possibly introducing structured logging for key VM events (e.g., opcode execution) using something like the tracing crate, and then expanding from there.

Would that be a good starting direction for this issue?

[Flamki]

Opened a focused first-step PR for this: #4982.is intentionally narrow (CLI + docs) to avoid overlap with broader VM tracing work: it adds BOA_TRACE opt-in tracing control with strict value parsing, tests, and debugging docs updates.