Logging API

The logging API enables your plugin to log entries in a custom text log file that you create with the call TSTextLogObjectCreate(). This log file is part of Traffic Server’s logging system; by default, it is stored in the logging directory. Once you have created the log object, you can set log properties.

The logging API enables you to:

The steps below show how the logging API is used in the blacklist_1.c sample plugin. For the complete source code, see the Sample Source Code section.

  1. A new log file is defined as a global variable.

    static TSTextLogObject log;
    
  2. In TSPluginInit, a new log object is allocated:

    TSReturnCode error = TSTextLogObjectCreate("blacklist",
                         TS_LOG_MODE_ADD_TIMESTAMP, &log);
    

    The new log is named blacklist.log. Each entry written to the log will have a timestamp. The NULL argument specifies that the new log does not have a log header. The error argument stores the result of the log creation; if the log is created successfully, then an error will be equal to TS_LOG_ERROR_NO_ERROR.

  3. After creating the log, the plugin makes sure that the log was created successfully:

    if (error != TS_SUCCESS) {
        printf("Blacklist plugin: error %d while creating log\n", error);
    }
    
  4. The Blacklist Plugin matches the host portion of the URL (in each client request) with a list of blacklisted sites (stored in the array sites[]):

    for (i = 0; i < nsites; i++) {
      if (strncmp (host, sites[i], host_length) == 0) {
        /* ... */
      }
    }
    

    If the host matches one of the blacklisted sites (such as sites[i]), then the plugin writes a blacklist entry to blacklist.log:

    if (log) { TSTextLogObjectWrite(log, "blacklisting site: %s",
    sites[i]);
    

    The format of the log entry is as follows:

    blacklisting site: sites[i]
    

    The log is not flushed or destroyed in the blacklist_1 plugin - it lives for the life of the plugin.