Guide to the 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:

Establish a custom text log for your plugin: see TSTextLogObjectCreate
Set the log header for your custom text log: see TSTextLogObjectHeaderSet
Enable or disable rolling your custom text log: see TSTextLogObjectRollingEnabledSet
Set the rolling interval (in seconds) for your custom text log: see TSTextLogObjectRollingIntervalSecSet
Set the rolling offset for your custom text log: see TSTextLogObjectRollingOffsetHrSet
Write text entries to the custom text log: see TSTextLogObjectWrite
Flush the contents of the custom text log's write buffer to disk: see TSTextLogObjectFlush
Destroy custom text logs when you are done with them: see TSTextLogObjectDestroy

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 appendix.

A new log file is defined as a global variable.
```
  static TSTextLogObject log;
```
In TSPluginInit, a new log object is allocated:
```
    log = TSTextLogObjectCreate("blacklist", TS_LOG_MODE_ADD_TIMESTAMP, NULL, &error);
```
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.

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

if (!log) {
    printf("Blacklist plugin: error %d while creating log\n", error);
}

The blacklist-1 plugin matches the host portion of the URL (in each client request) with a list of blacklisted sites (stored in the array sites[]):

::::c 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:

::::c if (log) { TSTextLogObjectWrite(log, "blacklisting site: %s", sites[i]); The format of the log entry is as follows:

:::text blacklisting site: sites[i] The log is not flushed or destroyed in the blacklist-1 plugin - it lives for the life of the plugin.

Programmers Guide