Crate logwise_proc 

Logwise Procedural Macros

This crate provides procedural macros for the logwise logging library, generating efficient structured logging code at compile time. The macros transform format strings with key-value pairs into optimized logging calls that use the PrivateFormatter system.

Architecture

Each logging macro follows a consistent three-phase pattern:

1. Pre-phase: Creates a LogRecord using *_pre() functions with location metadata
2. Format phase: Uses PrivateFormatter to write structured data via lformat_impl
3. Post-phase: Completes logging using *_post() functions (sync or async variants)

Log Levels and Build Configuration

The macros respect logwise’s opinionated logging levels:

• trace_*: Debug builds only, per-thread activation via Context::currently_tracing()
• debuginternal_*: Debug builds only, requires declare_logging_domain!() at crate root
• info_*: Debug builds only, for supporting downstream crates
• warn_*, error_*, perfwarn_*: Available in all builds

Usage Example

use logwise_proc::*;

// This macro call:
// logwise::info_sync!("User {name} has {count} items", name="alice", count=42);

// Expands to approximately:
// {
//     let mut record = logwise::hidden::info_sync_pre(file!(), line!(), column!());
//     let mut formatter = logwise::hidden::PrivateFormatter::new(&mut record);
//     formatter.write_literal("User ");
//     formatter.write_val("alice");
//     formatter.write_literal(" has ");
//     formatter.write_val(42);
//     formatter.write_literal(" items");
//     logwise::hidden::info_sync_post(record);
// }

Key-Value Parsing

Format strings support embedded key-value pairs:

• Keys are extracted from {key} placeholders in the format string
• Values are provided as key=value parameters after the format string
• The parser handles complex Rust expressions as values, including method calls and literals

Privacy Integration

These macros integrate with logwise’s privacy system via the Loggable trait. Values are processed through formatter.write_val() which respects privacy constraints.

Macros

debuginternal_async

Asynchronous debug-internal logging (debug builds only).

debuginternal_sync

Synchronous debug-internal logging (debug builds only).

error_async

Asynchronous error-level logging (all builds).

error_sync

Synchronous error-level logging (all builds).

info_async

Asynchronous info-level logging (debug builds only).

info_sync

Synchronous info-level logging (debug builds only).

lformat

Low-level macro for generating formatter calls from format strings.

mandatory_async

Asynchronous mandatory-level logging (all builds).

mandatory_sync

Synchronous mandatory-level logging (all builds).

perfwarn

Block-scoped performance warning interval (all builds).

perfwarn_begin

Begin a performance warning interval (all builds).

perfwarn_begin_if

Conditional performance warning interval.

profile_async

Asynchronous profile-level logging (all builds).

profile_begin

Begin a profile interval (all builds).

profile_sync

Synchronous profile-level logging (all builds).

trace_async

Asynchronous trace-level logging (debug builds only, per-thread activation).

trace_sync

Synchronous trace-level logging (debug builds only, per-thread activation).

warn_sync

Synchronous warning-level logging (all builds).

Attribute Macros

profile

Attribute macro to automatically profile a function’s execution time.