Crate thag_profiler 

thag_profiler

A performance profiling library for Rust applications.

Feature flags

The following features are supported:

• default — Default features: none
• time_profiling — Enable time-based performance profiling.
• full_profiling — Enable comprehensive profiling including time and memory usage.
• debug_logging — Enable debug logging of profiling code.
• internal_docs — Enable documentation of internal APIs and implementation details.
• document-features — Documentation features
• analyze_tool — Include dependencies required only for thag_profile binary.
• tools — Include dependencies for all tools.
• instrument_tool — Include dependencies required for thag_instrument and thag_uninstrument binaries.
• demo — Enable demo visualization functionality with required dependencies.
• inquire_theming — Enable theme-aware inquire UI integration.

Examples

# Time profiling only (default)
thag_profiler = { version = "0.1.0" }

# Full profiling with memory tracking
thag_profiler = { version = "0.1.0", features = ["full_profiling"] }

Basic Usage

// Enable profiling for the program.
// To disable it while keeping the instrumentation, you can either
// disable the profiling features in the `thag_profiler` dependency
// or simply specify `#[enable_profiling(no)]`.
use thag_profiler::{enable_profiling, profiled};
#[enable_profiling]
fn main() {
    // Function code...
    println!("some_calculation()={}", some_calculation());
}

// Instrument a function
#[profiled]
fn some_calculation() -> u64 {
    // Function code...
    42
}

Documentation Levels

This crate provides two levels of documentation:

• Public API (default): Clean, user-focused documentation
• Internal API (with internal_docs feature): Includes implementation details

Enable the internal_docs feature when building documentation to see internal utilities, debug functions, and implementation details that are normally hidden.

For details including attribute arguments see the main thag_profiler README.md.

Re-exports

pub use profiling::disable_profiling;

pub use profiling::extract_filename_timestamp;

pub use profiling::is_profiling_enabled;

pub use profiling::Profile;

pub use profiling::ProfileConfiguration;

pub use profiling::ProfileType;

pub use profiling::clear_profile_config_cache;

pub use profiling::get_config_profile_type;

pub use profiling::get_global_profile_type;

pub use profiling::is_detailed_memory;

pub use profiling::parse_env_profile_config;

pub use profiling::strip_hex_suffix_slice;

pub use mem_attribution::find_profile;

pub use mem_attribution::register_profile;

pub use mem_attribution::ProfileRef;

pub use mem_tracking::create_memory_task;

pub use mem_tracking::current_allocator;

pub use mem_tracking::get_last_active_task;

pub use mem_tracking::record_allocation;

pub use mem_tracking::Allocator;

pub use mem_tracking::Dispatcher;

pub use mem_tracking::TaskGuard;

pub use mem_tracking::TaskMemoryContext;

pub use mem_tracking::TrackingAllocator;

pub use profiling::extract_path;

pub use visualization::prompted_analysis;

pub use visualization::AnalysisType;

pub use mem_tracking::compare_exchange_using_system;

pub use mem_tracking::get_using_system;

pub use mem_tracking::reset_allocator_state;

pub use mem_tracking::set_using_system;

pub use profiling::PROFILING_MUTEX;

Modules

__private

Private module for internal macro implementations.

mem_attribution

Memory attribution module manages a profile registry for use with the full_profiling feature.

mem_tracking

Memory tracking module for use with the full_profiling feature. Task-aware memory allocator for profiling.

profiling

Core profiling module for profile definition and handling.

visualization

Demo visualization utilities for analyzing profiling data. Demo visualization utilities for thag_profiler

Macros

debug_log

Zero-cost debug logging gated behind feature debug_logging.

end

Proc macro for use with thag_profiler. This macro defines the end of the scope of a profile! macro with the same name argument, and also explicitly drops the profile in ring-fenced profiler code.

lazy_static_var

Core profiling functionality and configuration. Lazy-static variable generator.

profile

Proc macro for use with thag_profiler. This macro profiles a section of user code between itself and an optional end! macro with a matching name argument.

re

Core profiling functionality and configuration. Lazy-static regular expression generator.

safe_alloc

Safe allocation macro that passes through expressions when full profiling is disabled.

set_verbosity

Core profiling functionality and configuration. Convenient macro for setting global verbosity with short syntax.

static_lazy

Core profiling functionality and configuration. Creates a lazily-initialized static variable.

warn_once

Macro for executing code only once with an optimized fast path.

Structs

DebugLogger

Debug logging utilities.

Enums

ProfileError

Core profiling functionality and configuration. Error types that can occur during profiling operations.

Constants

PROFILING_FEATURE_ENABLED

Constant reflecting whether any profiling feature is enabled.

Functions

enhance_svg_accessibility

Rewrite the svg file with the Search link rendered more visible.

file_stem_from_path

Extract the file stem from a Path.

file_stem_from_path_str

Extract the file stem from a path string.

finalize_profiling

Finalize profiling and write out data files. Called by the #[enable_profiling] attribute macro at program termination.

flush_debug_log

Debug logging utilities.

get_base_location

Retrieve preset base location for profile backtrace cutoff (typically lib.rs::init_profiling) Get the base location set during profiling initialization.

get_debug_log_path

Debug logging utilities.

get_root_module

Retrieve profiled root module Get the root module name set during profiling initialization.

init_profiling

Initialize the profiling system. Called by the #[enable_profiling] attribute macro to set up profiling.

init_verbosity

Core profiling functionality and configuration. Initialize verbosity with a convenient function that handles common patterns.

set_global_verbosity

Core profiling functionality and configuration. Set the output verbosity for the current execution.

thousands

Formats a given positive integer with thousands separators (commas).

Type Aliases

ProfileResult

Core profiling functionality and configuration. A specialized Result type for profiling operations. Provides a convenient shorthand for Result<T, ProfileError>.

V

Core profiling functionality and configuration. Type alias for Verbosity to provide a shorter name for convenience

Attribute Macros

enable_profiling

Attribute macro for use with thag_profiler. This macro is intended to annotate the user main function in order to to enable and control profiling of the user code.

fn_name

Core profiling functionality and configuration. Define common errors for thag tools.

internal_doc

Core profiling functionality and configuration. Attribute macro for marking items as internal documentation.

profiled

Attribute macro for use with thag_profiler. This macro is intended to annotate user functions other than main in order to to control profiling of each function individually.

timing

Demo utilities. Measures and displays function execution time.