inst/docs/en/reference/logging-timing.md

In Rclade: Automated Deep-Time Phylogenetic Tree Collapsing and Visualization

Logging & Timing

Structured, leveled logging and timers for pipeline observability.

This module contains the following functions:

• set_log_enabled — Enable or disable logging
• set_log_file — Set log file for dual output
• set_log_level — Set log level
• log_info — Log an INFO message
• log_debug — Log a DEBUG message
• log_warning — Log a WARNING message
• log_error — Log an ERROR message
• log_critical — Log a CRITICAL message
• log_section — Print a formatted section header
• log_subsection — Print a formatted subsection header
• log_progress — Log a progress indicator
• log_keyvalue — Log a key-value pair
• log_stats — Print summary statistics
• log_table — Print a formatted table
• timer_start — Start a timer for performance measurement
• timer_stop — Stop a timer and log elapsed time

set_log_enabled

Enable or disable logging

Usage:

set_log_enabled(enabled)

Arguments:

| Argument | Description | |----------|-------------| | enabled | Logical. |

Examples:

set_log_enabled(FALSE)  # turn off all logging

set_log_file

Set log file for dual output

Usage:

set_log_file(filepath)

Arguments:

| Argument | Description | |----------|-------------| | filepath | Character. Path to log file. NULL to disable. |

Examples:

set_log_file("rclade.log")

set_log_level

Set log level

Usage:

set_log_level(level)

Arguments:

| Argument | Description | |----------|-------------| | level | Character. One of "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL". |

Examples:

set_log_level("DEBUG")

log_info

Log an INFO message

Usage:

log_info(..., .module = NULL)

Arguments:

| Argument | Description | |----------|-------------| | ... | Message components (passed to sprintf if multiple). | | .module | Character. Optional module/function tag (§15). Default: NULL. |

Examples:

log_info("Starting processing", .module = "main")

log_debug

Log a DEBUG message

Usage:

log_debug(..., .module = NULL)

Arguments:

| Argument | Description | |----------|-------------| | ... | Message components (passed to sprintf if multiple). | | .module | Character. Optional module/function tag (§15). Default: NULL. |

Examples:

log_debug("variable x =", 42, .module = "parse")

log_warning

Log a WARNING message

Usage:

log_warning(..., .module = NULL)

Arguments:

| Argument | Description | |----------|-------------| | ... | Message components (passed to sprintf if multiple). | | .module | Character. Optional module/function tag (§15). Default: NULL. |

Examples:

log_warning("Clade not monophyletic, skipped", .module = "collapse")

log_error

Log an ERROR message

Usage:

log_error(..., .module = NULL)

Arguments:

| Argument | Description | |----------|-------------| | ... | Message components (passed to sprintf if multiple). | | .module | Character. Optional module/function tag (§15). Default: NULL. |

Examples:

log_error("File not found", .module = "io")

log_critical

Log a CRITICAL message

Usage:

log_critical(..., .module = NULL)

Arguments:

| Argument | Description | |----------|-------------| | ... | Message components (passed to sprintf if multiple). | | .module | Character. Optional module/function tag (§15). Default: NULL. |

Examples:

log_critical("Out of memory", .module = "main")

log_section

Print a formatted section header

Usage:

log_section(title)

Arguments:

| Argument | Description | |----------|-------------| | title | Character. Section title. |

Examples:

log_section("Stage 1: Reading data")

log_subsection

Print a formatted subsection header

Usage:

log_subsection(title)

Arguments:

| Argument | Description | |----------|-------------| | title | Character. Subsection title. |

Examples:

log_subsection("Sub-step: parsing labels")

log_progress

Log a progress indicator

Usage:

log_progress(current, total, item = "")

Arguments:

| Argument | Description | |----------|-------------| | current | Integer. Current progress. | | total | Integer. Total items. | | item | Character. Description of current item. |

Examples:

log_progress(3, 10, item = "Processing tree file")

log_keyvalue

Log a key-value pair

Usage:

log_keyvalue(key, value, level = "INFO")

Arguments:

| Argument | Description | |----------|-------------| | key | Character. Key name. | | value | Any. Value to display. | | level | Character. Log level. Default: "INFO". |

Examples:

log_keyvalue("Number of nodes", 1234)

log_stats

Print summary statistics

Usage:

log_stats(stats)

Arguments:

| Argument | Description | |----------|-------------| | stats | Named list of statistics. |

Examples:

log_stats(list(files = 5, tips = 120))

log_table

Print a formatted table

Usage:

log_table(data, title = NULL)

Arguments:

| Argument | Description | |----------|-------------| | data | Named list or data.frame to display. | | title | Character. Optional table title. |

Examples:

log_table(data.frame(a = 1:3, b = letters[1:3]),
         title = "Statistics")

timer_start

Start a timer for performance measurement

Usage:

timer_start(name)

Arguments:

| Argument | Description | |----------|-------------| | name | Character. Timer name. |

Examples:

timer_start("pipeline")

timer_stop

Stop a timer and log elapsed time

Usage:

timer_stop(name, level = "INFO")

Arguments:

| Argument | Description | |----------|-------------| | name | Character. Timer name. | | level | Character. Log level. Default: "INFO". |

Value:

Numeric. Elapsed seconds.

Examples:

timer_stop("pipeline")

中文 | 文档首页

Rclade documentation built on Sept. 26, 2026, 5:07 p.m.