Architecture Decision Record

Active theme: Light

← 決策記錄例子

時間戳格式

內容:

摘要

問題

我哋想可以透過時間戳,以及透過一個喺我哋所有系統同第三方系統都運作良好嘅一致時間戳格式,追蹤事情幾時發生。

我哋同擁有不同時間戳格式嘅系統互動:

  • JSON 訊息冇原生時間戳格式,所以我哋需要揀選點樣將時間戳轉換成字串,以及將字串轉換成時間戳,即係點樣序列化/反序列化。

  • 部分應用程式設定為使用本地時間,而唔係 UTC 時間。對於必須配合本地時間嘅項目(例如觸發基於本地時間事件嘅項目),呢點可以好方便。

  • 部分系統有不同嘅時間精度需求同能力,例如使用秒對毫秒對納秒嘅時間解析度。例如,Linux 作業系統嘅 date 命令預設時間精度係秒,而 Nasdaq 證券交易所預設要求納秒嘅時間精度。

決策

我哋揀選納秒精度嘅 ISO 8601 時間戳標準格式,具體係「YYYY-MM-DDTHH:MM:SS.NNNNNNNNNZ」。

呢個格式顯示年、月、日、時、分、秒、納秒,以及 Zulu 時區,又稱 UTC、GMT。

狀態

已決定。

詳情

假設

我哋需要處理呢啲時間戳文字字串,由時間戳轉換成字串(又稱序列化),以及由字串轉換成時間戳(又稱反序列化)。

我哋想要一個一般易用、易轉換,而且人容易閱讀嘅格式。

我哋想同我哋無法控制嘅廣泛外部系統兼容,例如分析系統、資料庫系統、金融系統。

限制

部分系統有時間精度限制。例如,macOS 作業系統嘅 date 命令可以列印秒級時間精度,但唔可以列印納秒。

立場

我哋考慮過一系列選項:

  • Unix epoch,即係一個遞增嘅數字。

  • 精簡文字格式「YYYYMMDDTHHMMSSNNNNNNNNN」。

  • 使用本地時區對 UTC 時區。

論據

對於典型用途,我哋重視人類易讀易寫,多過原始速度/大小。

對於典型用途,我哋想要一個喺機器系統運作良好,亦適合人手操作嘅格式,例如撰寫樣本數據、閱讀 JSON 輸出、用 grep 搜尋日誌檔案等。

對於非典型用途(例如高效能運算),我哋預期會想透過將文字轉換成更快嘅格式(例如程式語言內置嘅日期物件類型),去優化我哋揀選嘅任何文字格式。所以對 HPC 嚟講,文字格式並不太重要。

影響

我哋各種文字系統同時間系統將會趨向採用呢個格式。

相關

相關決策

我哋可能亦想要一個快速/簡單嘅方法追蹤時間差,又稱持續時間。用 Unix epoch 時間戳就好容易做到。

相關需求

我哋可能想調整決策,例如如果我哋有針對特定日誌訊息戳記(例如 Splunk、Sumo、ELK 等)嘅相關需求。

相關工件

語言格式化器同解析器:

Rosetta Code 例子:

SixArm 例子:

相關原則

容易回復。我哋可以相當容易改用其他格式,例如 Unix epoch。

延遲過早優化。對於典型用途,我哋唔太在意少少額外字元,例如使用連字號同冒號嘅格式。

備註

喺呢度加入備註。