New configuration for hi-res timestamps (SparkPost/Momentum#1216)

content/momentum/4/config-options-summary.md

@@ -216,6 +216,7 @@ The `Version` column indicated the version(s) of Momentum that support the optio
 | [log_idle_interval](/momentum/4/modules/4-modules-cluster#option.log_idle_interval) – Amount of time to sleep before looking for another segment (cluster-specific) | na | 10 | 4.0 and later | cluster |
 | [log_requests_to_paniclog](/momentum/3/3-rest/rest-http-listener) – Whether to log REST injection requests | sending | false | 4.0 and later | http_listener, listen, pathway, pathway_group, peer |
 | [Logfile](/momentum/4/config/ref-eccluster-conf#eccluster.conf.logs.logfile) – Describe the full path to the log file | na |   | 4.0 and later | logs |
+| [LogHiresTimestamp](/momentum/4/config/ref-log-hires-timestamp) – Enable microsecond resolution for log timestamps | na | false | 5.3 and later | global |
 | [logs](/momentum/4/config/ref-ecelerity-cluster-conf) – Define the location of the cluster manager logs (cluster-specific) | na |   | 4.0 and later | cluster |
 | [logs](/momentum/4/config/ref-eccluster-conf) *(scope)* – Configure centralized log files on the cluster manager | na |   | 4.0 and later | global |
 | [low_action](/momentum/4/modules/4-adaptive#modules.adaptive.low_action) – Action when the high threshold is not met but the low threshold is met | sending | "throttle" "down" | 4.0 and later | adaptive_sweep_rule |

content/momentum/4/config/ref-log-hires-timestamp.md

@@ -0,0 +1,69 @@
+---
+lastUpdated: "07/01/2026"
+title: "LogHiresTimestamp"
+description: "LogHiresTimestamp enables microsecond resolution for log timestamps written by Momentum across the mainlog, bouncelog, rejectlog, paniclog, custom logs, and other logging modules"
+---
+
+<a name="conf.ref.log_hires_timestamp"></a>
+## Name
+
+LogHiresTimestamp — enable microsecond resolution for log timestamps
+
+## Synopsis
+
+`LogHiresTimestamp = true`
+
+<a name="idp.log_hires_timestamp"></a>
+## Description
+
+When `LogHiresTimestamp` is set to `true`, Momentum writes log timestamps with microsecond (1 µs) resolution instead of the default 1-second resolution.
+
+### Rationale
+
+Several Momentum log files are produced concurrently by independent loggers (for example `mainlog`, `bouncelog`, `rejectlog`, and `paniclog`). With the default 1-second resolution, many events that happen within the same second share an identical timestamp, and the relative ordering of events between files becomes ambiguous when the logs are read together — for instance when merging them in a log viewer such as [lnav](https://lnav.org/) or feeding them into a SIEM or analytics pipeline. Microsecond timestamps preserve the true ordering across files, which is essential for diagnostics, latency analysis, and other investigations.
+
+### Scope of the option
+
+The setting is global and affects every log file whose timestamps are produced by the core logging code, including:
+
+*   `mainlog` (reception, delivery, transient failure, permanent failure, heartbeat, accounting and import records — see [mainlog](/momentum/4/log-formats-mainlog))
+
+*   `bouncelog` (bounce and heartbeat records — see [bouncelog](/momentum/4/log-formats-bouncelog))
+
+*   `rejectlog` (rejection records — see [rejectlog](/momentum/4/log-formats-rejectlog))
+
+*   `paniclog` (panic and HTTP request records — see [paniclog](/momentum/4/log-formats-paniclog))
+
+*   Custom logs produced by [custom_logger](/momentum/4/modules/custom-logger) and [custom_bounce_logger](/momentum/4/modules/custom-bounce-logger)
+
+*   Chunk logs produced by [chunk_logger](/momentum/4/modules/chunk-logger)
+
+*   Message generation logs produced by the `msg_gen` module
+
+*   Critical messages written to `stderr` by the [ec_logger](/momentum/4/modules/ec-logger), formatted with [timestampformat](/momentum/4/config/ref-timestampformat)
+
+The effect on each timestamp depends on how it is rendered:
+
+*   **Numeric (epoch) timestamps.** A timestamp emitted as a decimal Unix epoch value (for example, the first field of every `mainlog`, `bouncelog`, `rejectlog`, or `paniclog` line) changes from a 10-digit seconds-since-epoch value (`1064868656`) to a 16-digit microseconds-since-epoch value (`1064868656123456`). No separator is inserted, so the field remains a single integer that downstream parsers can keep treating as a number.
+
+*   **Formatted (`strftime`) timestamps.** Timestamps rendered through a `strftime(3)` format string — such as the `timestamp_format` of [chunk_logger](/momentum/4/modules/chunk-logger), the `%t{...}` macro of [custom_logger](/momentum/4/modules/custom-logger), or [timestampformat](/momentum/4/config/ref-timestampformat) — keep the configured format, but every `%S` or `%T` conversion is followed by a `.NNNNNN` six-digit microsecond fraction. For example, the default `[%a %d %b %Y %H:%M:%S] ` becomes `[%a %d %b %Y %H:%M:%S.NNNNNN] ` and renders as `[Mon 20 May 2026 14:32:17.482915] `.
+
+When `LogHiresTimestamp` is `false` (the default), timestamps are emitted exactly as in previous releases of Momentum, with 1-second resolution and no `.NNNNNN` fraction.
+
+## Compatibility
+
+Tools that parse the numeric epoch field must accept either 10 or 16 decimal digits when this option is enabled. The Perl modules under `Ecelerity::Log` shipped with Momentum (`Ecelerity::Log::Auto`, `Ecelerity::Log::Bounce`, `Ecelerity::Log::Reject`, `Ecelerity::Log::Statp`) recognize both forms; when the source field is in microseconds, they expose it on the parsed record as `epoch_us` and keep populating `epoch` with the integer seconds, so existing consumers continue to work unchanged.
+
+<a name="idp.log_hires_timestamp.online"></a>
+## Online Modification
+
+`LogHiresTimestamp` is not online-tunable. Changing the option requires a Momentum restart.
+
+<a name="idp.log_hires_timestamp.scope"></a>
+## Scope
+
+`LogHiresTimestamp` is valid in the global scope.
+
+## See Also
+
+[timestampformat](/momentum/4/config/ref-timestampformat), [mainlog](/momentum/4/log-formats-mainlog), [bouncelog](/momentum/4/log-formats-bouncelog), [rejectlog](/momentum/4/log-formats-rejectlog), [paniclog](/momentum/4/log-formats-paniclog)

content/momentum/4/config/ref-timestampformat.md

@@ -18,7 +18,11 @@ timestampformat — set the timestamp format used when logging to stderr
 
 Sets the timestamp format used by Momentum when logging to `stderr`. This output is usually not seen unless you invoke **ecelerity** using the `-d` option. The default value is shown above.
 
+> **Note**
+>
+> When [LogHiresTimestamp](/momentum/4/config/ref-log-hires-timestamp) is enabled (Momentum 5.3 and later), every `%S` or `%T` conversion in the configured format is automatically followed by a `.NNNNNN` six-digit microsecond fraction, so the default value renders as `[Mon 20 May 2026 14:32:17.482915] `.
+
 <a name="idp26785984"></a> 
 ## Scope
 
-`timestampformat` is valid in the global scope.
+`timestampformat` is valid in the global scope.

content/momentum/4/log-formats-bouncelog.md

@@ -6,6 +6,10 @@ description: "The bouncelog records both in band and out of band bounces It is c
 
 The `bouncelog` records both in-band and out-of-band bounces. It is configured in the [bounce_logger](/momentum/4/modules/bounce-logger) module.
 
+> **Note**
+>
+> When [LogHiresTimestamp](/momentum/4/config/ref-log-hires-timestamp) is enabled (Momentum 5.3 and later), the timestamp field at offset `0` of every record is emitted as a 16-digit microseconds-since-epoch value (for example `1064868656123456`) instead of a 10-digit seconds-since-epoch value. The field remains a single integer with no separator.
+
 ### <a name="idp4696736"></a> Bounce Records
 
 A bounce line is written to the `bouncelog` for every bounce that Momentum witnesses. The log entry is an `@` delimited string, such as the following:

content/momentum/4/log-formats-mainlog.md

@@ -10,6 +10,10 @@ Every event is written to the `mainlog` file as a single line. Fixed position co
 
 The following sections define the format for each event type.
 
+> **Note**
+>
+> When [LogHiresTimestamp](/momentum/4/config/ref-log-hires-timestamp) is enabled (Momentum 5.3 and later), the timestamp field at offset `0` of every record is emitted as a 16-digit microseconds-since-epoch value (for example `1064868656123456`) instead of a 10-digit seconds-since-epoch value. The field remains a single integer with no separator.
+
 ### <a name="idp4862592"></a> Reception Records
 
 A reception line is written to the `mainlog` for every reception that Momentum performs. The log entry is an `@` delimited string, such as the following:

content/momentum/4/log-formats-paniclog.md

@@ -10,6 +10,10 @@ Under normal circumstances, Debug_Flags should be empty or should be omitted fro
 
 In addition, Momentum logs entries to the `paniclog` when the `log_requests_to_paniclog` option is enabled in the HTTP_Listener and its nested scopes.
 
+> **Note**
+>
+> When [LogHiresTimestamp](/momentum/4/config/ref-log-hires-timestamp) is enabled (Momentum 5.3 and later), the leading timestamp of every record (the value preceding the `:` separator) is emitted as a 16-digit microseconds-since-epoch value (for example `1307461172123456:`) instead of a 10-digit seconds-since-epoch value. The value remains a single integer with no internal separator.
+
 ### <a name="idp5044896"></a> Panic Records
 
 A line is written to the `paniclog` for every system event, when enabled in the configuration. The fields in the log entry are delimited by spaces.

content/momentum/4/log-formats-rejectlog.md

@@ -6,6 +6,10 @@ description: "The rejectlog stores records of inbound messages that are rejected
 
 The `rejectlog` stores records of inbound messages that are rejected by Momentum, either due to policy or protocol deviations. It lists the full context for all rejected messages, as well as a summary of why the message was rejected, and it is configured in the [ec_logger](/momentum/4/modules/ec-logger).
 
+> **Note**
+>
+> When [LogHiresTimestamp](/momentum/4/config/ref-log-hires-timestamp) is enabled (Momentum 5.3 and later), the leading timestamp of every record (the value preceding the `:` separator) is emitted as a 16-digit microseconds-since-epoch value (for example `1236672125123456:`) instead of a 10-digit seconds-since-epoch value. The value remains a single integer with no internal separator.
+
 ### <a name="idp5073872"></a> Rejection Records
 
 A rejection line is written to the `rejectlog` for every rejection that Momentum performs. The fields in the log entry are delimited by spaces, such as the following:

content/momentum/changelog/5/5-3-0.md

@@ -12,4 +12,5 @@ This section will list all of the major changes that happened with the release o
 | --- | --- | --- |
 | Feature | I-1064 | Added support for [license](/momentum/4/before-you-begin#momentum-license) signatures using ECDSA P-256 with SHA-256. |
 | Feature | I-1214 | Removed `msys-nodejs` RPM from the Momentum bundle, to be replaced with the 3rd-party `nodejs` package. Node.js LTS 24+ must be installed separately from the system or a vendor repository. |
+| Feature | I-1216 | Added the [LogHiresTimestamp](/momentum/4/config/ref-log-hires-timestamp) option to emit microsecond-resolution timestamps in the `mainlog`, `bouncelog`, `rejectlog`, `paniclog`, custom logs, chunk logs, and message generation logs, preserving event ordering when reading multiple log files together. |
 | Fix | TASK-227757 | [`ha_proxy_client`](/momentum/4/modules/ha-proxy-client) now re-resolves a hostname-based `ha_proxy_server` during each health check, so backend IP changes are picked up automatically without restart. |