From 608e18260c644cec3f21eec3ee7e871e30240a0d Mon Sep 17 00:00:00 2001 From: Florence Morris Date: Tue, 7 Nov 2023 14:45:14 -0500 Subject: [PATCH] (1) Updated Configure Logs page, added Set timezone section. (2) Updated cockroach debug merge-logs page, added required format option and considerations section. (#18036) --- .../v23.2/cockroach-debug-merge-logs.md | 19 ++++++++------ src/current/v23.2/configure-logs.md | 25 +++++++++++++++++++ 2 files changed, 37 insertions(+), 7 deletions(-) diff --git a/src/current/v23.2/cockroach-debug-merge-logs.md b/src/current/v23.2/cockroach-debug-merge-logs.md index 44f5e9af312..9d4e6d46181 100644 --- a/src/current/v23.2/cockroach-debug-merge-logs.md +++ b/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 %}) diff --git a/src/current/v23.2/configure-logs.md b/src/current/v23.2/configure-logs.md index 95150ea0575..bb56bac212b 100644 --- a/src/current/v23.2/configure-logs.md +++ b/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: