diff --git a/content/momentum/4/config-options-summary.md b/content/momentum/4/config-options-summary.md index a7bee5930..da6d525bf 100644 --- a/content/momentum/4/config-options-summary.md +++ b/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 | diff --git a/content/momentum/4/config/ref-log-hires-timestamp.md b/content/momentum/4/config/ref-log-hires-timestamp.md new file mode 100644 index 000000000..f899a1ffb --- /dev/null +++ b/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" +--- + + +## Name + +LogHiresTimestamp — enable microsecond resolution for log timestamps + +## Synopsis + +`LogHiresTimestamp = true` + + +## 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. + + +## Online Modification + +`LogHiresTimestamp` is not online-tunable. Changing the option requires a Momentum restart. + + +## 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) diff --git a/content/momentum/4/config/ref-timestampformat.md b/content/momentum/4/config/ref-timestampformat.md index 90012fd5d..6de84172b 100644 --- a/content/momentum/4/config/ref-timestampformat.md +++ b/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] `. + ## Scope -`timestampformat` is valid in the global scope. \ No newline at end of file +`timestampformat` is valid in the global scope. diff --git a/content/momentum/4/log-formats-bouncelog.md b/content/momentum/4/log-formats-bouncelog.md index 96d6ec27a..9d0b6ced5 100644 --- a/content/momentum/4/log-formats-bouncelog.md +++ b/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. + ### 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: diff --git a/content/momentum/4/log-formats-mainlog.md b/content/momentum/4/log-formats-mainlog.md index f69eba865..122966219 100644 --- a/content/momentum/4/log-formats-mainlog.md +++ b/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. + ### 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: diff --git a/content/momentum/4/log-formats-paniclog.md b/content/momentum/4/log-formats-paniclog.md index c9d00a3cc..f3c15c8eb 100644 --- a/content/momentum/4/log-formats-paniclog.md +++ b/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. + ### 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. diff --git a/content/momentum/4/log-formats-rejectlog.md b/content/momentum/4/log-formats-rejectlog.md index 14afe266d..27a99281b 100644 --- a/content/momentum/4/log-formats-rejectlog.md +++ b/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. + ### 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: diff --git a/content/momentum/changelog/5/5-3-0.md b/content/momentum/changelog/5/5-3-0.md index 5766ca0b0..b163d299c 100644 --- a/content/momentum/changelog/5/5-3-0.md +++ b/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. |