examples

NOTE: Examples are generated with the use of AI.

Sampling Library Examples

This directory contains practical examples demonstrating how to use the sampling library in various scenarios.

Running the Examples

go run .

Examples Overview

1. Default Example (default_example.go)

Demonstrates the simplest usage of the sampling library:

• Basic setup: Using NewSampler[string]() with default settings
• Default behavior: ZeroHash function + 100% sampling rate
• Practical setup: DefaultStringHasher + 50% sampling rate
• Key concepts: Hash validity, bucket distribution, empty string handling

Key takeaways:

• Default sampler uses ZeroHash (always returns 0, false) and 100% sampling
• DefaultStringHasher provides real hash values for meaningful sampling
• Empty strings have IsHashValid=false and Hash=0
• Bucket numbers (1-100) help verify hash distribution

2. Options Example (options_example.go)

Shows various configuration options and their effects:

• Low sampling rate: 5% sampling with DefaultStringHasher
• Skip invalid inputs: Using WithSkipInvalid() for empty strings
• Dynamic sampling: Custom max hash function based on input length
• Different data types: Byte slice sampling with BytesHasher

Key takeaways:

• WithStaticRate() sets fixed sampling percentages
• WithSkipInvalid() makes invalid inputs return false instead of true
• WithMaxHashFunc() enables dynamic sampling rates based on input
• Same configuration patterns work with different data types

3. Advanced Example (advanced_example.go)

Demonstrates advanced patterns with custom structs and business logic:

• Custom struct: User struct with multiple fields (ID, Username, Email, Premium)
• Custom hash function: userHasher combines multiple fields for comprehensive hashing
• Business logic integration: Premium users get 80% sampling, regular users get 20%
• Hash consistency: Same input always produces same hash and decision
• Performance comparison: Sample() vs SampleWithMeta() trade-offs

Key takeaways:

• Custom hash functions can combine multiple struct fields
• Business logic can be integrated via custom max hash functions
• Hash consistency ensures deterministic behavior
• Sample() is faster but SampleWithMeta() provides debugging information

4. Request Limiting Example (request_limiting_example.go)

Shows how to use sampling for request rate limiting in high-traffic systems:

• Custom Request struct: Represents HTTP requests with RequestId, Method, Path, UserAgent, Timestamp
• Request hash function: Uses RequestId for consistent sampling decisions
• Rate limiting: 30% sampling rate to reduce load on downstream services
• Real-world simulation: Processes 10 test requests, logs accepted ones, drops others
• Consistency demonstration: Same RequestId always gets same decision
• Distribution analysis: Shows how requests spread across hash buckets

Key takeaways:

• Deterministic rate limiting without shared state
• Works across distributed systems (multiple server instances)
• Fair distribution across different request types
• Easy to configure and adjust sampling rates
• No need for external rate limiting storage or counters

Code Structure

Each example file contains:

• Focused demonstration: One main concept per example
• Comprehensive output: Detailed tables showing hash values, decisions, and metadata
• Real-world scenarios: Practical use cases you might encounter
• Educational comments: Explanations of why certain patterns are used

Common Patterns

Basic Setup

sampler := sampling.NewSampler[string](
    sampling.WithHashFunc(hashing.DefaultStringHasher),
    sampling.WithStaticRate[string](0.1), // 10% sampling
)

Custom Hash Function

func customHasher(input MyStruct) (uint32, bool) {
    if !isValid(input) {
        return 0, false
    }
    composite := fmt.Sprintf("%v", input)
    return crc32.ChecksumIEEE([]byte(composite)), true
}

Dynamic Sampling Rate

dynamicMaxHash := func(input string) uint32 {
    rate := calculateRate(input) // Your business logic
    return hashing.ToMaxHash(rate, 1.0)
}

Understanding the Output

The examples show detailed output tables with these columns:

• Input: The value being sampled
• Take: Whether the sample should be included (true/false)
• Valid: Whether the hash function produced a valid hash
• Hash: The uint32 hash value generated
• MaxHash: The threshold value (computed from sampling rate)
• Bucket: Distribution bucket (1-100) for hash verification

Next Steps

After running these examples:

1. Experiment: Modify the sampling rates and see how it affects the results
2. Custom types: Try creating your own struct and hash function
3. Integration: Integrate sampling into your application's logging, metrics, or data processing
4. Performance: Benchmark Sample() vs SampleWithMeta() for your use case