Merge #104265

104265: util/log: new config field `format-options`, custom timezones in log output r=Santamaura,abargainier a=knz

Fixes #39097.
Fixes #88741.

This PR introduces a framework to define per-format customization options.
See the individual commits for details. 

# JSON output changes

The following options for the `json` format are available:
- `datetime-format`: introduce a new `datetime` field
- `datetime-timezone`: configure the tz for the new `datetime` field
- `fluent-tag`: see format doc
- `tag-style`: see format doc
 
Example:

```yaml
file-defaults:
  format: json
  format-options: { datetime-format: rfc3339, datetime-timezone: America/New_York }
```

Results in entries like this:
```json
{...,"timestamp":"1685719746.454267736","datetime":"2023-06-02T11:29:06.454267736-04:00",...}
```

i.e. the `timestamp` field is unchanged for backward-compatibility; a new `datetime` field is introduced alongside it.

# Text output format changes

Format options are now also supported for `crdb-v1` and `crdb-v2`. In particular, the `timezone` option changes the time zone used to print out the timestamp columns.

For example:
```yaml
file-defaults:
   format: crdb-v2
   format-options: {timezone: america/new_york}
```

Example logging output:
```
I230606 12:43:01.553407-040000 1 1@cli/start.go:575 ⋮ [n?] 4  soft memory limit of Go runtime is set to 35 GiB
                       ^^^^^^^ indicates GMT-4 was used.
```

See the individual commits and the generated documentation for details.

Co-authored-by: Raphael 'kena' Poss <[email protected]>

docs/generated/logsinks.md

@@ -81,6 +81,7 @@ Configuration options shared across all sink types:
 |--|--|
 | `filter` | specifies the default minimum severity for log events to be emitted to this sink, when not otherwise specified by the 'channels' sink attribute. |
 | `format` | the entry format to use. |
+| `format-options` | additional options for the format. |
 | `redact` | whether to strip sensitive information before log events are emitted to this sink. |
 | `redactable` | whether to keep redaction markers in the sink's output. The presence of redaction markers makes it possible to strip sensitive data reliably. |
 | `exit-on-error` | whether the logging system should terminate the process if an error is encountered while writing to this sink. |
@@ -163,6 +164,7 @@ Configuration options shared across all sink types:
 |--|--|
 | `filter` | specifies the default minimum severity for log events to be emitted to this sink, when not otherwise specified by the 'channels' sink attribute. |
 | `format` | the entry format to use. |
+| `format-options` | additional options for the format. |
 | `redact` | whether to strip sensitive information before log events are emitted to this sink. |
 | `redactable` | whether to keep redaction markers in the sink's output. The presence of redaction markers makes it possible to strip sensitive data reliably. |
 | `exit-on-error` | whether the logging system should terminate the process if an error is encountered while writing to this sink. |
@@ -230,6 +232,7 @@ Configuration options shared across all sink types:
 |--|--|
 | `filter` | specifies the default minimum severity for log events to be emitted to this sink, when not otherwise specified by the 'channels' sink attribute. |
 | `format` | the entry format to use. |
+| `format-options` | additional options for the format. |
 | `redact` | whether to strip sensitive information before log events are emitted to this sink. |
 | `redactable` | whether to keep redaction markers in the sink's output. The presence of redaction markers makes it possible to strip sensitive data reliably. |
 | `exit-on-error` | whether the logging system should terminate the process if an error is encountered while writing to this sink. |
@@ -279,7 +282,7 @@ Type-specific configuration options:
 | Field | Description |
 |--|--|
 | `channels` | the list of logging channels that use this sink. See the [channel selection configuration](#channel-format) section for details.  |
-| `no-color` | forces the omission of VT color codes in the output even when stderr is a terminal. |
+| `no-color` | forces the omission of VT color codes in the output even when stderr is a terminal. This option is deprecated; its effects are equivalent to 'format-options: {colors: none}'. |
 
 
 Configuration options shared across all sink types:
@@ -288,6 +291,7 @@ Configuration options shared across all sink types:
 |--|--|
 | `filter` | specifies the default minimum severity for log events to be emitted to this sink, when not otherwise specified by the 'channels' sink attribute. |
 | `format` | the entry format to use. |
+| `format-options` | additional options for the format. |
 | `redact` | whether to strip sensitive information before log events are emitted to this sink. |
 | `redactable` | whether to keep redaction markers in the sink's output. The presence of redaction markers makes it possible to strip sensitive data reliably. |
 | `exit-on-error` | whether the logging system should terminate the process if an error is encountered while writing to this sink. |

pkg/util/flagutil/flagutil.go

@@ -25,6 +25,7 @@ import (
 // as described in time.Parse.
 var TimeFormats = []string{
 	log.MessageTimeFormat,
+	log.MessageTimeFormatWithTZ,
 	log.FileTimeFormat,
 	time.RFC3339Nano,
 	time.RFC3339,

pkg/util/log/flags.go

@@ -15,6 +15,7 @@ import (
 	"fmt"
 	"io/fs"
 	"math"
+	"strings"
 
 	"github.com/cockroachdb/cockroach/pkg/util/envutil"
 	"github.com/cockroachdb/cockroach/pkg/util/log/channel"
@@ -24,6 +25,7 @@ import (
 	"github.com/cockroachdb/cockroach/pkg/util/log/severity"
 	"github.com/cockroachdb/cockroach/pkg/util/syncutil"
 	"github.com/cockroachdb/errors"
+	"github.com/cockroachdb/redact"
 )
 
 type config struct {
@@ -132,7 +134,7 @@ func ApplyConfig(config logconfig.Config) (logShutdownFn func(), err error) {
 
 	// Call the final value of logShutdownFn immediately if returning with error.
 	defer func() {
-		if err != nil {
+		if err != nil && logShutdownFn != nil {
 			logShutdownFn()
 		}
 	}()
@@ -248,6 +250,17 @@ func ApplyConfig(config logconfig.Config) (logShutdownFn func(), err error) {
 	if err := logging.stderrSinkInfoTemplate.applyConfig(config.Sinks.Stderr.CommonSinkConfig); err != nil {
 		return nil, err
 	}
+	if config.Sinks.Stderr.NoColor {
+		// This branch exists for backward compatibility with CockroachDB
+		// v23.1 and previous versions. The same effect can be obtained
+		// using 'format-options: {colors: none}'.
+		switch t := logging.stderrSinkInfoTemplate.formatter.(type) {
+		case *formatCrdbV1:
+			t.colorProfile = nil
+		case *formatCrdbV2:
+			t.colorProfile = nil
+		}
+	}
 	logging.stderrSinkInfoTemplate.applyFilters(config.Sinks.Stderr.Channels)
 
 	// Create the per-channel loggers.
@@ -437,9 +450,15 @@ func (l *sinkInfo) applyConfig(c logconfig.CommonSinkConfig) error {
 	l.criticality = *c.Criticality
 	f, ok := formatters[*c.Format]
 	if !ok {
-		return errors.Newf("unknown format: %q", *c.Format)
+		return errors.WithHintf(errors.Newf("unknown format: %q", *c.Format),
+			"Supported formats: %s.", redact.Safe(strings.Join(formatNames, ", ")))
+	}
+	l.formatter = f()
+	for k, v := range c.FormatOptions {
+		if err := l.formatter.setOption(k, v); err != nil {
+			return err
+		}
 	}
-	l.formatter = f
 	return nil
 }
 

pkg/util/log/format_crdb.go

@@ -29,6 +29,10 @@ const severityChar = "IWEF"
 // as used in time.Parse and time.Format.
 const MessageTimeFormat = "060102 15:04:05.999999"
 
+// MessageTimeFormatWithTZ is like MessageTimeFormat but with a numeric
+// time zone included.
+const MessageTimeFormatWithTZ = "060102 15:04:05.999999-070000"
+
 // FormatLegacyEntry writes the contents of the legacy log entry struct to the specified writer.
 func FormatLegacyEntry(e logpb.Entry, w io.Writer) error {
 	return FormatLegacyEntryWithOptionalColors(e, w, nil /* cp */)
@@ -37,7 +41,7 @@ func FormatLegacyEntry(e logpb.Entry, w io.Writer) error {
 // FormatLegacyEntryWithOptionalColors is like FormatLegacyEntry but the caller can specify
 // a color profile.
 func FormatLegacyEntryWithOptionalColors(e logpb.Entry, w io.Writer, cp ttycolor.Profile) error {
-	buf := formatLogEntryInternalV1(e, false /* isHeader */, true /* showCounter */, cp)
+	buf := formatLogEntryInternalV1(e, false /* isHeader */, true /* showCounter */, cp, nil /* loc */)
 	defer putBuffer(buf)
 	_, err := w.Write(buf.Bytes())
 	return err