Build a traceable evidence timeline
Order observations by actual UTC instants and keep their source identifiers.
Put observations on one clock
A timeline connects events from different exports. Normalize timestamps into UTC before ordering them. Keep fractional seconds when present: rounding an event can change which side of a window boundary it belongs on.
Sort by parsed datetime and then by event ID. The secondary key gives a deterministic order for simultaneous events without suggesting that the alphabetical ID proves causality. Two observations at the same instant can remain tied in your interpretation even when a table needs one row first.
Keep the route back to evidence
Every timeline row includes an ID and source. A timestamp without provenance is hard to verify. The output also includes an action label supplied by the event, such as logon_failure or email_received. Do not infer a click or compromise from a message merely existing in a mailbox.
This function rejects duplicate event IDs and naive timestamps. Those inputs would make the timeline ambiguous. A collection stage can instead quarantine duplicate records and pass only validated events to this function; the capstone uses that separation.
Use a new dictionary for the normalized output. Original exports retain their timestamps and offsets, while the report has a consistent UTC representation ending in Z. The checks include equivalent offsets, fractional seconds, and simultaneous events to exercise the details that a simple string sort misses.
from datetime import datetime, timezone
value = datetime.fromisoformat("2026-04-01T10:00:00.500+01:00")
print(value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z"))
Put it into practice.
Define build_timeline(events). Accept id, timestamp, source and action. Require unique IDs and aware ISO timestamps; raise ValueError otherwise. Return new dictionaries with those four fields, UTC timestamp formatted with datetime.isoformat().replace("+00:00", "Z"), preserving fractional precision. Sort by actual instant then ID. Keep inputs unchanged.
See an explained solution
from datetime import datetime, timezone
def build_timeline(events):
rows, seen = [], set()
for event in events:
if event["id"] in seen:
raise ValueError("Duplicate event ID")
seen.add(event["id"])
moment = datetime.fromisoformat(event["timestamp"])
if moment.tzinfo is None:
raise ValueError("Timestamp needs an offset")
moment = moment.astimezone(timezone.utc)
row = {"id": event["id"], "timestamp": moment.isoformat().replace("+00:00", "Z"), "source": event["source"], "action": event["action"]}
rows.append((moment, event["id"], row))
return [row for _, _, row in sorted(rows, key=lambda entry: (entry[0], entry[1]))]
Sorting uses datetime values rather than formatted text. The report preserves source fields and fractional precision, with a stable ID tie breaker.