ISO 8601 & Logging for Humans

Last updated: 2025-10-16

Timestamps that sort naturally and read clearly across systems.

Why ISO 8601

Human‑readable and machine‑sortable, ideal for filenames and logs.

Examples

Best Practices

Pick UTC for storage; show local times in UI with clear labels.

Event Correlation

When aggregating traces, store timestamps in UTC with nanosecond precision if your stack supports it, then render user‑visible times in the viewer’s locale.

For CSV/JSON exports, include an explicit timezone column or ISO 8601 strings with Z or offset to preserve meaning outside the app.

Related: Time Zones & UTC

Filename & Folder Conventions

Use sortable patterns like 2025-10-16/incident-2025-10-16-21-05-09Z.md so directories and zip archives maintain chronology.

Avoid locale‑specific month/day names in filenames; numeric ISO style avoids confusion in international handoffs.

Also see: How it works · Cheat‑Sheet

Human Review Aids

In long timelines, add visual separators per day boundary and annotate offsets on any rows that deviate from the canonical zone.

Use a monospace font for timestamp columns to improve scannability when times share prefixes.

Schema Discipline

Define a shared schema field like 'event_time_utc' for canonical times and forbid locale-specific fields from being used as join keys. This prevents subtle bugs in analytics.

Adopt a versioned timestamp format policy in your technical standards repository and link it from contributor docs and code review checklists.

Archival & Long-Term Storage

For archives meant to last decades, store timestamps in UTC with full four-digit years and fixed-width fields to avoid Y2K-style surprises. Consider including the leap second policy in the archive’s README.

When compressing logs, preserve filename timestamps in ISO order so chronologies survive extraction and rehydration across systems.

Observability Dashboards

In dashboards, allow switching the display zone per panel but keep the query window in UTC to maintain consistent aggregation. Label the current zone prominently on the graph legend.

Add quick 'copy as ISO' actions next to timestamped events so operators can share precise moments without reformatting.

Data Contracts in Practice

Publish a JSON schema with required timestamp fields and example payloads. Strong schemas reduce ambiguous integrations.

Version your API when changing timestamp precision or allowed formats to avoid breaking existing consumers.

Reviewer Checklist

During code review, verify that new features never rely on locale parsing for canonical data paths.

Confirm storage uses UTC, and user-facing rendering applies the correct time zone with explicit labels.