xSQL Tracing Framework

As explained in the Tracing Framework page, eXtremeDB provides APIs that allow applications to output trace and debugging information to a log file. Please view the C API Tracing Framework page for details about the various tracing options. For xSQL, these options are specified in the configuration file's trace_params section.

For an overview, see the xSQL Configuration File Options page.

Configuration File Example

The following configuration file example shows how the various tracing options can be set:

    # Tracing parameters
    trace_params : 
    {
        # Specifies filename where tracing will go. It is possible to specify "stderr" 
        # to pass all the messages to standard error stream.
        file : "xsql.log",

        # Format for the messages. Format specifiers are: %s and %e
        format: "%s: %e",

        # Maximum severity for messages appearing in the trace file.
        # Possible values are: verbose, debug, info, notice, warning, error, fatal.
        severity: info,

        # Options that control if the file will be closed and reopened for each written record.
        # Possible values are: leave_opened, keep_closed.
        options: keep_closed,

        # Delivery mode: 'sync' or 'async'. If omitted, async mode is inferred
        # when rotation, rotate_existing, or explicit queue settings are present.
        mode: async,

        # Existing-base-file policy at process start: append, truncate, rotate_existing.
        start_policy: append,

        # Rotation policy: none, size, or time. Size and time rotation require async mode.
        rotate_policy: size,

        # Soft size threshold in bytes; rotation happens between complete records.
        size_rotate_bytes: 10485760,

        # Time threshold in seconds; rotation happens when a later record is written.
        time_rotate_period: 86400,

        # Rotated-file retention count; zero means unlimited.
        rotated_file_limit: 5,

        # Async queue capacity; zero selects the historical unbounded queue.
        queue_capacity: 4096,

        # Full bounded-queue policy: drop_newest, drop_oldest, or block.
        queue_overflow: drop_newest
    }
            

Tracing Mode Selection

When the mode parameter is omitted, xSQL infers the delivery mode as follows:

• Async mode is selected automatically when start_policy is rotate_existing, when rotate_policy is size or time, or when explicit queue settings (queue_capacity or queue_overflow) are present.
• Otherwise, xSQL uses sync mode.

An explicit mode: sync combined with an async-only setting (such as rotation or rotate_existing) is rejected as an invalid configuration rather than being silently ignored.

Environment Variables Overlay

Environment variables overlay the xSQL trace_params fields individually. The same validation and mode-inference rules apply to the overlaid values. For a complete list of supported MCO_TRACE* environment variables, see the Tracing Framework page.

Startup, Restart, and Shutdown Behavior

• Startup and Restart: xSQL uses the same configuration helper during both initial startup and daemon restart, ensuring consistent tracing behavior across the application lifecycle.
• Error Reporting: The daemon restart path checks and reports both runtime and trace startup errors, instead of continuing with a partially initialized process.
• Graceful Shutdown: Shutdown drains configuration-owned async tracing before SAL teardown, ensuring that queued records are not lost.