Home

Traffic Server Software Developers Kit

Prev — Coupled Statistics
INKTextLogObjectHeaderSet — Next

Logging Functions

INKTextLogObjectCreate

Creates a new custom log for your plugin.

Prototype

INKReturnCode INKTextLogObjectCreate (const char *filename, int mode, INKTextLogObject *new_logobj)

Arguments

Const char *filename is the name of the new log file created in the log directory. You can specify a path to a subdirectory within the log directory (e.g. subdir/filename), but make sure you create the subdirectory first. If you do not specify a file name extension, then the extension .log is automatically added.

The logs you create are treated like ordinary logs - that is, they are rolled if log rolling is enabled. Log collation, however, is not supported.

int mode can be 0 and/or the following:

INK_LOG_MODE_ADD_TIMESTAMP

Whenever the plugin makes a log entry using INKTextLogObjectWrite (see below), it prepends the entry with a timestamp.

INK_LOG_MODE_DO_NOT_RENAME

This means that if there is a filename conflict, then Traffic Server should not attempt to rename the custom log. As a consequence of the name conflict, the custom log is not created.

INKTextLogObject *new_logobj is set to the newly-created log object.

Description

Creates a custom log for your plugin. Once the log object is created, use the APIs below to set properties.

  • INKTextLogObjectRollingEnabledSet

  • INKTextLogObjectRollingIntervalSecSet

  • INKTExtLogObjectRollingOffsetHrSet

If the value of mode is not a valid value, then the behavior of the API cannot be predicted.

Example

Suppose you call:

INKTextLogObjectCreate ("squid" , mode, NULL, &log);

If mode is INK_LOG_MODE_DO_NOT_RENAME, then you will not get a new log if squid.log already exists (you'll get an error instead).

If mode is not INK_LOG_MODE_DO_NOT_RENAME, then Traffic Server tries to rename the log to a new name (it will try squid_1.log).

If a log object is created with INK_LOG_MODE_DO_NOT_RENAME mode and a log with the same file name already exists, then the signature (i.e., the type of log file) is compared. If the signatures of the log files match, then the pre-existing file is opened and logging is resumed at the end of the file. If the signatures do not match, then an error is returned.

If a log object is created without INK_LOG_MODE_DO_NOT_RENAME mode and a log with the same file name already exists, then the signature (i.e., the type of log file) is compared. If the signatures of the log files match, then the pre-existing file is opened and logging is resumed at the end of the file. If the signature does not match, then another file with filename_1.log is tried and so on.

Note: The log file signature is the type of log file. Log files can be structured/fixed format log files or unstructured/free format log files. All free format log files have the same signature, while structured log files have the same structured/fixed format as the signature.

Returns

INK_SUCCESS if the API is called successfully.

INK_ERROR if an error occurs while calling the API or if an argument is invalid.