Format timestamps

After parsing timestamps to datetime, you usually need to convert them back to a string before forwarding the logs to their destination. In most cases, the output configuration does the conversion automatically.

Use the default timestamp format

Data conversion modules like xm_json and xm_syslog have built-in date and time formatting. When you use these modules' functions and procedures, they automatically generate timestamps in the module’s default format.

Example 1. Using the default timestamp formatting

Consider a log record with an $EventTime datetime field and a $Message field. The table below shows the $EventTime value stored internally as microseconds since the Unix epoch.

Table 1. Log record sample
Field	Value
$EventTime	1708630736221331
$Message	EXT4-fs (dm-0): mounted filesystem with ordered data mode.

This configuration uses the to_json() procedure of the xm_json module to output log records in JSON format.

nxlog.conf

<Extension json>
    Module    xm_json
</Extension>

<Output file>
    Module    om_file
    File      '/path/to/output/file'
    Exec      to_json();
</Output>

Since the configuration does not specify a format for datetime values, it will output the $EventTime field in the default DateFormat, i.e., YYYY-MM-DDThh:mm:ss.sTZ in local time.

Output sample

{
  "EventTime": "2024-02-22T20:38:56.221331+01:00",
  "Message": "EXT4-fs (dm-0): mounted filesystem with ordered data mode."
}

Use a custom timestamp format

You can use the strftime() function to explicitly convert a datetime value to a string in one of the supported custom date and time formats.

Example 2. Converting a timestamp to a string

Consider a log record with an $EventTime datetime field and a $Message field. The table below shows the $EventTime value stored internally as microseconds since the Unix epoch.

Table 2. Log record sample
Field	Value
$EventTime	1708636179075845
$Message	EXT4-fs (dm-0): mounted filesystem with ordered data mode.

This configuration uses the strftime() function to convert $EventTime to a string in the local time zone. It then converts the record to JSON for demonstration purposes.

nxlog.conf

<Extension json>
    Module    xm_json
</Extension>

<Output file>
    Module    om_file
    File      '/path/to/output/file'
    <Exec>
        $EventTime = strftime($EventTime, '%Y-%m-%dT%H:%M:%S%z');  (1)
        to_json();
    </Exec>
</Output>

1	`%Y-%m-%dT%H:%M:%S%z` is one of the formats that the C `strftime(3)` function supports.

The following JSON object shows the same log record after NXLog Agent processed it.

Output sample

{
  "EventTime": "2024-02-22T22:09:39+0100",
  "Message": "EXT4-fs (dm-0): mounted filesystem with ordered data mode."
}

NXLog Agent supports additional format strings to the stock C strftime(3) function—for example, date and time formats with fractional seconds and in UTC. See the strftime() documentation in the NXLog Agent Reference Manual for the supported formats.

Example 3. Converting a timestamp to a string with fractional seconds

Consider a log record with an $EventTime datetime field and a $Message field. The table below shows the $EventTime value stored internally as microseconds since the Unix epoch.

Table 3. Log record sample
Field	Value
$EventTime	1708637563256720
$Message	EXT4-fs (dm-0): mounted filesystem with ordered data mode.

This configuration uses the strftime() function to convert $EventTime to a string in UTC, regardless of the host’s timezone. It then converts the logs to JSON for demonstration purposes.

nxlog.conf

<Extension json>
    Module    xm_json
</Extension>

<Output file>
    Module    om_file
    File      '/path/to/output/file'
    <Exec>
	    $EventTime = strftime($EventTime, 'YYYY-MM-DDThh:mm:ss.sUTC');  (1)
	    to_json();
    </Exec>
</Output>

1	`YYYY-MM-DDThh:mm:ss.sUTC` is an NXLog Agent-specific format that supports fractional seconds.

The following JSON object shows the same log record after NXLog Agent processed it.

Output sample

{
  "EventTime": "2024-02-22T21:32:43.256720Z",
  "Message": "EXT4-fs (dm-0): mounted filesystem with ordered data mode."
}