Knowledge · Go

Go Unix timestamps (time.Time)

time.Now, time.Unix, UnixNano

now := time.Now().UTC()
fmt.Println(now.Unix())
fmt.Println(now.UnixMilli())
fmt.Println(now.UnixMicro())
fmt.Println(now.UnixNano())

t := time.Unix(1713794701, 500_000_000) // 500ms fractional
fmt.Println(t.UTC().Format(time.RFC3339Nano))

UnixNano cannot represent every instant near far-future dates because the result does not fit int64 — for extreme simulations, stay in time.Time or use big integers with explicit units.

time.Time vs int64

Passing bare int64 epochs across packages loses type safety. Wrapper types (type EpochSec int64) or protobuf google.protobuf.Timestamp communicate intent. Remember JSON marshaling: encoding/json on time.Time emits RFC3339 strings by default — customize if you need numeric epochs.

Parsing with time.Parse

const layout = "2006-01-02 15:04:05"
s := "2026-04-22 14:05:01"
t, err := time.ParseInLocation(layout, s, time.UTC)
if err != nil { log.Fatal(err) }

// Reference minute for fractional layouts
ref := "Jan 2 15:04:05.000000000 2006 MST"
t2, _ := time.Parse(ref, "Apr 22 14:05:01.123456789 2026 UTC")

time.Duration arithmetic

Durations are nanosecond-resolution signed values but should be created with helpers time.Hour * 3 to avoid magic numbers. Subtracting time.Time values uses monotonic data when available — do not persist durations derived from skewed wall adjustments as authoritative TTLs without context.

start := time.Now()
// work ...
elapsed := time.Since(start)
if elapsed > 1500*time.Millisecond {
    log.Println("slow path")
}

IANA zones with LoadLocation

loc, err := time.LoadLocation("America/New_York")
if err != nil { log.Fatal(err) }
local := time.Date(2026, time.April, 22, 9, 5, 0, 0, loc)
utc := local.UTC()
fmt.Println(utc.Unix())

Key takeaways

• Serialize with explicit intent: string RFC3339 vs int epoch.
• Watch JSON defaults — consumers may assume milliseconds.
• Monotonic subtraction differs from wall-only math after NTP steps.
• Load IANA zones from OS database; embed tzdata in static binaries when needed.
• Test DST boundaries with table-driven cases from zoneinfo.

Converter