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 INKTextLogObjectCreate. 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 INKTextLogObjectCreate
Set the log header for your custom text log: see INKTextLogObjectHeaderSet
Enable or disable rolling your custom text log: see INKTextLogObjectRollingEnabledSet
Set the rolling interval (in seconds) for your custom text log: see INKTextLogObjectRollingIntervalSecSet
Set the rolling offset for your custom text log: see INKTextLogObjectRollingOffsetHrSet
Write text entries to the custom text log: see INKTextLogObjectWrite
Flush the contents of the custom text log’s write buffer to disk: see INKTextLogObjectFlush
Destroy custom text logs when you are done with them: see INKTextLogObjectDestroy

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 INKTextLogObject log;
```
In INKPluginInit, a new log object is allocated:
```
log = INKTextLogObjectCreate("blacklist", INK_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 INK_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[ ]):
```
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) {
       INKTextLogObjectWrite(log, "blacklisting site: %s", sites[i]);
```
The format of the log entry is as follows:

<timestamp>blacklisting site:sites[i]

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

Traffic Server Software Developers Kit

Guide to the Logging API