diff --git a/doc/admin-guide/files/records.config.en.rst b/doc/admin-guide/files/records.config.en.rst index c50bdf6609a..4bf8dd8aded 100644 --- a/doc/admin-guide/files/records.config.en.rst +++ b/doc/admin-guide/files/records.config.en.rst @@ -3221,6 +3221,10 @@ Diagnostic Logging Configuration When set to 2, interprets the :ts:cv:`proxy.config.diags.debug.client_ip` setting determine whether diagnostic messages are logged. + When set to 3, enables logging for diagnostic messages whose log level is `diag` or `debug`, except those + output by deprecated functions such as `TSDebug()` and `TSDebugSpecific()`. Using the value 3 will have less + of a negative impact on proxy throughput than using the value 1. + .. ts:cv:: CONFIG proxy.config.diags.debug.client_ip STRING NULL if :ts:cv:`proxy.config.diags.debug.enabled` is set to 2, this value is tested against the source IP of the incoming connection. If there is a match, all the diagnostic messages for that connection and the related outgoing connection will be logged. @@ -3243,7 +3247,7 @@ Diagnostic Logging Configuration ssl TLS termination and certificate processing ============ ===================================================== - |TS| plugins will typically log debug messages using the :c:func:`TSDebug` + |TS| plugins will typically log debug messages using the :c:func:`TSDbg` API, passing the plugin name as the debug tag. .. ts:cv:: CONFIG proxy.config.diags.debug.throttling_interval_msec INT 0 diff --git a/doc/developer-guide/api/functions/TSDebug.en.rst b/doc/developer-guide/api/functions/TSDebug.en.rst index f9cafdfc55e..a12551001bc 100644 --- a/doc/developer-guide/api/functions/TSDebug.en.rst +++ b/doc/developer-guide/api/functions/TSDebug.en.rst @@ -18,8 +18,8 @@ .. default-domain:: c -TSDebug -******* +TSDbg +***** Traffic Server Debugging APIs. @@ -37,7 +37,11 @@ Synopsis .. function:: void TSFatal(const char * format, ...) .. function:: void TSAlert(const char * format, ...) .. function:: void TSEmergency(const char * format, ...) +.. type:: TSDbgCtl +.. function:: void TSDbg(const TSDbgCtl * ctlptr, const char * format, ...) +.. function:: const TSDbgCtl * TSDbgCtlCreate(const char * tag) .. function:: void TSDebug(const char * tag, const char * format, ...) +.. function:: int TSIsDbgCtlSet(const TSDbgCtl * ctlptr) .. function:: int TSIsDebugTagSet(const char * tag) .. function:: void TSDebugSpecific(int debug_flag, const char * tag, const char * format, ...) .. function:: void TSHttpTxnDebugSet(TSHttpTxn txnp, int on) @@ -76,10 +80,19 @@ Traffic Server, Traffic Manager, AuTest, CI, and your log monitoring service/das trafficserver.out ================= -:func:`TSDebug` logs the debug message only if the given debug :arg:`tag` is enabled. +:func:`TSDbg` logs the debug message only if the given debug control pointed to by +:arg:`ctlptr` is enabled. It writes output to the Traffic Server debug log through stderr. + +:func:`TSDbgCtlCreate` creates a debug control, associated with the +debug :arg:`tag`, and returns a const pointer to it. + +:func:`TSIsDbgCtlSet` returns non-zero if the given debug control, pointed to by :arg:`ctlptr`, is +enabled. + +:func:`TSDebug` (deprecated) logs the debug message only if the given debug :arg:`tag` is enabled. It writes output to the Traffic Server debug log through stderr. -:func:`TSIsDebugTagSet` returns non-zero if the given debug :arg:`tag` is +:func:`TSIsDebugTagSet` (deprecated) returns non-zero if the given debug :arg:`tag` is enabled. In debug mode, :macro:`TSAssert` Traffic Server to prints the file diff --git a/doc/developer-guide/debugging/debug-tags.en.rst b/doc/developer-guide/debugging/debug-tags.en.rst index 7738acebfbc..9cd45392de1 100644 --- a/doc/developer-guide/debugging/debug-tags.en.rst +++ b/doc/developer-guide/debugging/debug-tags.en.rst @@ -22,16 +22,34 @@ Debug Tags ********** -Use the API -``void TSDebug (const char *tag, const char *format_str, ...)`` to add -traces in your plugin. In this API: +Use the API macro +``TSDbg(ctlptr, const char *format_str, ...)`` to add +traces in your plugin. In this macro: + +- ``ctlptr`` is the Traffic Server parameter that enables Traffic Server + to print out ``format_str``. It is returned by ``TSDbgCtlCreate()``. + +- ``...`` are variables for ``format_str`` in the standard ``printf`` + style. + +``void TSDbgCtlCreate (const char *tag)`` returns a (const) pointer to +``TSDbgCtl``. The ``TSDbgCtl`` control is enabled when debug output is +enabled globally by configuaration, and ``tag`` matches a configured +regular expression. + +The deprecated API +``void TSDebug (const char *tag, const char *format_str, ...)`` also +outputs traces. In this API: - ``tag`` is the Traffic Server parameter that enables Traffic Server - to print out *``format_str``* + to print out ``format_str`` -- ``...`` are variables for *``format_str``* in the standard ``printf`` +- ``...`` are variables for ``format_str`` in the standard ``printf`` style. +Use of ``TSDebug()`` causes trace output to have a more negative impact +on proxy throughput. + Run Traffic Server with the ``-Ttag`` option. For example, if the tag is ``my-plugin``, then the debug output goes to ``traffic.out.``\ See below: @@ -40,7 +58,7 @@ below: traffic_server -T"my-plugin" -Set the following variables in :file:`records.config` (in the Traffic Server +Sets the following variables in :file:`records.config` (in the Traffic Server ``config`` directory): :: @@ -48,13 +66,22 @@ Set the following variables in :file:`records.config` (in the Traffic Server CONFIG proxy.config.diags.debug.enabled INT 1 CONFIG proxy.config.diags.debug.tags STRING debug-tag-name +(Performance will be better if ``enabled`` is set to 3 rather than 1, but, +using 3, output from ``TSDebug()`` will not be enabled, only from ``TSDbg()``.) In this case, debug output goes to ``traffic.out``. Example: .. code-block:: c - TSDebug ("my-plugin", "Starting my-plugin at %d", the_time); + static TSDbgCtl const *my_dbg_ctl; // Non-local variable. + ... + my_dbg_ctl = TSDbgCtlCreate("my-plugin"); // In TSPluginInit() or TSRemapInit(). + ... + TSDbg(my_dbg_ctl, "Starting my-plugin at %d", the_time); + ... + TSDbg(my_dbg_ctl, "Later on in my-plugin"); + The statement ``"Starting my-plugin at