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 denylist_1.cc 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 ts_log;
    
  2. In TSPluginInit, a new log object is allocated:

    TSReturnCode error = TSTextLogObjectCreate("denylist",
                         TS_LOG_MODE_ADD_TIMESTAMP, &ts_log);
    

    The new log is named denylist.log. Each entry written to the log will have a timestamp. The nullptr 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("denylist plugin: error %d while creating log\n", error);
    }
    
  4. The Denylist Plugin matches the host portion of the URL (in each client request) with a list of denylisted 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 denylisted sites (such as sites[i]), then the plugin writes a denylist entry to denylist.log:

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

    The format of the log entry is as follows:

    denylisting site: sites[i]
    

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