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()
Set the rolling size for your custom text log: see TSTextLogObjectRollingSizeMbSet()
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 section.

A new log file is defined as a global variable.
```
static TSTextLogObject log;
```
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.

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);
}

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.