Meetily Debugging and Logging Macros: How to Use `perf_debug!` and `perf_trace!`

The perf_debug! and perf_trace! macros provide zero-cost, conditional logging for performance-critical paths in Meetily, compiling to no-ops in release builds while outputting debug and trace level logs respectively during development.

Meetily’s Rust core implements specialized logging macros designed specifically for hot-path instrumentation without runtime overhead. These macros leverage conditional compilation to ensure diagnostic code disappears completely in production binaries while remaining available for detailed performance analysis during development. Understanding when to apply each macro helps maintain the application's real-time audio processing performance while enabling deep debugging capabilities.

Macro Definitions and Compilation Behavior

Both macros are defined in frontend/src-tauri/src/lib.rs using #[cfg(debug_assertions)] gates to control their expansion. The implementation wraps the standard log crate macros but conditionally compiles them away in release builds.

perf_debug! expands to log::debug! in debug builds and an empty statement in release:

// frontend/src-tauri/src/lib.rs
#[cfg(debug_assertions)]
macro_rules! perf_debug {
    ($($arg:tt)*) => {
        log::debug!($($arg)*)
    };
}

#[cfg(not(debug_assertions))]
macro_rules! perf_debug {
    ($($arg:tt)*) => {};
}

perf_trace! operates identically but targets the trace log level:

// frontend/src-tauri/src/lib.rs
#[cfg(debug_assertions)]
macro_rules! perf_trace {
    ($($arg:tt)*) => {
        log::trace!($($arg)*)
    };
}

#[cfg(not(debug_assertions))]
macro_rules! perf_trace {
    ($($arg:tt)*) => {};
}

The macros are re-exported for module-wide access via:

pub(crate) use perf_debug;
pub(crate) use perf_trace;

When to Use Each Macro

Choose between these macros based on the granularity of data you need and the frequency of the logging event.

Use perf_debug! for High-Level Hot Path Events

Apply perf_debug! in performance-sensitive loops where occasional insight is valuable but per-item granularity would generate excessive noise. This includes audio mixing routines, voice activity detection (VAD) phases, and transcription chunk handling.

Key characteristics:

• Log level: debug
• Cost in release: Zero (complete elimination)
• Best for: Chunk counts, buffer sizes, filtering decisions, and pipeline state changes

Use perf_trace! for Granular Inspection

Reserve perf_trace! for extremely fine-grained diagnostics where you need per-item or per-millisecond visibility, such as individual segment timestamps or intermediate buffer dumps.

Key characteristics:

• Log level: trace
• Cost in release: Zero (complete elimination)
• Best for: Per-segment transcription timing, exact control-flow decisions, and massive data dumps

Avoid using standard log::debug! or log::trace! directly in hot paths; these incur runtime overhead even in release builds. The conditional compilation in perf_debug! and perf_trace! guarantees zero-cost abstraction for production deployments.

Real-World Usage Examples

Audio Pipeline Debugging

In frontend/src-tauri/src/audio/pipeline.rs, perf_debug! tracks chunk processing without impacting the real-time audio stream:

// Located near line 812
perf_debug!(
    "Pipeline processed {} chunks, current chunk: {} ({} samples)",
    processed_chunks,
    current_chunk_index,
    current_chunk.len()
);

This logs critical pipeline state only during development, ensuring the mixing engine runs at full speed in production.

Whisper Engine Tracing

In frontend/src-tauri/src/whisper_engine/whisper_engine.rs, perf_trace! provides per-segment visibility for transcription diagnostics:

// Located near line 765
perf_trace!(
    "Segment {} ({:.2}s-{:.2}s): '{}'",
    segment_index,
    segment.start_time,
    segment.end_time,
    segment.text
);

The same file uses perf_debug! for filtering repetitive or meaningless text during preprocessing, demonstrating how both macros coexist in the same module for different debugging depths.

Summary

• perf_debug! and perf_trace! are conditional logging macros defined in frontend/src-tauri/src/lib.rs that compile to no-ops in release builds.
• Use ** perf_debug!** for medium-granularity events in hot paths like audio processing and chunk handling.
• Use perf_trace! for ultra-fine-grained data such as per-segment timestamps and intermediate buffers.
• Both macros rely on #[cfg(debug_assertions)] to ensure zero runtime overhead in production binaries.
• Standard log macros should be avoided in performance-critical code paths; these custom wrappers provide the necessary compile-time guarantees.

Frequently Asked Questions

What is the performance impact of these macros in release builds?

There is zero impact. When compiled without debug_assertions (the default for cargo build --release), both macros expand to empty statements ({}). The compiler eliminates them entirely, ensuring no string formatting, no function calls, and no branching overhead reaches production binaries.

Can I use these macros in my own Meetily modules?

Yes. After the re-exports in frontend/src-tauri/src/lib.rs, any module within the src-tauri crate can invoke perf_debug! or perf_trace! directly. They follow the same scoping rules as standard macros and require no additional imports beyond the standard logging setup.

Why not use log::debug! directly with a feature flag?

While feature flags can disable logging crates at compile time, perf_debug! provides finer-grained control at the call site level. This allows you to keep standard log::debug! calls for non-critical initialization code while ensuring absolute zero cost for hot-path instrumentation, without managing complex feature flag permutations across the build graph.

How do I enable these logs when running in debug mode?

Logs appear automatically in debug builds (cargo run or cargo build without the --release flag) when the RUST_LOG environment variable includes debug or trace levels. For example: RUST_LOG=debug cargo run. The macros forward to log::debug! and log::trace!, so they respect the standard env_logger configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}