Module trace_id

sentinel_proxy

Module trace_id 

Source
Expand description

TinyFlake: Operator-friendly Trace ID Generation

TinyFlake is Sentinel’s default trace ID format, designed for operators who need to copy, paste, and correlate request IDs across logs, dashboards, and support tickets.

§Format

k7BxR3nVp2Ym
└──┘└───────┘
 3ch   8ch
 time  random
  • 11 characters total (vs 36 for UUID)
  • Base58 encoded (excludes confusing chars: 0, O, I, l)
  • Time-prefixed for chronological sorting in logs
  • No dashes for easy double-click selection in terminals

§Comparison with Snowflake

TinyFlake is inspired by Twitter’s Snowflake but differs in key ways:

FeatureSnowflakeTinyFlake
Length19 digits11 chars
EncodingDecimalBase58
CoordinationRequires worker IDsNone (random)
Time resolutionMillisecondsSeconds
UniquenessGuaranteedStatistical

§Collision Probability

The 8-character random component provides 58^8 ≈ 128 trillion combinations. Using the birthday paradox formula:

  • At 1,000 req/sec: 50% collision chance after ~11 million requests (~3 hours)
  • At 10,000 req/sec: 50% collision chance after ~11 million requests (~18 minutes)
  • At 100,000 req/sec: 50% collision chance after ~11 million requests (~2 minutes)

However, collisions only matter within the same second (due to time prefix). Within a single second at 100k req/sec, collision probability is ~0.004%.

For guaranteed uniqueness, use UUID format instead.

§Configuration

In sentinel.kdl:

server {
    trace-id-format "tinyflake"  // default, or "uuid"
}

§Examples

use sentinel_proxy::trace_id::{generate_tinyflake, generate_uuid, generate_for_format, TraceIdFormat};

// Generate TinyFlake (default)
let id = generate_tinyflake();
assert_eq!(id.len(), 11);

// Generate UUID
let uuid = generate_uuid();
assert_eq!(uuid.len(), 36);

// Generate based on format config
let id = generate_for_format(TraceIdFormat::TinyFlake);

§Header Propagation

TinyFlake respects incoming trace headers in this order:

  1. X-Trace-Id
  2. X-Correlation-Id
  3. X-Request-Id

If an incoming request has any of these headers, that value is used instead of generating a new ID. This allows distributed tracing across services.

Enums§

TraceIdFormat
Trace ID format selection.

Constants§

TINYFLAKE_LENGTH
TinyFlake ID length

Functions§

generate_for_format
Generate a trace ID using the specified format
generate_tinyflake
Generate a TinyFlake trace ID
generate_uuid
Generate a UUID v4 trace ID