(1) Updated Configure Logs page, added Set timezone section. (2) Upda…

…ted cockroach debug merge-logs page, added required format option and considerations section. (#18036)

src/current/v23.2/cockroach-debug-merge-logs.md

@@ -24,10 +24,11 @@ $ cockroach debug merge-logs [log file directory] [flags]
 
 ## Flags
 
-Use the following flags to filter the `debug merge-logs` results for a specified regular expression or time range.
+The `debug merge-logs` subcommand supports the following flags:
 
 Flag | Description
 -----|-----------
+`--format` | **Required** The [format of the logs]({% link {{ page.version.version }}/log-formats.md %}) in the log file directory. The logs in a `.zip` generated using [`cockroach debug zip`]({% link {{ page.version.version }}/cockroach-debug-zip.md %}) are of type [`crdb-v1`]({% link {{ page.version.version }}/log-formats.md %}#format-crdb-v1).
 `--filter` | Limit the results to the specified regular expression
 `--from` | Start time for the time range filter.
 `--to` | End time for the time range filter.
@@ -39,44 +40,48 @@ Generate a debug zip file:
 
 {% include_cached copy-clipboard.html %}
 ~~~ shell
-$ cockroach debug zip ./cockroach-data/logs/debug.zip --insecure
+cockroach debug zip ./cockroach-data/logs/debug.zip --insecure
 ~~~
 
 Unzip the file:
 
 {% include_cached copy-clipboard.html %}
 ~~~ shell
-$ unzip ./cockroach-data/logs/debug.zip
+unzip ./cockroach-data/logs/debug.zip
 ~~~
 
 Merge the logs in the debug folder:
 
 {% include_cached copy-clipboard.html %}
 ~~~ shell
-$ cockroach debug merge-logs debug/nodes/*/logs/*
+cockroach debug merge-logs debug/nodes/*/logs/* --format=crdb-v1
 ~~~
 
 Alternatively, filter the merged logs for a specified time range:
 
 {% include_cached copy-clipboard.html %}
 ~~~ shell
-$ cockroach debug merge-logs debug/nodes/*/logs/* --from="220713 18:36:28.208553" --to="220713 18:36:29.232864"
+cockroach debug merge-logs debug/nodes/*/logs/* --format=crdb-v1 --from="231031 19:19:50.917185" --to="231031 19:19:57.189263"
 ~~~
 
 You can also filter the merged logs for a regular expression:
 
 {% include_cached copy-clipboard.html %}
 ~~~ shell
-cockroach debug merge-logs debug/nodes/*/logs/* --filter="RUNNING IN INSECURE MODE"
+cockroach debug merge-logs debug/nodes/*/logs/* --format=crdb-v1 --filter="ALL SECURITY CONTROLS HAVE BEEN DISABLED"
 ~~~
 
 You can redact sensitive information from the merged logs:
 
 {% include_cached copy-clipboard.html %}
 ~~~ shell
-cockroach debug merge-logs --redact debug/nodes/*/logs/*
+cockroach debug merge-logs debug/nodes/*/logs/* --format=crdb-v1 --redact
 ~~~
 
+## Considerations
+
+As of v23.2, logs can be configured to use a [timezone with formats `crdb-v1` or `crdb-v2`]({% link {{ page.version.version }}/configure-logs.md %}#set-timezone). This is a [backward-incompatible change](https://www.cockroachlabs.com/docs/releases/v23.2#v23-2-0-alpha-1-backward-incompatible-changes). `cockroach debug merge-logs` requires v23.2 or later if run against logs with the timezone configured. With versions prior to v23.2, `cockroach debug merge-logs` will return an error if run against logs with the timezone configured.
+
 ## See also
 
 - [File an Issue]({% link {{ page.version.version }}/file-an-issue.md %})

src/current/v23.2/configure-logs.md

@@ -483,6 +483,31 @@ sinks:
       channels: {INFO: DEV, ERROR: OPS}
 ~~~
 
+### Set timezone
+
+The log output formats [`crdb-v1`]({% link {{ page.version.version }}/log-formats.md %}#format-crdb-v1) and [`crdb-v2`]({% link {{ page.version.version }}/log-formats.md %}#format-crdb-v2) support the format option `timezone`. When specified, the corresponding timezone is used to produce the timestamp column. The value can be any [timezone name recognized by the Go standard library](https://github.com/arp242/tz/blob/bf333631bec4/list.go).
+
+For example:
+
+{% include_cached copy-clipboard.html %}
+~~~ yaml
+file-defaults:
+  format: crdb-v2
+  format-options: {timezone: america/new_york}
+~~~
+
+The timezone offset is included with the timestamp to ensure that the times can be read back precisely.
+
+Example logging output:
+
+~~~
+I231030 14:17:23.674909-040000 1 1@cli/log_flags.go:200 ⋮ [n?] 1  using explicit logging configuration:
+I231030 14:17:23.674909-040000 1 1@cli/log_flags.go:200 ⋮ [n?] 1 +‹file-defaults:›
+I231030 14:17:23.674909-040000 1 1@cli/log_flags.go:200 ⋮ [n?] 1 +‹   format: crdb-v2›
+I231030 14:17:23.674909-040000 1 1@cli/log_flags.go:200 ⋮ [n?] 1 +‹   format-options: {timezone: america/new_york}›
+                       ^^^^^^^ indicates GMT-4 timezone offset was used.
+~~~
+
 ### Redact logs
 
 CockroachDB can redact personally identifiable information (PII) from log messages. The logging system includes two parameters that handle this differently: