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

> Master Meetily debugging with perf_debug! and perf_trace! macros. Learn how to use these zero-cost logging tools effectively in your development workflow for performance insights.

- Repository: [Zackriya Solutions/meetily](https://github.com/Zackriya-Solutions/meetily)
- Tags: how-to-guide
- Published: 2026-07-26

---

**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`](https://github.com/Zackriya-Solutions/meetily/blob/main/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:

```rust
// 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:

```rust
// 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:

```rust
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`](https://github.com/Zackriya-Solutions/meetily/blob/main/frontend/src-tauri/src/audio/pipeline.rs), `perf_debug!` tracks chunk processing without impacting the real-time audio stream:

```rust
// 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`](https://github.com/Zackriya-Solutions/meetily/blob/main/frontend/src-tauri/src/whisper_engine/whisper_engine.rs), `perf_trace!` provides per-segment visibility for transcription diagnostics:

```rust
// 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`](https://github.com/Zackriya-Solutions/meetily/blob/main/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`](https://github.com/Zackriya-Solutions/meetily/blob/main/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.