Reduce overhead incurred by enabling debug output.

doc/admin-guide/files/records.config.en.rst

@@ -3327,6 +3327,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.
@@ -3349,7 +3353,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

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

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,21 +58,30 @@ 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):
 
 ::
 
        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 <time>"`` appears whenever you
 run Traffic Server with the ``my-plugin`` tag:
@@ -63,6 +90,16 @@ 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:
+
+.. code-block:: cpp
+
+       static auto my_dbg_ctl = TSDbgCtlCreate("my-plugin"); // Non-local variable.
+       ...
+       TSDbg(my_dbg_ctl, "Starting my-plugin at %d", the_time);
+       ...
+       TSDbg(my_dbg_ctl, "Later on in my-plugin");
+
 Other Useful Internal Debug Tags
 ================================
 
@@ -71,7 +108,7 @@ internal debugging purposes. These can also be used to follow Traffic
 Server behavior for testing and analysis.
 
 The debug tag setting (``-T`` and ``proxy.config.diags.debug.tags``) is a
-anchored regular expression against which the tag for a specific debug
+anchored regular expression (PCRE) against which the tag for a specific debug
 message is matched. This means the value "http" matches debug messages
 with the tag "http" but also "http\_seq" and "http\_trans". If you want
 multiple tags then use a pipe symbol to separate the tags. For example

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

@@ -122,14 +122,15 @@ The thread functions are listed below:
 Debugging Functions
 ===================
 
--  :c:func:`TSDebug`
-   prints out a formatted statement if you are running Traffic Server in
-   debug mode.
-
--  :c:func:`TSIsDebugTagSet`
-   checks to see if a debug tag is set. If the debug tag is set, then
-   Traffic Server prints out all debug statements associated with the
-   tag.
+-  :c:func:`TSDbg`
+   (replaces deprecated :c:func:`TSDebug`) prints out a formatted
+   statement if you are running Traffic Server in debug mode.
+
+-  :c:func:`TSIsDbgCtlSet`
+   (replaces deprecated :c:func:`TSIsDebugTagSet`)
+   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.
 
 -  :c:func:`TSError`
    prints error messages to Traffic Server's error log

include/ts/apidefs.h.in

@@ -1070,6 +1070,11 @@ typedef struct TSHttpConnectOptions_s {
   TSIOBufferWaterMark buffer_water_mark;
 } TSHttpConnectOptions;
 
+typedef struct TSDbgCtl_s {
+  char volatile on; // Flag
+  char const *tag;
+} TSDbgCtl;
+
 /* --------------------------------------------------------------------------
    Init */
 

include/ts/ts.h

@@ -2190,11 +2190,40 @@ tsapi void TSDebug(const char *tag, const char *format_str, ...) TS_PRINTFLIKE(2
     @param ... Format arguments.
  */
 tsapi void TSDebugSpecific(int debug_flag, const char *tag, const char *format_str, ...) TS_PRINTFLIKE(3, 4);
-extern int diags_on_for_plugins;
+extern int diags_on_for_plugins; /* Do not use directly. */
 #define TSDEBUG             \
   if (diags_on_for_plugins) \
   TSDebug
 
+extern char ts_new_debug_on_flag_; /* Do not use directly. */
+
+#define TSIsDbgCtlSet(ctlp__) (ts_new_debug_on_flag_ && ctlp__->on)
+
+/**
+    Output a debug line if the debug output control is turned on.
+
+    @param ctlp pointer to TSDbgCtl, returned by TSDbgCtlCreate().
+    @param ...  Format string and (optional) arguments.
+ */
+#define TSDbg(ctlp, ...)              \
+  do {                                \
+    if (TSIsDbgCtlSet(ctlp)) {        \
+      _TSDbg(ctlp->tag, __VA_ARGS__); \
+    }                                 \
+  } while (0)
+
+/**
+    Return a pointer for use with TSDbg().  For good performance,
+    this should be called in TSPluginInit() or TSRemapInit(), or in
+    static initialization in C++ (with the result stored in a
+    static pointer).
+
+    @param tag Debug tag for the control.
+ */
+tsapi TSDbgCtl const *TSDbgCtlCreate(char const *tag);
+
+void _TSDbg(const char *tag, const char *format_str, ...) TS_PRINTFLIKE(2, 3); /* Not for direct use. */
+
 /* --------------------------------------------------------------------------
    logging api */
 

include/tscore/DbgCtl.h

@@ -0,0 +1,56 @@
+/** @file
+
+  DbgCtl class header file.
+
+  @section license License
+
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+ */
+
+#pragma once
+
+#include <ts/ts.h>
+
+// For use with TSDbg().
+//
+class DbgCtl
+{
+public:
+  // Tag is a debug tag.  Debug output associated with this control will be output when debug output
+  // is enabled globally, and the tag matches the configured debug tag regular expression.
+  //
+  DbgCtl(char const *tag) : _ptr(_get_ptr(tag)) {}
+
+  TSDbgCtl const *
+  ptr() const
+  {
+    return _ptr;
+  }
+
+  // Call this when the compiled regex to enable tags may have changed.
+  //
+  static void update();
+
+private:
+  TSDbgCtl const *const _ptr;
+
+  static const TSDbgCtl *_get_ptr(char const *tag);
+
+  class _RegistryAccessor;
+
+  friend TSDbgCtl const *TSDbgCtlCreate(char const *tag);
+};