diff --git a/doc/admin-guide/files/records.yaml.en.rst b/doc/admin-guide/files/records.yaml.en.rst index 060a65193a4..c4c12c87b8f 100644 --- a/doc/admin-guide/files/records.yaml.en.rst +++ b/doc/admin-guide/files/records.yaml.en.rst @@ -3329,7 +3329,7 @@ Diagnostic Logging Configuration .. ts:cv:: CONFIG proxy.config.diags.show_location INT 1 Annotates diagnostic messages with the source code location. Set to 1 to enable - for Debug() messages only. Set to 2 to enable for all messages. + for Dbg() messages only. Set to 2 to enable for all messages. .. ts:cv:: CONFIG proxy.config.diags.debug.enabled INT 0 :reloadable: @@ -3338,10 +3338,6 @@ 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. @@ -3364,9 +3360,6 @@ Diagnostic Logging Configuration ssl TLS termination and certificate processing ============ ===================================================== - |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 :reloadable: :units: milliseconds diff --git a/doc/developer-guide/api/functions/TSAPI.en.rst b/doc/developer-guide/api/functions/TSAPI.en.rst index 799ae810856..d6b19c89e39 100644 --- a/doc/developer-guide/api/functions/TSAPI.en.rst +++ b/doc/developer-guide/api/functions/TSAPI.en.rst @@ -103,7 +103,7 @@ The Traffic Server API adheres to the following naming conventions: :data:`TS_MIME_FIELD_ACCEPT`. * The names of defined types are mixed-case. For example, :type:`TSHttpSsn` - and :func:`TSHttpTxn`. :func:`TSDebug` + and :func:`TSHttpTxn`. :func:`TSContCreate` * Function names are mixed-case. For example, :func:`TSUrlCreate` and :func:`TSContDestroy`. diff --git a/doc/developer-guide/api/functions/TSDebug.en.rst b/doc/developer-guide/api/functions/TSDebug.en.rst index 6be89c25900..460cc928b0e 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 -TSDbg -***** +Dbg +*** Traffic Server Debugging APIs. @@ -37,14 +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 TSDbgCtlDestroy(const TSDbgCtl * dbg_ctl) -.. 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, ...) +.. cpp:type:: DbgCtl +.. cpp:function:: void Dbg(DbgCtl &ctl, const char * format, ...) +.. cpp:function:: bool DbgCtl::on() +.. cpp:function:: void SpecificDbg(bool debug_flag, DbgCtl &ctl, const char * format, ...) +.. cpp:function:: void DbgPrint(DbgCtl &ctl, const char * format, ...) .. function:: void TSHttpTxnDebugSet(TSHttpTxn txnp, int on) .. function:: void TSHttpSsnDebugSet(TSHttpSsn ssn, int on) .. function:: int TSHttpTxnDebugGet(TSHttpTxn txnp) @@ -81,22 +78,14 @@ Traffic Server, AuTest, CI, and your log monitoring service/dashboard (e.g. Splu trafficserver.out ================= -: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:`TSDbgCtlDestroy` destroys a debug control, pointed to by :arg:`dbg_ctl`. - -:func:`TSIsDbgCtlSet` returns non-zero if the given debug control, pointed to by :arg:`ctlptr`, is +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. -: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. +cpp:func:`Dbg` logs the debug message only if the given debug control referred to by +:arg:`ctl` is enabled. It writes output to the Traffic Server debug log through stderr. -:func:`TSIsDebugTagSet` (deprecated) returns non-zero if the given debug :arg:`tag` is -enabled. +``ctl.on()`` (where ``ctl`` is an instance of ``DbgCtl``) returns true if ``ctl`` is on. In debug mode, :macro:`TSAssert` Traffic Server to prints the file name, line number and expression, and then aborts. In release mode, @@ -104,33 +93,44 @@ the expression is not removed but the effects of printing an error message and aborting are. :macro:`TSReleaseAssert` prints an error message and aborts in both release and debug mode. -:func:`TSDebugSpecific` emits a debug line even if the debug :arg:`tag` +cpp:func:`SpecificDbg` emits a debug line even if the debug :arg:`tag` is turned off, as long as debug flag is enabled. This can be used in conjunction with :func:`TSHttpTxnDebugSet`, :func:`TSHttpSsnDebugSet`, :func:`TSHttpTxnDebugGet` and :func:`TSHttpSsnDebugGet` to enable debugging on specific session and transaction objects. +cpp:func:`DbgPrint` emits a debug line even if the debug :arg:`tag` +is turned off. + :func:`TSHttpServerStateNameLookup`, :func:`TSHttpHookNameLookup` and :func:`TSHttpEventNameLookup` converts the respective internal state to a -string representation. This can be useful in debugging (:func:`TSDebug`), +string representation. This can be useful in debugging (cpp:func:`Dbg`), logging and other types notifications. +(Note that cpp:type:`DbgCtl`, cpp:func:`Dbg`, cpp:func:`SpecificDbg` and cpp:func:`DbgPrint` +are not in the ``tsapi::c`` namespace.) + +(For an example of how to write a plugin with debug tracing, that can be +compiled with both |TS| Version 10 and older versions of ATS, see ``redirect_1``.) + Examples ======== -This example uses :func:`TSDebugSpecific` to log a message when a specific +This example uses cpp:func:`SpecificDbg` to log a message when a specific debugging flag is enabled:: #include + DbgCtl dbg_ctl{PLUGIN_NAME}; + // Produce information about a hook receiving an event - TSDebug(PLUGIN_NAME, "Entering hook=%s, event=%s", - TSHttpHookNameLookup(hook), TSHttpEventNameLookup(event)); + Dbg(dbg_ctl, "Entering hook=%s, event=%s", + TSHttpHookNameLookup(hook), TSHttpEventNameLookup(event)); - // Emit debug message if "tag" is enabled or the txn debug + // Emit debug message if "dbg_ctl" is enabled or the txn debug // flag is set. - TSDebugSpecifc(TSHttpTxnDebugGet(txn), "tag" , - "Hello World from transaction %p", txn); + SpecificDbg(TSHttpTxnDebugGet(txn), dbg_ctl , + "Hello World from transaction %p", txn); See Also ======== diff --git a/doc/developer-guide/api/functions/TSTrafficServerVersionGet.en.rst b/doc/developer-guide/api/functions/TSTrafficServerVersionGet.en.rst index 1d98ab992fd..2e6d995ada0 100644 --- a/doc/developer-guide/api/functions/TSTrafficServerVersionGet.en.rst +++ b/doc/developer-guide/api/functions/TSTrafficServerVersionGet.en.rst @@ -55,6 +55,8 @@ Example #define PLUGIN_NAME "hello_world" + DbgCtl dbg_ctl{PLUGIN_NAME}; + int check_ts_version() { @@ -98,7 +100,7 @@ Example return; } - TSDebug(PLUGIN_NAME, "Hello World!"); + Dbg(dbg_ctl, "Hello World!"); } See Also diff --git a/doc/developer-guide/debugging/debug-tags.en.rst b/doc/developer-guide/debugging/debug-tags.en.rst index 9fb73b7def2..9dc203f6526 100644 --- a/doc/developer-guide/debugging/debug-tags.en.rst +++ b/doc/developer-guide/debugging/debug-tags.en.rst @@ -23,36 +23,19 @@ Debug Tags ********** Use the API macro -``TSDbg(ctlptr, const char *format_str, ...)`` to add +``Dbg(ctl, 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()``. +- ``ctl`` is the Traffic Server parameter that enables Traffic Server + to print out ``format_str``. It is an instance of the class ``DbgCtl``. - ``...`` are variables for ``format_str`` in the standard ``printf`` style. -``TSDbgCtlCreate (const char *tag)`` returns a (const) pointer to -``TSDbgCtl``. The ``TSDbgCtl`` control is enabled when debug output is +The ``DbgCtl`` control is enabled when debug output is enabled globally by configuration, and ``tag`` matches a configured regular expression. -``TSDbgCtlDestroy (TSDbgCtl const *dbg_ctl)`` destroys a debug control -created by ``TSDbgCtlCreast()``. - -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`` - -- ``...`` 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: @@ -73,25 +56,8 @@ Sets the following variables in :file:`records.yaml` (in the Traffic Server tags: 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 - - 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"); - ... - TSDbgCtlDestroy(my_dbg_ctl); - - The statement ``"Starting my-plugin at