From b0a862aaa478696c93cb630b971986a795a6496a Mon Sep 17 00:00:00 2001 From: Walt Karas Date: Wed, 30 Aug 2023 23:35:55 +0000 Subject: [PATCH 1/4] Remove TSDebug() and TSIsDebugTagSet() TS API functions. Replace with Dbg() and DbgCtl::on(). This required extensive changes to the ESI plugin unit tests. Doc changes were also necessary. The redirect_1 example plugin is changed to illustrate how to implement debug trace output in a plugin that can compile and run with either these ATS10 changes or for older versions of ATS. --- doc/admin-guide/files/records.yaml.en.rst | 9 +- .../api/functions/TSAPI.en.rst | 2 +- .../api/functions/TSDebug.en.rst | 62 ++-- .../TSTrafficServerVersionGet.en.rst | 4 +- .../debugging/debug-tags.en.rst | 56 +--- .../jsonrpc-handler-development.en.rst | 8 +- .../example-plugins/denylist/index.en.rst | 7 +- .../http-alternate-selection.en.rst | 10 +- .../http-transactions.en.rst | 7 +- .../plugins/plugin-interfaces.en.rst | 9 +- doc/release-notes/whats-new.en.rst | 2 + .../plugins/c-api/cert_update/cert_update.cc | 19 +- .../client_context_dump.cc | 11 +- .../plugins/c-api/denylist_1/denylist_1.cc | 9 +- .../c-api/disable_http2/disable_http2.cc | 11 +- example/plugins/c-api/file_1/file_1.cc | 7 +- example/plugins/c-api/hello/hello.cc | 7 +- example/plugins/c-api/intercept/intercept.cc | 6 +- .../lifecycle_plugin/lifecycle_plugin.cc | 19 +- .../c-api/null_transform/null_transform.cc | 35 ++- .../c-api/output_header/output_header.cc | 13 +- example/plugins/c-api/passthru/passthru.cc | 13 +- example/plugins/c-api/protocol/Protocol.cc | 13 +- example/plugins/c-api/protocol/Protocol.h | 6 + example/plugins/c-api/protocol/TxnSM.cc | 84 +++--- .../c-api/protocol_stack/protocol_stack.cc | 11 +- .../plugins/c-api/query_remap/query_remap.cc | 27 +- .../plugins/c-api/redirect_1/redirect_1.cc | 40 ++- example/plugins/c-api/remap/remap.cc | 49 ++-- .../remap_header_add/remap_header_add.cc | 19 +- .../c-api/request_buffer/request_buffer.cc | 15 +- .../response_header_1/response_header_1.cc | 27 +- .../plugins/c-api/secure_link/secure_link.cc | 19 +- .../server_transform/server_transform.cc | 15 +- .../c-api/session_hooks/session_hooks.cc | 11 +- .../c-api/ssl_preaccept/ssl_preaccept.cc | 10 +- example/plugins/c-api/ssl_sni/ssl_sni.cc | 12 +- .../ssl_sni_allowlist/ssl_sni_allowlist.cc | 6 +- example/plugins/c-api/statistic/statistic.cc | 7 +- example/plugins/c-api/thread_pool/psi.cc | 33 ++- .../c-api/txn_data_sink/txn_data_sink.cc | 22 +- .../plugins/c-api/vconn_args/vconn_args.cc | 17 +- .../plugins/c-api/verify_cert/verify_cert.cc | 8 +- example/plugins/c-api/version/version.cc | 7 +- include/ts/DbgCtl.h | 11 + include/ts/ts.h | 25 -- include/tscore/Diags.h | 12 - include/tscore/DiagsTypes.h | 13 - include/tscpp/api/Logger.h | 23 +- plugins/authproxy/utils.cc | 2 + plugins/authproxy/utils.h | 4 +- plugins/background_fetch/background_fetch.cc | 46 +-- plugins/background_fetch/configs.cc | 22 +- plugins/background_fetch/configs.h | 2 + plugins/background_fetch/headers.cc | 4 +- plugins/background_fetch/rules.cc | 20 +- plugins/cache_promote/cache_promote.cc | 19 +- plugins/cache_promote/chance_policy.h | 2 +- plugins/cache_promote/configs.cc | 6 +- plugins/cache_promote/lru_policy.cc | 20 +- plugins/cache_promote/lru_policy.h | 8 +- plugins/cache_promote/policy.cc | 8 +- plugins/cache_promote/policy.h | 6 +- plugins/cache_promote/policy_manager.cc | 10 +- plugins/cache_promote/policy_manager.h | 4 +- .../cache_range_requests.cc | 6 +- plugins/cachekey/common.cc | 4 + plugins/cachekey/common.h | 16 +- plugins/certifier/certifier.cc | 56 ++-- plugins/compress/debug_macros.h | 41 +-- plugins/conf_remap/conf_remap.cc | 19 +- plugins/escalate/escalate.cc | 19 +- plugins/esi/combo_handler.cc | 23 +- plugins/esi/common/ComponentBase.h | 17 +- plugins/esi/common/DocNode.cc | 14 +- plugins/esi/common/Utils.cc | 29 +- plugins/esi/common/Utils.h | 6 - plugins/esi/common/gzip.cc | 20 +- plugins/esi/esi.cc | 265 +++++++++--------- plugins/esi/fetcher/HttpDataFetcherImpl.cc | 25 +- plugins/esi/fetcher/HttpDataFetcherImpl.h | 2 +- plugins/esi/lib/EsiGunzip.cc | 11 +- plugins/esi/lib/EsiGunzip.h | 2 +- plugins/esi/lib/EsiGzip.cc | 11 +- plugins/esi/lib/EsiGzip.h | 2 +- plugins/esi/lib/EsiParser.cc | 137 +++++---- plugins/esi/lib/EsiParser.h | 2 +- plugins/esi/lib/EsiProcessor.cc | 180 ++++++------ plugins/esi/lib/EsiProcessor.h | 3 +- plugins/esi/lib/Expression.cc | 50 ++-- plugins/esi/lib/Expression.h | 2 +- plugins/esi/lib/HandlerManager.cc | 10 +- plugins/esi/lib/HandlerManager.h | 2 +- plugins/esi/lib/Variables.cc | 67 +++-- plugins/esi/lib/Variables.h | 9 +- plugins/esi/serverIntercept.cc | 46 +-- plugins/esi/test/docnode_test.cc | 7 +- plugins/esi/test/gzip_test.cc | 3 - plugins/esi/test/parser_test.cc | 4 +- plugins/esi/test/print_funcs.cc | 75 ++++- plugins/esi/test/print_funcs.h | 28 -- plugins/esi/test/processor_test.cc | 17 +- plugins/esi/test/utils_test.cc | 3 - plugins/esi/test/vars_test.cc | 36 +-- plugins/experimental/access_control/common.cc | 6 + plugins/experimental/access_control/common.h | 21 +- .../experimental/access_control/headers.cc | 2 +- .../cache_fill/background_fetch.cc | 29 +- .../cache_fill/background_fetch.h | 8 +- plugins/experimental/cache_fill/cache_fill.cc | 14 +- .../cache_key_genid/cache_key_genid.cc | 12 +- .../cert_reporting_tool.cc | 11 +- .../experimental/cookie_remap/cookie_remap.cc | 201 ++++++------- .../custom_redirect/custom_redirect.cc | 6 +- .../experimental/fastcgi/src/ats_fastcgi.cc | 6 +- .../fastcgi/src/ats_fcgi_client.cc | 17 +- .../fastcgi/src/connection_pool.cc | 12 +- .../experimental/fastcgi/src/fcgi_config.cc | 28 +- .../experimental/fastcgi/src/fcgi_config.h | 2 +- plugins/experimental/fastcgi/src/server.cc | 51 ++-- .../fastcgi/src/server_connection.cc | 13 +- .../fastcgi/src/server_intercept.cc | 6 +- .../fastcgi/src/server_intercept.h | 2 +- plugins/experimental/fq_pacing/fq_pacing.cc | 14 +- plugins/experimental/geoip_acl/acl.cc | 29 +- plugins/experimental/geoip_acl/acl.h | 6 + plugins/experimental/geoip_acl/geoip_acl.cc | 8 +- .../experimental/header_freq/header_freq.cc | 16 +- plugins/experimental/hook-trace/hook-trace.cc | 44 +-- plugins/experimental/http_stats/http_stats.cc | 10 +- plugins/experimental/icap/icap_plugin.cc | 19 +- plugins/experimental/inliner/ats-inliner.cc | 8 +- plugins/experimental/inliner/cache-handler.h | 20 +- plugins/experimental/inliner/cache.cc | 10 +- plugins/experimental/inliner/fetcher.cc | 2 +- plugins/experimental/inliner/fetcher.h | 26 +- .../experimental/inliner/inliner-handler.cc | 1 - plugins/experimental/inliner/ts.cc | 19 +- plugins/experimental/inliner/ts.h | 2 - plugins/experimental/magick/magick.cc | 28 +- .../experimental/maxmind_acl/maxmind_acl.cc | 8 +- plugins/experimental/maxmind_acl/mmdb.cc | 149 +++++----- plugins/experimental/maxmind_acl/mmdb.h | 6 + .../memory_profile/memory_profile.cc | 19 +- .../experimental/money_trace/money_trace.cc | 5 + .../experimental/money_trace/money_trace.h | 12 +- .../experimental/otel_tracer/otel_tracer.cc | 18 +- plugins/experimental/rate_limit/limiter.h | 6 +- plugins/experimental/rate_limit/rate_limit.cc | 14 +- .../experimental/rate_limit/sni_limiter.cc | 26 +- .../experimental/rate_limit/sni_selector.cc | 8 +- .../experimental/rate_limit/txn_limiter.cc | 6 +- plugins/experimental/rate_limit/utilities.cc | 11 +- plugins/experimental/rate_limit/utilities.h | 6 + .../redo_cache_lookup/redo_cache_lookup.cc | 16 +- .../ssl_session_reuse/src/ats_ssl_plugin.cc | 2 +- .../ssl_session_reuse/src/common.cc | 29 +- .../ssl_session_reuse/src/common.h | 6 + .../ssl_session_reuse/src/config.cc | 2 +- .../ssl_session_reuse/src/openssl_utils.cc | 10 +- .../ssl_session_reuse/src/publish.cc | 61 ++-- .../ssl_session_reuse/src/session_process.cc | 12 +- .../ssl_session_reuse/src/ssl_init.cc | 11 +- .../ssl_session_reuse/src/ssl_key_utils.cc | 24 +- .../ssl_session_reuse/src/subscriber.cc | 38 +-- plugins/experimental/sslheaders/sslheaders.cc | 5 + plugins/experimental/sslheaders/sslheaders.h | 7 +- .../sslheaders/unit_tests/test_sslheaders.cc | 3 +- .../experimental/stek_share/state_machine.h | 10 +- plugins/experimental/stek_share/stek_share.cc | 98 +++---- .../stream_editor/stream_editor.cc | 18 +- .../experimental/system_stats/system_stats.cc | 19 +- plugins/experimental/tls_bridge/tls_bridge.cc | 32 ++- plugins/experimental/uri_signing/common.cc | 7 + plugins/experimental/uri_signing/common.h | 11 +- .../experimental/uri_signing/uri_signing.cc | 4 +- plugins/experimental/url_sig/url_sig.cc | 88 +++--- plugins/experimental/wasm/ats_context.cc | 62 ++-- plugins/experimental/wasm/ats_context.h | 2 + plugins/experimental/wasm/ats_wasm.cc | 6 +- plugins/experimental/wasm/wasm_main.cc | 88 +++--- plugins/generator/generator.cc | 6 +- plugins/header_rewrite/condition.h | 4 +- plugins/header_rewrite/conditions.cc | 134 ++++----- plugins/header_rewrite/conditions.h | 46 +-- .../header_rewrite/conditions_geo_geoip.cc | 10 +- .../header_rewrite/conditions_geo_maxmind.cc | 36 +-- plugins/header_rewrite/header_rewrite.cc | 46 +-- plugins/header_rewrite/lulu.h | 7 + plugins/header_rewrite/matcher.h | 32 +-- plugins/header_rewrite/operator.h | 6 +- plugins/header_rewrite/operators.cc | 154 +++++----- plugins/header_rewrite/operators.h | 42 +-- plugins/header_rewrite/resources.cc | 32 +-- plugins/header_rewrite/resources.h | 4 +- plugins/header_rewrite/ruleset.cc | 8 +- plugins/header_rewrite/ruleset.h | 4 +- plugins/header_rewrite/statement.h | 4 +- plugins/header_rewrite/value.cc | 2 +- plugins/header_rewrite/value.h | 2 +- plugins/healthchecks/healthchecks.cc | 28 +- plugins/ja3_fingerprint/ja3_fingerprint.cc | 39 +-- plugins/libloader/libloader.cc | 4 +- plugins/lua/ts_lua.cc | 70 ++--- plugins/lua/ts_lua_common.h | 6 + plugins/lua/ts_lua_crypto.cc | 6 +- plugins/lua/ts_lua_http.cc | 4 +- plugins/lua/ts_lua_http_config.cc | 20 +- plugins/lua/ts_lua_misc.cc | 17 +- plugins/lua/ts_lua_string.cc | 4 +- plugins/lua/ts_lua_transform.cc | 14 +- plugins/lua/ts_lua_util.cc | 31 +- plugins/multiplexer/ats-multiplexer.cc | 8 +- plugins/multiplexer/dispatch.cc | 18 +- plugins/multiplexer/fetcher.cc | 7 +- plugins/multiplexer/fetcher.h | 26 +- plugins/prefetch/common.cc | 7 + plugins/prefetch/common.h | 20 +- plugins/prefetch/configs.cc | 2 + plugins/prefetch/fetch.cc | 9 +- plugins/prefetch/headers.cc | 2 +- plugins/regex_remap/regex_remap.cc | 40 +-- plugins/regex_revalidate/regex_revalidate.cc | 109 +++---- plugins/remap_purge/remap_purge.cc | 22 +- plugins/remap_stats/remap_stats.cc | 24 +- plugins/s3_auth/s3_auth.cc | 69 ++--- .../server_push_preload.cc | 16 +- plugins/slice/client.cc | 2 +- plugins/slice/prefetch.cc | 2 +- plugins/slice/server.cc | 6 +- plugins/slice/slice.cc | 7 +- plugins/slice/slice.h | 10 +- plugins/slice/util.cc | 2 +- plugins/statichit/statichit.cc | 6 +- plugins/stats_over_http/stats_over_http.cc | 64 +++-- plugins/tcpinfo/tcpinfo.cc | 34 +-- plugins/traffic_dump/global_variables.h | 3 + plugins/traffic_dump/session_data.cc | 46 +-- plugins/traffic_dump/traffic_dump.cc | 16 +- plugins/traffic_dump/transaction_data.cc | 28 +- plugins/webp_transform/ImageTransform.cc | 2 +- plugins/xdebug/xdebug.cc | 31 +- plugins/xdebug/xdebug_headers.cc | 13 +- plugins/xdebug/xdebug_transforms.cc | 12 +- src/api/InkAPI.cc | 34 --- src/api/InkAPITest.cc | 173 ++++++------ src/tscore/Diags.cc | 4 +- src/tscpp/api/Logger.cc | 5 + src/tscpp/api/logging_internal.h | 7 +- .../plugins/session_id_verify.cc | 8 +- .../plugins/jsonrpc_plugin_handler_test.cc | 32 ++- .../tsapi/test_TSHttpTxnServerAddrSet.cc | 10 +- .../gold_tests/pluginTest/tsapi/test_tsapi.cc | 6 +- tests/tools/plugins/cert_update.cc | 19 +- tests/tools/plugins/cont_schedule.cc | 69 ++--- tests/tools/plugins/continuations_verify.cc | 14 +- tests/tools/plugins/custom204plugin.cc | 31 +- tests/tools/plugins/emergency_shutdown.cc | 3 +- tests/tools/plugins/fatal_shutdown.cc | 3 +- tests/tools/plugins/hook_add_plugin.cc | 21 +- tests/tools/plugins/ssl_client_verify_test.cc | 11 +- tests/tools/plugins/ssl_hook_test.cc | 35 +-- tests/tools/plugins/ssl_secret_load_test.cc | 21 +- tests/tools/plugins/ssl_verify_test.cc | 16 +- tests/tools/plugins/ssntxnorder_verify.cc | 57 ++-- tests/tools/plugins/test_hooks.cc | 24 +- 266 files changed, 3229 insertions(+), 2853 deletions(-) delete mode 100644 plugins/esi/test/print_funcs.h 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