zlog Documentation

Rotation controls how log files are managed by size and count to prevent disk exhaustion.

Syntax for file rotation: "(file path)", (size) * (count) ~ "(archive name)"

• Size: The threshold that triggers rotation (e.g., 10MB).
• Count: The number of archive files to keep. 0 means keep all. If not specified, all old logs are kept.
• Archive Name: Must include #r for Rolling or #s for Sequence.

Rolling (#r) behavior: When out.log reaches the limit, it is renamed to out.log.1. The next rotation moves out.log.1 to out.log.2, and so on. The oldest file has the highest serial number.

Sequence (#s) behavior: When aa.log reaches the limit, it is renamed to aa.log.0. The next rotation moves aa.log.0 to aa.log.1, and so on.

Examples:

• "aa.log", 10MB: Simple rolling rotation.
• "aa.log", 10MB * 3 ~ "aa.log.#r": Rotates at 10MB, keeps 3 archives, uses rolling naming.

MDC (Mapped Diagnostic Context) is a thread-local key-value map. It allows you to attach metadata to log entries, which can then be included in the log format or used to dynamically generate log file paths. This is useful for distinguishing between different scenarios (like different customers) in concurrent processing.

Key features:

• Thread Safety: The MDC map belongs to the thread; calling zlog_put_mdc() in one thread does not affect others.
• Format Integration: Use %M(key) in your configuration [formats] to print the value associated with key.
• Dynamic Paths: Use %M(key) in your configuration [rules] to create separate log files based on the MDC value (e.g., "mdc_%M(customer_name).log";).

API:

• zlog_put_mdc(const char *key, const char *value): Sets the value for the specified key in the current thread.

// Example usage
zlog_put_mdc("myname", "Zhang");
zlog_info(zc, "2.hello, zlog");

zlog uses a matching mechanism between source code categories and configuration file rules. A rule consists of a category, a level, an output channel, and a format.

When you retrieve a category in your C code using zlog_get_category("my_cat"), zlog looks for rules in the [rules] section of the configuration file that match the string my_cat.

Example Workflow:

1. Source Code: zlog_info(c, "hello, zlog"); where c is a category named my_cat.
2. Config Rule: my_cat.DEBUG >stdout; simple
3. Matching: zlog checks if the log level (INFO) is greater than or equal to the rule level (DEBUG). Since INFO >= DEBUG, the log is sent to stdout using the simple format.
4. Format Definition: [formats] simple = "%m%n" determines the final output string.

zlog_category_t *c;
c = zlog_get_category("my_cat");
zlog_info(c, "hello, zlog");

You can take control of how logs are handled by defining a custom output function. In this mode, zlog is responsible for generating the log path and message dynamically based on your configuration, but you are responsible for the actual output, rotation, and cleanup actions.

To implement user-defined output:

1. Define a placeholder name in the [rules] section of your configuration file.
2. Register a C function to that name using zlog_set_record().
3. The function must accept a zlog_msg_t * pointer.

Note: Implementing complex rotation logic (like size-based or time-based rotation) in a custom output function can be difficult in multi-process or multi-threaded environments.

# 1. Define in configuration file
[formats]
simple = "%m%n"

[rules]
my_cat.* $myoutput, " mypath %c %d";simple

# 2. Set the function in C
#include "zlog.h"

int output(zlog_msg_t *msg)
{
    printf("[mystd]:[%s][%s][%ld]\n", msg->path, msg->buf, (long)msg->len);
    return 0;
}

int main(int argc, char** argv)
{
    int rc;
    zlog_category_t *zc;

    rc = zlog_init("test_record.conf");
    if (rc) {
        return -1;
    }

    // Register the custom output function
    zlog_set_record("myoutput", output);

    zc = zlog_get_category("my_cat");
    if (!zc) {
        zlog_fini();
        return -2;
    }

    zlog_info(zc, "hello, zlog");
    zlog_fini();
    return 0;
}