From 381c3c417b8e41c43fd4d420a6d9d3f479c28588 Mon Sep 17 00:00:00 2001 From: Michael Erickson Date: Wed, 18 May 2022 12:26:34 -0700 Subject: [PATCH] docs: clarify descriptions for tracing cluster settings The descriptions for sql.trace.txn.enable_threshold and sql.trace.stmt.enable_threshold suggested that tracing was only enabled for transactions and statements longer than the threshold duration. This is not true, however: tracing is enabled for everything, and only _logged_ for transactions and statements longer than the threshold duration. Make this clear in the descriptions. Also make the description for sql.trace.session_eventlog.enabled a "single" sentence to match the style of other descriptions. Release note: None --- .../settings/settings-for-tenants.txt | 6 ++--- docs/generated/settings/settings.html | 6 ++--- pkg/sql/exec_util.go | 22 +++++++++++-------- 3 files changed, 19 insertions(+), 15 deletions(-) diff --git a/docs/generated/settings/settings-for-tenants.txt b/docs/generated/settings/settings-for-tenants.txt index 224523e98256..f80571cb0ee0 100644 --- a/docs/generated/settings/settings-for-tenants.txt +++ b/docs/generated/settings/settings-for-tenants.txt @@ -265,9 +265,9 @@ sql.telemetry.query_sampling.enabled boolean false when set to true, executed qu sql.temp_object_cleaner.cleanup_interval duration 30m0s how often to clean up orphaned temporary objects sql.temp_object_cleaner.wait_interval duration 30m0s how long after creation a temporary object will be cleaned up sql.trace.log_statement_execute boolean false set to true to enable logging of executed statements -sql.trace.session_eventlog.enabled boolean false set to true to enable session tracing. Note that enabling this may have a non-trivial negative performance impact. -sql.trace.stmt.enable_threshold duration 0s duration beyond which all statements are traced (set to 0 to disable). This applies to individual statements within a transaction and is therefore finer-grained than sql.trace.txn.enable_threshold. -sql.trace.txn.enable_threshold duration 0s duration beyond which all transactions are traced (set to 0 to disable). This setting is coarser grained thansql.trace.stmt.enable_threshold because it applies to all statements within a transaction as well as client communication (e.g. retries). +sql.trace.session_eventlog.enabled boolean false set to true to enable session tracing; note that enabling this may have a negative performance impact +sql.trace.stmt.enable_threshold duration 0s enables tracing on all statements; statements executing for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting applies to individual statements within a transaction and is therefore finer-grained than sql.trace.txn.enable_threshold +sql.trace.txn.enable_threshold duration 0s enables tracing on all transactions; transactions open for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting is coarser-grained than sql.trace.stmt.enable_threshold because it applies to all statements within a transaction as well as client communication (e.g. retries) sql.ttl.default_delete_batch_size integer 100 default amount of rows to delete in a single query during a TTL job sql.ttl.default_delete_rate_limit integer 0 default delete rate limit for all TTL jobs. Use 0 to signify no rate limit. sql.ttl.default_range_concurrency integer 1 default amount of ranges to process at once during a TTL delete diff --git a/docs/generated/settings/settings.html b/docs/generated/settings/settings.html index e957ab767320..22bcdcdc5f2a 100644 --- a/docs/generated/settings/settings.html +++ b/docs/generated/settings/settings.html @@ -196,9 +196,9 @@ sql.temp_object_cleaner.cleanup_intervalduration30m0show often to clean up orphaned temporary objects sql.temp_object_cleaner.wait_intervalduration30m0show long after creation a temporary object will be cleaned up sql.trace.log_statement_executebooleanfalseset to true to enable logging of executed statements -sql.trace.session_eventlog.enabledbooleanfalseset to true to enable session tracing. Note that enabling this may have a non-trivial negative performance impact. -sql.trace.stmt.enable_thresholdduration0sduration beyond which all statements are traced (set to 0 to disable). This applies to individual statements within a transaction and is therefore finer-grained than sql.trace.txn.enable_threshold. -sql.trace.txn.enable_thresholdduration0sduration beyond which all transactions are traced (set to 0 to disable). This setting is coarser grained thansql.trace.stmt.enable_threshold because it applies to all statements within a transaction as well as client communication (e.g. retries). +sql.trace.session_eventlog.enabledbooleanfalseset to true to enable session tracing; note that enabling this may have a negative performance impact +sql.trace.stmt.enable_thresholdduration0senables tracing on all statements; statements executing for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting applies to individual statements within a transaction and is therefore finer-grained than sql.trace.txn.enable_threshold +sql.trace.txn.enable_thresholdduration0senables tracing on all transactions; transactions open for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting is coarser-grained than sql.trace.stmt.enable_threshold because it applies to all statements within a transaction as well as client communication (e.g. retries) sql.ttl.default_delete_batch_sizeinteger100default amount of rows to delete in a single query during a TTL job sql.ttl.default_delete_rate_limitinteger0default delete rate limit for all TTL jobs. Use 0 to signify no rate limit. sql.ttl.default_range_concurrencyinteger1default amount of ranges to process at once during a TTL delete diff --git a/pkg/sql/exec_util.go b/pkg/sql/exec_util.go index 11e041d70c87..c5edbf0fea22 100644 --- a/pkg/sql/exec_util.go +++ b/pkg/sql/exec_util.go @@ -221,10 +221,12 @@ var secondaryTenantZoneConfigsEnabled = settings.RegisterBoolSetting( var traceTxnThreshold = settings.RegisterDurationSetting( settings.TenantWritable, "sql.trace.txn.enable_threshold", - "duration beyond which all transactions are traced (set to 0 to "+ - "disable). This setting is coarser grained than"+ - "sql.trace.stmt.enable_threshold because it applies to all statements "+ - "within a transaction as well as client communication (e.g. retries).", 0, + "enables tracing on all transactions; transactions open for longer than "+ + "this duration will have their trace logged (set to 0 to disable); "+ + "note that enabling this may have a negative performance impact; "+ + "this setting is coarser-grained than sql.trace.stmt.enable_threshold "+ + "because it applies to all statements within a transaction as well as "+ + "client communication (e.g. retries)", 0, ).WithPublic() // TraceStmtThreshold is identical to traceTxnThreshold except it applies to @@ -234,9 +236,11 @@ var traceTxnThreshold = settings.RegisterDurationSetting( var TraceStmtThreshold = settings.RegisterDurationSetting( settings.TenantWritable, "sql.trace.stmt.enable_threshold", - "duration beyond which all statements are traced (set to 0 to disable). "+ - "This applies to individual statements within a transaction and is therefore "+ - "finer-grained than sql.trace.txn.enable_threshold.", + "enables tracing on all statements; statements executing for longer than "+ + "this duration will have their trace logged (set to 0 to disable); "+ + "note that enabling this may have a negative performance impact; "+ + "this setting applies to individual statements within a transaction and "+ + "is therefore finer-grained than sql.trace.txn.enable_threshold", 0, ).WithPublic() @@ -247,8 +251,8 @@ var TraceStmtThreshold = settings.RegisterDurationSetting( var traceSessionEventLogEnabled = settings.RegisterBoolSetting( settings.TenantWritable, "sql.trace.session_eventlog.enabled", - "set to true to enable session tracing. "+ - "Note that enabling this may have a non-trivial negative performance impact.", + "set to true to enable session tracing; "+ + "note that enabling this may have a negative performance impact", false, ).WithPublic()