Chilkat.Log Class Overview

Chilkat.Log is a lightweight structured logging helper for building diagnostic logs with nested contexts, tagged values, informational messages, error messages, timestamps, integers, binary data, and hashes. It is useful when code needs to record a readable sequence of operations and values for troubleshooting.

What the Class Is Used For

Use Chilkat.Log when an application needs to construct a diagnostic log in a structured way. A log can be organized into nested contexts, and each context can contain tagged data, messages, timestamps, encoded binary data, hashes, and numeric values.

Organize by Context Use EnterContext and LeaveContext to create nested sections.
Log Named Values Add tagged strings, integers, 64-bit integers, timestamps, dates, and limited strings.
Log Binary Data Safely Record binary data as Base64, hex, or a computed hash.
Record Diagnostics Use informational and error messages to show what happened inside a context.

Typical Workflow

  1. Create a Log object.
  2. Call Clear with an initial top-level tag to start a new log.
  3. Call EnterContext before a logical operation or nested section.
  4. Add messages and values with methods such as LogInfo, LogError, LogData, LogInt, or LogTimestamp.
  5. For binary data, use LogDataBase64, LogDataHex, or LogHash2.
  6. Call LeaveContext when the logical operation is complete.
  7. If a method fails or behaves unexpectedly, inspect LastErrorText.
Context pairing: Every call to EnterContext should be paired with a matching call to LeaveContext.

Core Concepts

Concept Meaning Important Members
Top-Level Context The root tag for a new log. Clear
Nested Contexts Logical sections inside the log, useful for grouping related operations. EnterContext, LeaveContext
Tagged Data Name/value entries added to the current context. LogData, LogInt, LogInt64
Messages Human-readable informational or error text. LogInfo, LogError
Binary Logging Binary data can be represented as Base64, hex, or a hash. LogDataBase64, LogDataHex, LogHash2
Automatic Cleanup Empty contexts are removed automatically when leaving the context. LeaveContext

Property

Property Purpose Guidance
LastErrorText Provides diagnostic information about the last method or property access. Check this property if a method fails or behaves unexpectedly. Diagnostic information may be available regardless of success or failure.

Context Management

Method Purpose Important Details
Clear Clears the current log and starts a new one. The initialTag becomes the initial top-level context tag.
EnterContext Enters a new named context. Must be paired with a matching LeaveContext.
LeaveContext Leaves the current context. A context that contains no logged entries is automatically removed from the log.
Empty context behavior: If a context is entered and then left without any logging inside it, that context is automatically removed from the log.

Logging Text, Messages, and Numbers

Method Logs Use When
LogData A tagged string value. Use for ordinary name/value data, such as hostnames, filenames, states, or request IDs.
LogDataMax A tagged string limited to a maximum number of characters. Use when the value might be long and only the beginning should be recorded.
LogInfo An informational message in the current context. Use to describe normal progress or decisions.
LogError An error message in the current context. Use to record failures or exceptional conditions.
LogInt A tagged integer value. Use for counts, status values, sizes, or other 32-bit numeric values.
LogInt64 A tagged 64-bit integer value. Use for large counts, file sizes, byte offsets, or timestamps represented as integers.

Logging Time Values

Method Output Use When
LogDateTime Current date/time in RFC822 format. Pass true for GMT/UTC time or false for local time.
LogTimestamp Current time in HH:MM:SS:mmm format. Use for lightweight timing markers inside a diagnostic log.

Logging Binary Data

Method Representation Use When
LogDataBase64
LogDataBase64_2 		Base64 Use when binary data should be preserved in a compact text-safe encoding.
LogDataHex
LogDataHex2 		Hexadecimal Use when byte-by-byte inspection is useful or when comparing binary values.
LogHash2 Hash digest in hex format. Use when logging the full binary data is unnecessary or too large, but a stable identifier is useful.
Hash algorithms: LogHash2 supports hash names such as SHA1, SHA256, SHA384, SHA512, and MD5.

Method Summary by Category

Category Methods / Property Purpose
Start and structure logs Clear, EnterContext, LeaveContext Clear the log and organize entries into nested contexts.
Text and messages LogData, LogDataMax, LogInfo, LogError Log tagged text values, truncated text, informational messages, and errors.
Numbers LogInt, LogInt64 Log integer and 64-bit integer values.
Time LogDateTime, LogTimestamp Log RFC822 date/time values or compact time markers.
Binary data LogDataBase64, LogDataBase64_2, LogDataHex, LogDataHex2, LogHash2 Log binary data as Base64, hex, or a hash digest.
Diagnostics LastErrorText Read diagnostic information after failed or unexpected operations.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Log structure is not as expected EnterContext, LeaveContext Verify that every entered context is paired with a matching leave call.
Expected context is missing LeaveContext Empty contexts are automatically removed when leaving the context. Add at least one log entry inside the context if it should remain visible.
Logged string is too large LogDataMax Use a maximum-character limit to record only the beginning of a large string.
Binary data is unreadable LogDataBase64, LogDataHex Choose Base64 for compact transport-safe output or hex for byte-level inspection.
Binary payload is too large to log LogHash2 Log a hash digest instead of the full payload.
Need operation details after failure LastErrorText Check diagnostic text after failed or unexpected logging operations.

Common Pitfalls

Pitfall Better Approach
Entering a context but never leaving it. Pair each EnterContext with LeaveContext.
Expecting empty contexts to remain in the log. Log at least one entry inside a context if it should appear in the final log.
Logging very large text values without limits. Use LogDataMax when only the beginning of a string is needed.
Logging sensitive binary data directly. Use LogHash2 when a digest is enough for comparison or troubleshooting.
Using date/time logs without deciding between local time and GMT. Pass the desired gmt value to LogDateTime.
Ignoring diagnostic information after an unexpected logging result. Check LastErrorText for details.

Best Practices

Recommendation Reason
Use clear context names. Context tags make the log easier to scan and help identify where each value was recorded.
Log important inputs and decisions as tagged values. Structured name/value entries are easier to search and compare than free-form text alone.
Use LogInfo for normal progress and LogError for failures. Separating informational and error entries improves readability.
Use LogTimestamp around timing-sensitive steps. Timestamp markers help identify delays or ordering issues.
Use LogDataMax for potentially large strings. It keeps logs readable and prevents large values from overwhelming diagnostic output.
Prefer hashes for large or sensitive binary values. A digest can confirm whether data changed without logging the entire payload.
Check LastErrorText after failures. It provides useful diagnostic detail for unexpected logging behavior.

Summary

Chilkat.Log is a structured diagnostic logging helper for creating readable logs with nested contexts, tagged values, informational messages, error messages, timestamps, date/time entries, integer values, binary data, and hash digests.

The most important practical guidance is to pair EnterContext with LeaveContext, use tagged values for important data, use LogDataMax for large strings, prefer LogHash2 when full binary data should not be logged, and inspect LastErrorText whenever a logging operation behaves unexpectedly.