TL;DR: Request IDs that look like UUIDs are not all interchangeable—v4 is random, v1 embeds time and node bits, v7 orders by time. Pick a version for correlation logs on purpose, and validate shape before blaming the tracer. Lightweight generators and validators in a masters tool help you spot mismatched IDs quickly.
Why “just use a UUID” is incomplete advice
Distributed systems need opaque IDs that collide rarely and paste cleanly into logs. UUID strings satisfy the paste test. They do not automatically satisfy sorting, privacy, or database index behavior. Teams that generate v1 in one service and v4 in another still “have UUIDs,” yet dashboards sort differently and security reviews ask different questions.
Version behaviors that affect operations
- Version 4: random (modulo version nibble). Great default for request IDs when you do not need time order. Indexes see random inserts—fine at moderate volume, sometimes painful at extreme write rates.
- Version 1: time-based with node information. Roughly sortable by time, but older layouts leaked MAC-derived bits. Prefer only with modern libraries and a clear privacy review.
- Version 7: Unix-time ordered designs gaining adoption for databases that want locality without exposing a MAC. Confirm library support before standardizing.
- Nil and max UUIDs: all-zero or all-one values often mean “unset.” Treat them as bugs in inbound headers, not real traffic.
String form versus binary form
Logs usually store the 8-4-4-4-12 hex form. Some buses ship 16 raw bytes. When you hash or truncate for display, document whether you truncate the string or the bytes—those are different prefixes.
Propagation rules beat clever generators
The hardest bugs are not collisions; they are lost correlation. Define:
- Which inbound header wins (
X-Request-Id,traceparent, vendor headers). - Whether gateways mint an ID when absent.
- Whether workers must continue the parent ID or create a child span ID.
A perfectly random v4 is useless if a reverse proxy overwrites it on every hop. Align with your tracing standard instead of inventing a parallel UUID culture.
Validation before escalation
When a partner says your ID is “invalid,” check:
- Correct length and hex alphabet.
- Version nibble matches the version you claim to send.
- Variant bits follow RFC expectations for that family.
- No uppercase/lowercase policy fights—most systems accept both; a few legacy ACLs do not.
Online validators catch transposed characters from OCR’d screenshots. Generators help reproduce a fresh ID in the same version when you need a synthetic fixture.
Database and privacy side effects
Random v4 primary keys can fragment B-trees; time-ordered IDs improve locality but can leak approximate request time to anyone who sees the ID. For public-facing tokens, prefer IDs that are not also sequential business numbers. For internal request correlation, time ordering is often worth it.
Never embed user email or account numbers inside a “UUID-shaped” string. Format compliance is not anonymity.
Practical team defaults
For new HTTP services, a sane baseline is: accept inbound W3C trace context when present; otherwise mint UUID v4 for X-Request-Id and log both. If your OLTP store struggles with random PKs, consider v7 for database keys while keeping v4 for external request IDs—two jobs, two identifiers.
When you need to mint or inspect samples outside the app container, use the UUID utilities on www.masters-tool.com, then delete fixtures that accidentally contain production IDs from shared notes.
Version choice is a design decision. Make it once, document it, and validate aggressively when systems disagree about what a “valid UUID” means.
