Format timestamps

After parsing timestamps to datetime, you usually need to convert them back to a string before forwarding the data to its 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 an event 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 events 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 an event 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 event 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 event 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 an event 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 event 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 event 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."
}