Dbg

Traffic Server Debugging APIs.

Synopsis

#include <ts/ts.h>
void TSStatus(const char *format, ...)
void TSNote(const char *format, ...)
void TSWarning(const char *format, ...)
void TSError(const char *format, ...)
void TSFatal(const char *format, ...)
void TSAlert(const char *format, ...)
void TSEmergency(const char *format, ...)
type DbgCtl
void Dbg(DbgCtl &ctl, const char *format, ...)
bool DbgCtl::on()
void SpecificDbg(bool debug_flag, DbgCtl &ctl, const char *format, ...)
void DbgPrint(DbgCtl &ctl, const char *format, ...)
void TSHttpTxnDebugSet(TSHttpTxn txnp, int on)
void TSHttpSsnDebugSet(TSHttpSsn ssn, int on)
int TSHttpTxnDebugGet(TSHttpTxn txnp)
int TSHttpSsnDebugGet(TSHttpSsn ssn)
const char *TSHttpServerStateNameLookup(TSServerState state)
const char *TSHttpHookNameLookup(TSHttpHookID hook)
const char *TSHttpEventNameLookup(TSEvent event)
TSAssert(...)
TSReleaseAssert(...)

diags.log

The following methods print to diags.log with expected reactions as a coordinated outcome of Traffic Server, AuTest, CI, and your log monitoring service/dashboard (e.g. Splunk)

API

Purpose

AuTest+CI

LogMonitor

TSStatus()

basic information

TSNote()

significant information

TSWarning()

concerning information

track

TSError()

operational failure

FAIL

review

TSFatal()

recoverable crash

FAIL

review

TSAlert()

significant crash

FAIL

ALERT

TSEmergency()

unrecoverable,misconfigured

FAIL

ALERT

Note

TSFatal(), TSAlert(), and TSEmergency() can be called within TSPluginInit(), such that Traffic Server can be shutdown promptly when the plugin fails to initialize properly.

trafficserver.out

cpp:type:DbgCtl is a C++ class. Its constructor is DbgCtl::DbgCtl(const char *tag). tag is the debug tag for the control, as a null-terminated string. The control is enabled/on when the tag is enabled.

cpp:func:Dbg logs the debug message only if the given debug control referred to by ctl is enabled. It writes output to the Traffic Server debug log through stderr.

ctl.on() (where ctl is an instance of DbgCtl) returns true if ctl is on.

In debug mode, TSAssert Traffic Server to prints the file name, line number and expression, and then aborts. In release mode, the expression is not removed but the effects of printing an error message and aborting are. TSReleaseAssert prints an error message and aborts in both release and debug mode.

cpp:func:SpecificDbg emits a debug line even if the debug tag is turned off, as long as debug flag is enabled. This can be used in conjunction with TSHttpTxnDebugSet(), TSHttpSsnDebugSet(), TSHttpTxnDebugGet() and TSHttpSsnDebugGet() to enable debugging on specific session and transaction objects.

cpp:func:DbgPrint emits a debug line even if the debug tag is turned off.

TSHttpServerStateNameLookup(), TSHttpHookNameLookup() and TSHttpEventNameLookup() converts the respective internal state to a string representation. This can be useful in debugging (cpp:func:Dbg), logging and other types notifications.

(For an example of how to write a plugin with debug tracing, that can be compiled with both Traffic Server Version 10 and older versions of ATS, see redirect_1.)

Examples

This example uses cpp:func:SpecificDbg to log a message when a specific debugging flag is enabled:

#include <ts/ts.h>

DbgCtl dbg_ctl{PLUGIN_NAME};

// Produce information about a hook receiving an event
Dbg(dbg_ctl, "Entering hook=%s, event=%s",
    TSHttpHookNameLookup(hook), TSHttpEventNameLookup(event));

// Emit debug message if "dbg_ctl" is enabled or the txn debug
// flag is set.
SpecificDbg(TSHttpTxnDebugGet(txn), dbg_ctl ,
            "Hello World from transaction %p", txn);

See Also

TSAPI(3ts), printf(3)