Indicate timezone offset in formatted timestamps

[csabahenk]

The current convention in Glusterfs is to render time values to date strings in timezone UTC. This was adopted to avoid ambiguity regarding temporal data -- assuming all dates in logs, dumps, output are UTC, then it's well defined what time value is referred by them, regardless of the place of origin.

However, this is a leaky abstraction, as

• date strings without timezone specification are not absolute temporal data;
• which can be mitigated by a strong implicit precondition regarding the time offset so that dates are to be interpreted as of them;
• which is missing from Glusterfs, as the zone choice (local vs UTC) is at the whim of a command line option.

So while UTC is default, nothing indicates if Glusterfs has been started with local time.

The UTC convention is also confusing UI, because the general expectation is that locally originated time values are rendered as local time; therefore:

• time values that are directly facing users, like temporal data in status report of various components / entities are counter intuitive if implicitly rendered UTC;
• matching entries of Glusterfs logs with local non-Glusterfs logs (mostly implicitly local time) is error prone if Gluster times are implicitly UTC.

All these issue can be came over just by explicitly indicating time offset along dates.

[gluster-ant]

A patch https://review.gluster.org/24219 has been posted that references this issue.

Indicate timezone offsets in timestamps

Logs and other output carrying timestamps will have now timezone offsets indicated, eg.:

[2020-03-12 07:01:05.584482 +0000] I [MSGID: 106143] [glusterd-pmap.c:388:pmap_registry_remove] 0-pmap: removing brick (null) on port 49153

To this end,

• gf_time_fmt() now inserts timezone offset via %z strftime(3) template.

• A new utility function has been added, gf_time_fmt_tv(), that takes a struct timeval pointer (*tv) instead of a time_t value to specify the time. If tv->tv_usec is negative,

  gf_time_fmt_tv(... tv ...)

  is equivalent to

  gf_time_fmt(... tv->tv_sec ...)

  Otherwise it also inserts tv->tv_usec to the formatted string.

• Building timestamps of usec precision has been converted to gf_time_fmt_tv, which is necessary because the method of appending a period and the usec value to the end of the timestamp does not work if the timestamp has zone offset, but it's also beneficial in terms of eliminating repetition.
• The buffer passed to gf_time_fmt/gf_time_fmt_tv has been unified to be of GF_TIMESTR_SIZE size (256). We need slightly larger buffer space to accommodate the zone offset and it's preferable to use a buffer which is undisputedly large enough.

This change does not do the following:

• Retaining a method of timestamp creation without timezone offset. As to my understanding we don't need such backward compatibility as the code just emits timestamps to logs and other diagnostic texts, and doesn't do any later processing on them that would rely on their format. An exception to this, ie. a case where timestamp is built for internal use, is graph.c:fill_uuid(). As far as I can see, what matters in that case is the uniqueness of the produced string, not the format.
• Implementing a single-token (space free) timestamp format. While some timestamp formats used to be single-token, now all of them will include a space preceding the offset indicator. Again, I did not see a use case where this could be significant in terms of representation.
• Moving the codebase to a single unified timestamp format and dropping the fmt argument of gf_time_fmt/gf_time_fmt_tv. While the gf_timefmt_FT format is almost ubiquitous, thee are a few cases where different formats are used. I'm not convinced there is any reason to not use gf_timefmt_FT in those cases too, but I did not want to make a decision in this regard.

Change-Id: I0af73ab5d490cca7ed8d07a2ce7ac22a6df2920a Updates: #837 Signed-off-by: Csaba Henk csaba@redhat.com

[amarts]

Both Issue description, and also the patch commit message are detailed to provide both DesignSpec, and Documentation. hence the Label :-) Thanks.

[crkinard]

Yay. The log files now specify what offset from UTC the entries are. Kind of moot when you can't change the offset of the log files at all so they will always be UTC. Everything else logs in local time going by the system TZ but this software because the dev's seem to absolute refuse to do this.