Add configurable logTimeFormat option

Logs hardcoded timestamps as Unix milliseconds, which carries no
timezone and reads as UTC in plain log viewers (podman logs, logread).
This adds a logTimeFormat config field so operators can pick a
TZ-aware format, while keeping the existing numeric output as default.

- New TypeLogTimeFormat wrapper (typed like every other config field):
  presets unix / unix-ms / unix-micro / unix-nano / rfc3339 /
  rfc3339-nano, and any other value is passed through to zerolog as a
  Go reference-time layout. Set() rejects an empty value.
- Default stays "unix-ms" -> zerolog.TimeFormatUnixMs, so output is
  byte-for-byte unchanged unless the option is set.
- run_proxy.go resolves the configured value instead of hardcoding it.
- example.config.toml documents the presets with a single consistent
  example instant.

Based on the approach of #531 by @resolvicomai. Resolves #427.

example.config.toml

@@ -15,6 +15,31 @@
 # you have any issue.
 debug = true
 
+# logTimeFormat configures the timestamp format in logs. The default is
+# "unix-ms", which keeps the historical integer Unix-milliseconds output,
+# so nothing that parses the current logs breaks.
+#
+# All example values below render the same instant:
+# 2026-05-20T12:23:45.123Z, i.e. 2026-05-20T15:23:45.123 at +03:00.
+#
+# Numeric presets (good for log aggregators, always UTC by definition):
+#   "unix-ms"      Unix milliseconds.  DEFAULT. 1779279825123
+#   "unix"         Unix seconds.       1779279825
+#   "unix-micro"   Unix microseconds.  1779279825123456
+#   "unix-nano"    Unix nanoseconds.   1779279825123456789
+#
+# Human-readable presets (honor the host timezone):
+#   "rfc3339"      2026-05-20T15:23:45+03:00
+#   "rfc3339-nano" 2026-05-20T15:23:45.123456789+03:00
+#
+# Or any Go time layout. Reference moment: Mon Jan 2 15:04:05 MST 2006.
+# Examples:
+#   log-time-format = "2006-01-02 15:04:05"            # 2026-05-20 15:23:45
+#   log-time-format = "2006-01-02 15:04:05.000 -0700"  # with ms and offset
+#   log-time-format = "02 Jan 2006 15:04:05 MST"       # 20 May 2026 15:23:45 MSK
+#
+# log-time-format = "unix-ms"
+
 # A secret (required). Please remember that mtg supports only FakeTLS
 # mode, legacy simple and secured mode are prohibited. For you it means
 # that secret should either be base64-encoded or starts with ee.

internal/cli/run_proxy.go

@@ -24,7 +24,13 @@ import (
 )
 
 func makeLogger(conf *config.Config) mtglib.Logger {
-	zerolog.TimeFieldFormat = zerolog.TimeFormatUnixMs
+	// An unset log time format keeps mtg's historical default
+	// (Unix milliseconds), so the existing output does not change.
+	logTimeFormat := config.TypeLogTimeFormat{
+		Value: conf.LogTimeFormat.Get(config.TypeLogTimeFormatUnixMs),
+	}
+
+	zerolog.TimeFieldFormat = logTimeFormat.ZerologFormat()
 	zerolog.TimestampFieldName = "timestamp"
 	zerolog.LevelFieldName = "level"
 

internal/cli/run_proxy_test.go

@@ -0,0 +1,44 @@
+package cli
+
+import (
+	"testing"
+	"time"
+
+	"github.com/9seconds/mtg/v2/internal/config"
+	"github.com/rs/zerolog"
+	"github.com/stretchr/testify/assert"
+)
+
+// TestMakeLoggerTimeFieldFormat verifies that the configured logTimeFormat
+// is what ends up in zerolog's global TimeFieldFormat — including the
+// historical default when the field is unset.
+func TestMakeLoggerTimeFieldFormat(t *testing.T) {
+	cases := []struct {
+		name  string
+		value string
+		want  string
+	}{
+		{name: "unset-default", value: "", want: zerolog.TimeFormatUnixMs},
+		{name: "unix", value: "unix", want: zerolog.TimeFormatUnix},
+		{name: "unix-ms", value: "unix-ms", want: zerolog.TimeFormatUnixMs},
+		{name: "unix-micro", value: "unix-micro", want: zerolog.TimeFormatUnixMicro},
+		{name: "unix-nano", value: "unix-nano", want: zerolog.TimeFormatUnixNano},
+		{name: "rfc3339", value: "rfc3339", want: time.RFC3339},
+		{name: "rfc3339-nano", value: "rfc3339-nano", want: time.RFC3339Nano},
+		{name: "go-layout", value: "2006-01-02 15:04:05", want: "2006-01-02 15:04:05"},
+	}
+
+	for _, c := range cases {
+		c := c
+
+		t.Run(c.name, func(t *testing.T) {
+			conf := &config.Config{}
+			if c.value != "" {
+				assert.NoError(t, conf.LogTimeFormat.Set(c.value))
+			}
+
+			makeLogger(conf)
+			assert.Equal(t, c.want, zerolog.TimeFieldFormat)
+		})
+	}
+}

internal/config/config.go

@@ -22,20 +22,21 @@ type ListConfig struct {
 }
 
 type Config struct {
-	Debug                       TypeBool        `json:"debug"`
-	AllowFallbackOnUnknownDC    TypeBool        `json:"allowFallbackOnUnknownDc"`
-	Secret                      mtglib.Secret   `json:"secret"`
-	BindTo                      TypeHostPort    `json:"bindTo"`
-	ProxyProtocolListener       TypeBool        `json:"proxyProtocolListener"`
-	PreferIP                    TypePreferIP    `json:"preferIp"`
-	AutoUpdate                  TypeBool        `json:"autoUpdate"`
-	DomainFrontingPort          TypePort        `json:"domainFrontingPort"`
-	DomainFrontingIP            TypeIP          `json:"domainFrontingIp"`
-	DomainFrontingProxyProtocol TypeBool        `json:"domainFrontingProxyProtocol"`
-	TolerateTimeSkewness        TypeDuration    `json:"tolerateTimeSkewness"`
-	Concurrency                 TypeConcurrency `json:"concurrency"`
-	PublicIPv4                  TypeIP          `json:"publicIpv4"`
-	PublicIPv6                  TypeIP          `json:"publicIpv6"`
+	Debug                       TypeBool          `json:"debug"`
+	LogTimeFormat               TypeLogTimeFormat `json:"logTimeFormat"`
+	AllowFallbackOnUnknownDC    TypeBool          `json:"allowFallbackOnUnknownDc"`
+	Secret                      mtglib.Secret     `json:"secret"`
+	BindTo                      TypeHostPort      `json:"bindTo"`
+	ProxyProtocolListener       TypeBool          `json:"proxyProtocolListener"`
+	PreferIP                    TypePreferIP      `json:"preferIp"`
+	AutoUpdate                  TypeBool          `json:"autoUpdate"`
+	DomainFrontingPort          TypePort          `json:"domainFrontingPort"`
+	DomainFrontingIP            TypeIP            `json:"domainFrontingIp"`
+	DomainFrontingProxyProtocol TypeBool          `json:"domainFrontingProxyProtocol"`
+	TolerateTimeSkewness        TypeDuration      `json:"tolerateTimeSkewness"`
+	Concurrency                 TypeConcurrency   `json:"concurrency"`
+	PublicIPv4                  TypeIP            `json:"publicIpv4"`
+	PublicIPv6                  TypeIP            `json:"publicIpv6"`
 	DomainFronting              struct {
 		Host          TypeHost `json:"host"`
 		IP            TypeIP   `json:"ip"`
@@ -71,10 +72,10 @@ type Config struct {
 			Interval TypeDuration    `json:"interval"`
 			Count    TypeConcurrency `json:"count"`
 		} `json:"keepAlive"`
-		DOHIP            TypeIP         `json:"dohIp"`
-		DNS              TypeDNSURI     `json:"dns"`
-		Proxies          []TypeProxyURL `json:"proxies"`
-		TCPNotSentLowat  TypeBytes      `json:"tcpNotSentLowat"`
+		DOHIP           TypeIP         `json:"dohIp"`
+		DNS             TypeDNSURI     `json:"dns"`
+		Proxies         []TypeProxyURL `json:"proxies"`
+		TCPNotSentLowat TypeBytes      `json:"tcpNotSentLowat"`
 	} `json:"network"`
 	Stats struct {
 		StatsD struct {

internal/config/config_test.go

@@ -42,6 +42,49 @@ func (suite *ConfigTestSuite) TestParseMinimalConfig() {
 	suite.Equal("0.0.0.0:3128", conf.BindTo.String())
 }
 
+func (suite *ConfigTestSuite) TestParseLogTimeFormatDefault() {
+	conf, err := config.Parse(suite.ReadConfig("minimal.toml"))
+	suite.NoError(err)
+	suite.Equal("unix-ms", conf.LogTimeFormat.Get("unix-ms"))
+}
+
+func (suite *ConfigTestSuite) TestParseLogTimeFormatPresets() {
+	presets := []string{
+		"unix", "unix-ms", "unix-micro", "unix-nano",
+		"rfc3339", "rfc3339-nano",
+		"2006-01-02 15:04:05",
+	}
+
+	for _, preset := range presets {
+		preset := preset
+
+		suite.Run(preset, func() {
+			conf, err := config.Parse([]byte(`
+secret = "7oe1GqLy6TBc38CV3jx7q09nb29nbGUuY29t"
+bind-to = "0.0.0.0:3128"
+log-time-format = "` + preset + `"
+`))
+			suite.NoError(err)
+			suite.Equal(preset, conf.LogTimeFormat.Get("unix-ms"))
+		})
+	}
+}
+
+func (suite *ConfigTestSuite) TestParseLogTimeFormatEmptyIsUnset() {
+	// An explicitly empty log-time-format is dropped by the TOML->JSON
+	// omitempty step (the same as prefer-ip and every other optional
+	// string field), so it is treated as unset and falls back to the
+	// default. Rejection of a genuinely empty value is enforced by
+	// TypeLogTimeFormat.Set, exercised in type_log_time_format_test.go.
+	conf, err := config.Parse([]byte(`
+secret = "7oe1GqLy6TBc38CV3jx7q09nb29nbGUuY29t"
+bind-to = "0.0.0.0:3128"
+log-time-format = ""
+`))
+	suite.NoError(err)
+	suite.Equal("unix-ms", conf.LogTimeFormat.Get("unix-ms"))
+}
+
 func (suite *ConfigTestSuite) TestParsePublicIP() {
 	conf, err := config.Parse(suite.ReadConfig("public_ip.toml"))
 	suite.NoError(err)

internal/config/parse.go

@@ -10,6 +10,7 @@ import (
 
 type tomlConfig struct {
 	Debug                       bool   `toml:"debug" json:"debug,omitempty"`
+	LogTimeFormat               string `toml:"log-time-format" json:"logTimeFormat,omitempty"`
 	AllowFallbackOnUnknownDC    bool   `toml:"allow-fallback-on-unknown-dc" json:"allowFallbackOnUnknownDc,omitempty"`
 	Secret                      string `toml:"secret" json:"secret"`
 	BindTo                      string `toml:"bind-to" json:"bindTo"`

internal/config/type_log_time_format.go

@@ -0,0 +1,105 @@
+package config
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/rs/zerolog"
+)
+
+const (
+	// TypeLogTimeFormatUnix renders log timestamps as integer Unix
+	// seconds.
+	TypeLogTimeFormatUnix = "unix"
+
+	// TypeLogTimeFormatUnixMs renders log timestamps as integer Unix
+	// milliseconds. This is the default and matches mtg's historical
+	// behavior.
+	TypeLogTimeFormatUnixMs = "unix-ms"
+
+	// TypeLogTimeFormatUnixMicro renders log timestamps as integer Unix
+	// microseconds.
+	TypeLogTimeFormatUnixMicro = "unix-micro"
+
+	// TypeLogTimeFormatUnixNano renders log timestamps as integer Unix
+	// nanoseconds.
+	TypeLogTimeFormatUnixNano = "unix-nano"
+
+	// TypeLogTimeFormatRFC3339 renders log timestamps as an RFC3339
+	// string, honoring the host timezone.
+	TypeLogTimeFormatRFC3339 = "rfc3339"
+
+	// TypeLogTimeFormatRFC3339Nano renders log timestamps as an
+	// RFC3339Nano string, honoring the host timezone.
+	TypeLogTimeFormatRFC3339Nano = "rfc3339-nano"
+)
+
+// TypeLogTimeFormat configures the timestamp format used by the logger.
+//
+// A value is either one of the presets above or any Go reference-time
+// layout (see the time package). Presets map to zerolog's Unix magic
+// constants or to time.RFC3339/time.RFC3339Nano; everything else is
+// handed to zerolog verbatim as a layout string.
+//
+// Validation is intentionally shallow: a Go layout is just a string, so
+// there is no way to reject a malformed one up front without rendering a
+// sample timestamp (and even that has false negatives). Set therefore
+// rejects only what is unambiguously wrong — an empty value — and accepts
+// any non-empty string, leaving genuine layout typos to surface in the
+// log output.
+type TypeLogTimeFormat struct {
+	Value string
+}
+
+func (t *TypeLogTimeFormat) Set(value string) error {
+	if strings.TrimSpace(value) == "" {
+		return fmt.Errorf("log time format cannot be empty")
+	}
+
+	t.Value = value
+
+	return nil
+}
+
+func (t TypeLogTimeFormat) Get(defaultValue string) string {
+	if t.Value == "" {
+		return defaultValue
+	}
+
+	return t.Value
+}
+
+// ZerologFormat resolves the configured value to the string that
+// zerolog.TimeFieldFormat expects: a Unix magic constant, an RFC3339
+// layout, or the raw Go layout for a free-form value.
+func (t TypeLogTimeFormat) ZerologFormat() string {
+	switch strings.ToLower(strings.TrimSpace(t.Value)) {
+	case TypeLogTimeFormatUnix:
+		return zerolog.TimeFormatUnix
+	case TypeLogTimeFormatUnixMs:
+		return zerolog.TimeFormatUnixMs
+	case TypeLogTimeFormatUnixMicro:
+		return zerolog.TimeFormatUnixMicro
+	case TypeLogTimeFormatUnixNano:
+		return zerolog.TimeFormatUnixNano
+	case TypeLogTimeFormatRFC3339:
+		return time.RFC3339
+	case TypeLogTimeFormatRFC3339Nano:
+		return time.RFC3339Nano
+	default:
+		return t.Value
+	}
+}
+
+func (t *TypeLogTimeFormat) UnmarshalText(data []byte) error {
+	return t.Set(string(data))
+}
+
+func (t TypeLogTimeFormat) MarshalText() ([]byte, error) {
+	return []byte(t.String()), nil
+}
+
+func (t TypeLogTimeFormat) String() string {
+	return t.Value
+}

internal/config/type_log_time_format_test.go

@@ -0,0 +1,126 @@
+package config_test
+
+import (
+	"encoding/json"
+	"testing"
+	"time"
+
+	"github.com/9seconds/mtg/v2/internal/config"
+	"github.com/rs/zerolog"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/suite"
+)
+
+type typeLogTimeFormatTestStruct struct {
+	Value config.TypeLogTimeFormat `json:"value"`
+}
+
+type TypeLogTimeFormatTestSuite struct {
+	suite.Suite
+}
+
+func (suite *TypeLogTimeFormatTestSuite) TestUnmarshalFail() {
+	testData := []string{
+		"",
+		"   ",
+	}
+
+	for _, v := range testData {
+		data, err := json.Marshal(map[string]string{
+			"value": v,
+		})
+		suite.NoError(err)
+
+		suite.T().Run(v, func(t *testing.T) {
+			assert.Error(t, json.Unmarshal(data, &typeLogTimeFormatTestStruct{}))
+		})
+	}
+}
+
+func (suite *TypeLogTimeFormatTestSuite) TestUnmarshalOk() {
+	testData := []string{
+		"unix",
+		"unix-ms",
+		"unix-micro",
+		"unix-nano",
+		"rfc3339",
+		"rfc3339-nano",
+		"UNIX-MS",
+		"RFC3339",
+		"2006-01-02 15:04:05",
+		"02 Jan 2006 15:04:05 MST",
+	}
+
+	for _, v := range testData {
+		data, err := json.Marshal(map[string]string{
+			"value": v,
+		})
+		suite.NoError(err)
+
+		suite.T().Run(v, func(t *testing.T) {
+			assert.NoError(t, json.Unmarshal(data, &typeLogTimeFormatTestStruct{}))
+		})
+	}
+}
+
+func (suite *TypeLogTimeFormatTestSuite) TestZerologFormatPresets() {
+	testData := []struct {
+		value string
+		want  string
+	}{
+		{value: "unix", want: zerolog.TimeFormatUnix},
+		{value: "unix-ms", want: zerolog.TimeFormatUnixMs},
+		{value: "unix-micro", want: zerolog.TimeFormatUnixMicro},
+		{value: "unix-nano", want: zerolog.TimeFormatUnixNano},
+		{value: "rfc3339", want: time.RFC3339},
+		{value: "rfc3339-nano", want: time.RFC3339Nano},
+		// Case-insensitive on presets.
+		{value: "UNIX-NANO", want: zerolog.TimeFormatUnixNano},
+		{value: "RFC3339-Nano", want: time.RFC3339Nano},
+		// Surrounding whitespace is trimmed on presets.
+		{value: "  unix-ms  ", want: zerolog.TimeFormatUnixMs},
+		// Anything else is a Go layout passed through verbatim.
+		{value: "2006-01-02 15:04:05", want: "2006-01-02 15:04:05"},
+		{value: "02 Jan 2006 15:04:05 MST", want: "02 Jan 2006 15:04:05 MST"},
+	}
+
+	for _, c := range testData {
+		c := c
+
+		suite.T().Run(c.value, func(t *testing.T) {
+			v := config.TypeLogTimeFormat{}
+			assert.NoError(t, v.Set(c.value))
+			assert.Equal(t, c.want, v.ZerologFormat())
+		})
+	}
+}
+
+func (suite *TypeLogTimeFormatTestSuite) TestSetRejectsEmpty() {
+	v := config.TypeLogTimeFormat{}
+
+	suite.Error(v.Set(""))
+	suite.Error(v.Set("   "))
+}
+
+func (suite *TypeLogTimeFormatTestSuite) TestGetDefault() {
+	// A zero value carries no format; Get must fall back to the default.
+	v := config.TypeLogTimeFormat{}
+	suite.Equal("unix-ms", v.Get("unix-ms"))
+
+	suite.NoError(v.Set("rfc3339"))
+	suite.Equal("rfc3339", v.Get("unix-ms"))
+}
+
+func (suite *TypeLogTimeFormatTestSuite) TestMarshalRoundTrip() {
+	testStruct := &typeLogTimeFormatTestStruct{}
+	suite.NoError(testStruct.Value.Set("rfc3339"))
+
+	encoded, err := json.Marshal(testStruct)
+	suite.NoError(err)
+	suite.Contains(string(encoded), "rfc3339")
+}
+
+func TestTypeLogTimeFormat(t *testing.T) {
+	t.Parallel()
+	suite.Run(t, &TypeLogTimeFormatTestSuite{})
+}