Log Rust Reference Documentation

Log

Current Version: 11.6.1

Chilkat.Log

Build readable structured diagnostic logs with nested context and tagged values.

Chilkat.Log is a lightweight structured logging helper for creating readable diagnostic logs from application code. It can record nested operation contexts, informational messages, error messages, timestamps, integers, 64-bit integers, tagged values, binary data, Base64 data, hex data, shortened data previews, and computed hashes. It is useful when code needs a clear step-by-step record of operations, inputs, outputs, and diagnostic values for troubleshooting.

Nested operation context

Use EnterContext and LeaveContext to group log entries under readable operation names.

Messages and errors

Add informational messages, error messages, and tagged text values to explain what the application is doing.

Numbers and timestamps

Log integers, 64-bit integers, timestamps, and date/time values when tracing state changes or timing-sensitive workflows.

Binary diagnostics

Record binary data as Base64, hex, or shortened previews so byte-level values can be inspected safely in text logs.

Hash logging

Compute and log hashes of data when comparing content, verifying transformations, or avoiding full data dumps.

Clear and reuse

Clear the log and continue building new diagnostic output during repeated operations or test runs.

Common pattern: Create a Log object, enter a named context for the operation, log the important values and decisions as the code runs, leave the context, and inspect the resulting text if troubleshooting is needed. Use Chilkat.Log for application-level diagnostic output; use LastErrorText on Chilkat objects for detailed diagnostics from Chilkat method calls.

For an extended overview, see Log Class Overview.

Object Creation

// Cargo.toml:
//     [dependencies]
//     chilkat = "11.6"

use chilkat::Log;

// Once per process, before any other Chilkat call:
chilkat::unlock_bundle("Anything for 30-day trial")?;  // shorthand for Global::new().unlock_bundle(..)

let log = Log::new();
// ... the native object is freed when `log` goes out of scope.
pub fn new() -> Log

Creates the underlying native Chilkat object (Log also implements Default). Every method takes &self, so the object never needs to be declared mut. A Log is Send but not Sync: it may be moved to another thread, but a reference to it cannot be shared between threads at the same time.

impl Drop for Log

The native object is freed when the Log is dropped — when it goes out of scope, or explicitly with drop(log). There is no Dispose method to call.

Errors

Methods that can fail return chilkat::Result<T>, which is Result<T, chilkat::Error>: a method whose only outcome is success or failure returns Result<()>, a method producing a string or an object returns Result<String> or Result<Log>. The error carries the object's LastErrorText at the time of the failure (Error::last_error_text), the class and method names, and implements std::error::Error, so ? works in any function returning chilkat::Result or a Box<dyn Error>. Properties never fail, and methods that answer a question (has_..., is_..., ...) return a plain bool.

match log.some_method(...) {
    Ok(value) => println!("{value:?}"),
    Err(e) => eprintln!("{}", e.last_error_text()),
}

Properties

DebugLogFilePath
// read/write
pub fn debug_log_file_path(&self) -> String
pub fn set_debug_log_file_path(&self, value: &str)

If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.

Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.

Possible causes of hangs include:

  • A timeout property set to 0, indicating an infinite timeout.
  • A hang occurring within an event callback in the application code.
  • An internal bug in the Chilkat code causing the hang.

More Information and Examples
Example showing how to use DebugLogFilePath.
top
LastErrorHtml
// read-only
pub fn last_error_html(&self) -> String

Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastErrorText
// read-only
pub fn last_error_text(&self) -> String

Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

More Information and Examples
Concept of LastErrorTextLastErrorText Standard Information
top
LastErrorXml
// read-only
pub fn last_error_xml(&self) -> String

Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastMethodSuccess
// read/write
pub fn last_method_success(&self) -> bool
pub fn set_last_method_success(&self, value: bool)

Indicates the success or failure of the most recent method call: true means success, false means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.

top
VerboseLogging
// read/write
pub fn verbose_logging(&self) -> bool
pub fn set_verbose_logging(&self, value: bool)

If set to true, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is false. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

top
Version
// read-only
pub fn version(&self) -> String

Version of the component/library, such as "10.1.0"

More Information and Examples
How to get the Chilkat version at runtime.
top

Methods

Clear
pub fn clear(&self, initial_tag: &str)
Introduced in version 9.5.0.44

Clears all existing log entries and starts a new log whose top-level context is named initialTag.

Typical use: Call this at the beginning of an operation or test run, then add entries with the other Log* methods. The completed structured log can be inspected through the Log object's diagnostic text, such as LastErrorText.
top
EnterContext
pub fn enter_context(&self, tag: &str)
Introduced in version 9.5.0.44

Begins a nested logging context named tag. Entries written after this call are grouped inside the new context until a matching LeaveContext is called.

Balanced contexts: Pair each EnterContext with LeaveContext. Contexts may be nested to reflect operation hierarchy.
More Information and Examples
Enter/Leave Context in Logging
top
LeaveContext
pub fn leave_context(&self)
Introduced in version 9.5.0.44

Ends the current nested logging context and returns logging to its parent context.

Empty contexts are omitted: If nothing was logged after entering the current context, Chilkat automatically removes that empty context when it is left.
top
LogData
pub fn log_data(&self, tag: &str, message: &str)
Introduced in version 9.5.0.44

Adds a tagged text value to the current context. The output associates tag with message, making this useful for named values such as filenames, paths, IDs, states, or protocol fields.

Sensitive data: Avoid logging passwords, private keys, access tokens, session secrets, or other sensitive values unless disclosure is intentional.
top
LogDataBase64_2
pub fn log_data_base64_2(&self, tag: &str, byte_data: &[u8])
Introduced in version 9.5.0.82

Encodes szByteData bytes beginning at pByteData as Base64 and logs the result under tag.

C++ byte buffer: This form accepts a pointer and explicit byte count. Base64 is printable encoding only; it does not protect the logged data.
top
LogDataHex2
pub fn log_data_hex2(&self, tag: &str, byte_data: &[u8])
Introduced in version 9.5.0.82

Encodes szByteData bytes beginning at pByteData as hexadecimal text and logs the result under tag.

C++ byte buffer: This form accepts a pointer and explicit byte count. The caller must supply a valid buffer containing at least szByteData readable bytes.
top
LogDataMax
pub fn log_data_max(&self, tag: &str, message: &str, max_num_chars: i32)
Introduced in version 9.5.0.44

Adds a tagged text value to the current context, but limits the logged value to at most the first maxNumChars characters of message.

Diagnostic previews: Use this when a value may be very large and only a leading preview is needed. The original input string is not modified.
top
LogDateTime
pub fn log_date_time(&self, tag: &str, gmt: bool)
Introduced in version 9.5.0.44

Logs the current date and time under tag using an RFC 822-style date/time representation. If gmt is true, the logged time is GMT/UTC; otherwise local system time is used.

Date/time vs. timestamp: Use LogDateTime for a calendar date with timezone context. Use LogTimestamp for a time-of-day marker.
top
LogError
pub fn log_error(&self, message: &str)
Introduced in version 9.5.0.44

Adds message as an error entry in the current logging context.

Application diagnostics: This is application-defined logging. It is separate from LastErrorText produced by other Chilkat objects when their operations fail.
top
LogHash2
pub fn log_hash2(&self, tag: &str, hash_alg: &str, byte_data: &[u8])
Introduced in version 9.5.0.82

Computes a hash of szByteData bytes beginning at pByteData and logs the digest as hexadecimal text under tag. Supported values for hashAlg are SHA1, SHA256, SHA384, SHA512, and MD5.

Useful for comparison: A digest is often preferable to dumping a large binary value when the goal is to determine whether two byte sequences are identical.
Security note: MD5 and SHA1 are not suitable when cryptographic collision resistance is required. Prefer SHA-256 or stronger for security-sensitive hashing.
top
LogInfo
pub fn log_info(&self, message: &str)
Introduced in version 9.5.0.44

Adds message as an informational entry in the current logging context.

Structured tracing: Use informational entries for significant steps and decisions. Use LogData when the entry is better represented as a named value.
top
LogInt
pub fn log_int(&self, tag: &str, value: i32)
Introduced in version 9.5.0.44

Adds the integer value to the current log under tag.

top
LogInt64
pub fn log_int64(&self, tag: &str, value: i64)
Introduced in version 9.5.0.44

Adds the signed 64-bit integer value to the current log under tag.

64-bit values: Useful for values such as large byte counts, file sizes, sequence numbers, or timestamps that can exceed ordinary integer ranges.
top
LogTimestamp
pub fn log_timestamp(&self, tag: &str)
Introduced in version 9.5.0.44

Logs the current time-of-day under tag in HH:MM:SS:mmm form, where mmm represents milliseconds.

Timing note: This is a time-of-day marker, not a monotonic elapsed-time measurement.
top