Remove TSDebug() and TSIsDebugTagSet() TS API functions.

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

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`.

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,56 +78,59 @@ 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,
 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 <ts/ts.h>
 
+    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
 ========

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

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,44 +56,27 @@ 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 <time>"`` appears whenever you
 run Traffic Server with the ``my-plugin`` tag:
 
 ::
 
        traffic_server -T"my-plugin"
 
-If your plugin is a C++ plugin, the above example can be written as:
+Example:
 
 .. code-block:: cpp
 
-       #include <tscpp/api/Cleanup.h>
-       ...
-       static TSDbgCtlUniqPtr my_dbg_ctl_guard{TSDbgCtlCreate("my-plugin")}; // Non-local variable.
-       TSDbgCtl const * const my_dbg_ctl{my_dbg_ctl_guard.get()}; // Non-local variable.
+       namespace
+       {
+       DbgCtl my_dbg_ctl{"my-plugin"}; // Non-local variable.
+       }
        ...
-       TSDbg(my_dbg_ctl, "Starting my-plugin at %d", the_time);
+       Dbg(my_dbg_ctl, "Starting my-plugin at %d", the_time);
        ...
-       TSDbg(my_dbg_ctl, "Later on in my-plugin");
+       Dbg(my_dbg_ctl, "Later on in my-plugin");
 
 Other Useful Internal Debug Tags
 ================================

doc/developer-guide/jsonrpc/jsonrpc-handler-development.en.rst

@@ -237,9 +237,9 @@ RPC method registration and implementation examples
             }
 
             if (TSRPCRegisterMethodHandler("join_strings", my_join_string_handler, rpcRegistrationInfo) == TS_ERROR) {
-                TSDebug(PLUGIN_NAME, "%s failed to register", rpcCallName.c_str());
+                Dbg(dbg_ctl, "%s failed to register", rpcCallName.c_str());
             } else {
-                TSDebug(PLUGIN_NAME, "%s successfully registered", rpcCallName.c_str());
+                Dbg(dbg_ctl, "%s successfully registered", rpcCallName.c_str());
             }
         }
 
@@ -292,9 +292,9 @@ RPC method registration and implementation examples
             }
 
             if (TSRPCRegisterMethodHandler("merge_yaml_file", merge_yaml_file, rpcRegistrationInfo) == TS_ERROR) {
-                TSDebug(PLUGIN_NAME, "%s failed to register", rpcCallName.c_str());
+                Dbg(dbg_ctl, "%s failed to register", rpcCallName.c_str());
             } else {
-                TSDebug(PLUGIN_NAME, "%s successfully registered", rpcCallName.c_str());
+                Dbg(dbg_ctl, "%s successfully registered", rpcCallName.c_str());
             }
         }
 

doc/developer-guide/plugins/example-plugins/denylist/index.en.rst

@@ -74,6 +74,11 @@ that might be sent to it:
 
 .. code-block:: c
 
+   namespace
+   {
+   DbgCtl dbg_ctl{"denylist_plugin"};
+   }
+
    static int
    denylist_plugin (TSCont contp, TSEvent event, void *edata)
    {
@@ -86,7 +91,7 @@ that might be sent to it:
             handle_response (txnp);
             return 0;
          default:
-            TSDebug ("denylist_plugin", "This event was unexpected: %d", );
+            Dbg (dbg_ctl, "This event was unexpected: %d", int(event) );
             break;
       }
       return 0;

doc/developer-guide/plugins/hooks-and-transactions/http-alternate-selection.en.rst

@@ -89,8 +89,8 @@ The sample code below shows how to call the alternate APIs.
       if (accept_transform_field) {
          TSMimeHdrFieldValueStringGet(client_req_buf, client_req_hdr,
             accept_transform_field, 0, &accept_transform_value, &accept_transform_len);
-         TSDebug(DBG_TAG, "Accept-Transform = |%s|",
-            accept_transform_value);
+         Dbg(dbg_ctl, "Accept-Transform = |%s|",
+             accept_transform_value);
       }
 
       /* get the Content-Transform field value from cached server response */
@@ -99,8 +99,8 @@ The sample code below shows how to call the alternate APIs.
       if (content_transform_field) {
          TSMimeHdrFieldValueStringGet(cache_resp_buf, cache_resp_hdr,
             content_transform_field, 0, &content_transform_value, &content_transform_len);
-         TSDebug(DBG_TAG, "Content-Transform = |%s|",
-            content_transform_value);
+         Dbg(dbg_ctl, "Content-Transform = |%s|",
+             content_transform_value);
       }
 
       /* compute quality */
@@ -118,7 +118,7 @@ The sample code below shows how to call the alternate APIs.
          quality = content_plugin ? 0.0 : 0.5;
       }
 
-      TSDebug(DBG_TAG, "Setting quality to %3.1f", quality);
+      Dbg(dbg_ctl, "Setting quality to %3.1f", quality);
 
       /* set quality for this alternate */
       TSHttpAltInfoQualitySet(infop, quality);

doc/developer-guide/plugins/hooks-and-transactions/http-transactions.en.rst

@@ -49,7 +49,10 @@ transaction and associate data to the transaction.
 
     #include <ts/ts.h>
 
-    char const DBG_TAG[] = "txn";
+    namespace
+    {
+    DbgCtl dbg_ctl{"txn"};
+    }
 
     /* Structure to be associated to txns */
     struct TxnData {
@@ -86,7 +89,7 @@ transaction and associate data to the transaction.
 
        case TS_EVENT_HTTP_TXN_CLOSE:
           /* Print txn data values */
-          TSDebug(DBG_TAG, "Txn data i=%d f=%f s=%s", txn_data->i, txn_data->f, txn_data->s);
+          Dbg(dbg_ctl, "Txn data i=%d f=%f s=%s", txn_data->i, txn_data->f, txn_data->s);
 
           /* Then destroy the txn cont and its data */
           delete txn_data;

doc/developer-guide/plugins/plugin-interfaces.en.rst

@@ -122,12 +122,11 @@ The thread functions are listed below:
 Debugging Functions
 ===================
 
--  :c:func:`TSDbg`
-   (replaces deprecated :c:func:`TSDebug`) prints out a formatted
-   statement if you are running Traffic Server in debug mode.
+-  :cpp:func:`Dbg`
+   prints out a formatted statement if you are
+   running Traffic Server in debug mode.
 
--  :c:func:`TSIsDbgCtlSet`
-   (replaces deprecated :c:func:`TSIsDebugTagSet`)
+-  :cpp:func:`DbgCtl::on`
    checks to see if a debug control (associated with a debug tag) is
    set. If the debug tag is set, then Traffic Server prints out all
    debug statements associated with the control.

doc/release-notes/whats-new.en.rst

@@ -52,3 +52,5 @@ Switch to C++17
 
 Plugins are now required to be compiled as C++ code, rather than straight C.
 The API is tested with C++17, so code compatible with this version is preferred.
+``TSDebug`` and related functions are removed.  Debug tracing should now be done
+using cpp:func:`Dbg` and related functions, as in |TS| core code.