Unix Epoch Timestamps, Timezones & Distributed Systems: Architecture & Best Practices

Timestamp Magnitude Cheat Sheet:
Digits   Precision      Example Value               Common Ecosystems
───────  ────────────   ──────────────────────────  ───────────────────────────
10       Seconds        1,771,408,000               POSIX, C, Python time(), PHP
13       Milliseconds   1,771,408,000,000           JavaScript Date.now(), Java
16       Microseconds   1,771,408,000,000,000       Python time_ns, Linux perf
19       Nanoseconds    1,771,408,000,000,000,000   Go UnixNano(), OpenTelemetry

// High-Precision Monotonic Latency Profiler in Node.js / TypeScript
export async function profileOperation<T>(
  operationName: string,
  task: () => Promise<T>
): Promise<{ result: T; durationMs: number; epochTimestamp: number }> {
  // Capture wall-clock timestamp for external database audit logging
  const epochTimestamp = Date.now();

  // Capture monotonic nanosecond clock for internal execution timing
  const startMonotonic = process.hrtime.bigint();

  try {
    const result = await task();
    const endMonotonic = process.hrtime.bigint();

    // Elapsed duration calculated in nanoseconds, converted to milliseconds
    const durationNs = endMonotonic - startMonotonic;
    const durationMs = Number(durationNs) / 1_000_000;

    console.log(`[${operationName}] Completed in ${durationMs.toFixed(3)}ms (Epoch: ${epochTimestamp})`);
    return { result, durationMs, epochTimestamp };
  } catch (error) {
    const endMonotonic = process.hrtime.bigint();
    const durationMs = Number(endMonotonic - startMonotonic) / 1_000_000;
    console.error(`[${operationName}] Failed after ${durationMs.toFixed(3)}ms`, error);
    throw error;
  }
}