0
# HdrHistogram
1

2
HdrHistogram provides High Dynamic Range (HDR) histograms for recording and analyzing value distributions with configurable precision across wide dynamic ranges. It enables accurate measurement of latency, response times, and other metrics without losing precision due to quantization effects.
3

4
## Package Information
5

6
- **Package Name**: org.hdrhistogram:HdrHistogram
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Version**: 2.2.2
10
- **Installation**: Add Maven dependency
11

12
```xml
13
<dependency>
14
    <groupId>org.hdrhistogram</groupId>
15
    <artifactId>HdrHistogram</artifactId>
16
    <version>2.2.2</version>
17
</dependency>
18
```
19

20
## Core Imports
21

22
```java { .api }
23
// Core histogram classes
24
import org.HdrHistogram.Histogram;
25
import org.HdrHistogram.ConcurrentHistogram;
26
import org.HdrHistogram.DoubleHistogram;
27

28
// Base classes and interfaces
29
import org.HdrHistogram.AbstractHistogram;
30
import org.HdrHistogram.ValueRecorder;
31
import org.HdrHistogram.DoubleValueRecorder;
32

33
// Recorder classes for continuous recording
34
import org.HdrHistogram.Recorder;
35
import org.HdrHistogram.SingleWriterRecorder;
36

37
// Iterator classes for data analysis
38
import org.HdrHistogram.PercentileIterator;
39
import org.HdrHistogram.HistogramIterationValue;
40
```
41

42
## Basic Usage
43

44
```java
45
import org.HdrHistogram.Histogram;
46

47
// Create histogram with 3 significant digits precision
48
// Can track values from 1 to 2^63 with auto-resizing
49
Histogram histogram = new Histogram(3);
50

51
// Record values (latencies in microseconds)
52
histogram.recordValue(1234);  // 1.234ms latency
53
histogram.recordValue(5678);  // 5.678ms latency
54
histogram.recordValue(987);   // 0.987ms latency
55

56
// Analyze recorded data
57
long count = histogram.getTotalCount();           // Total samples: 3
58
double mean = histogram.getMean();                // Mean value
59
long p95 = histogram.getValueAtPercentile(95.0);  // 95th percentile
60
long p99 = histogram.getValueAtPercentile(99.0);  // 99th percentile
61
long max = histogram.getMaxValue();               // Maximum value
62

63
// Output percentile distribution
64
histogram.outputPercentileDistribution(System.out, 1.0);
65
```
66

67
## Architecture
68

69
HdrHistogram uses a logarithmic bucket structure that provides:
70

71
- **Constant space complexity** regardless of data range
72
- **Constant time complexity** for recording and percentile queries  
73
- **Configurable precision** via significant digits parameter
74
- **Wide dynamic range** supporting values from 1 to 2^63
75
- **Memory efficiency** through various storage optimizations
76

77
### Key Design Concepts
78

79
**Precision Control**: The `numberOfSignificantValueDigits` parameter (0-5) controls measurement precision. Higher values provide more accurate percentiles at the cost of memory usage.
80

81
**Value Equivalence**: Values are grouped into equivalent ranges where all values in a range are considered equivalent for analysis purposes. This enables the constant space complexity.
82

83
**Coordinated Omission Correction**: Methods like `recordValueWithExpectedInterval()` help correct for coordinated omission where measurements miss high values due to system pauses.
84

85
**Thread Safety Models**: Multiple implementations provide different thread safety guarantees from single-threaded to fully concurrent access.
86

87
## Capabilities
88

89
### Core Histogram Operations
90

91
Basic histogram recording and analysis functionality for integer values.
92

93
```java { .api }
94
// AbstractHistogram - Base functionality
95
void recordValue(long value);
96
void recordValueWithCount(long value, long count);
97
void recordValueWithExpectedInterval(long value, long expectedInterval);
98
long getTotalCount();
99
double getMean();
100
long getValueAtPercentile(double percentile);
101
void reset();
102
```
103

104
[Core Histogram Operations](./core-operations.md)
105

106
### Concurrent and Thread-Safe Variants
107

108
Thread-safe histogram implementations for multi-threaded environments.
109

110
```java { .api }
111
// Thread-safe histogram variants
112
AtomicHistogram atomicHist = new AtomicHistogram(highestTrackableValue, 3);
113
ConcurrentHistogram concurrentHist = new ConcurrentHistogram(3);
114
SynchronizedHistogram syncHist = new SynchronizedHistogram(3);
115
```
116

117
[Concurrent Histogram Variants](./concurrent-histograms.md)
118

119
### Specialized Memory-Optimized Variants
120

121
Memory-efficient histogram implementations for specific use cases.
122

123
```java { .api }
124
// Memory-optimized variants
125
IntCountsHistogram intHist = new IntCountsHistogram(highestTrackableValue, 3);
126
PackedHistogram packedHist = new PackedHistogram(highestTrackableValue, 3);
127
ShortCountsHistogram shortHist = new ShortCountsHistogram(highestTrackableValue, 3);
128
```
129

130
[Specialized Histogram Variants](./specialized-variants.md)
131

132
### Double Value Histograms
133

134
Histogram implementations for recording floating-point values.
135

136
```java { .api }
137
// Double value histograms
138
DoubleHistogram doubleHist = new DoubleHistogram(3);
139
ConcurrentDoubleHistogram concurrentDouble = new ConcurrentDoubleHistogram(3);
140
PackedDoubleHistogram packedDouble = new PackedDoubleHistogram(3);
141
PackedConcurrentDoubleHistogram packedConcurrentDouble = new PackedConcurrentDoubleHistogram(3);
142
void recordValue(double value);
143
double getValueAtPercentile(double percentile);
144
```
145

146
[Double Value Histograms](./double-histograms.md)
147

148
### Recorder Classes for Interval Measurements
149

150
Continuous recording with interval histogram snapshots for monitoring scenarios.
151

152
```java { .api }
153
// Recorder classes
154
Recorder recorder = new Recorder(3);
155
SingleWriterRecorder singleWriter = new SingleWriterRecorder(3);
156
Histogram getIntervalHistogram();
157
Histogram getIntervalHistogram(Histogram histogramToRecycle);
158
```
159

160
[Recorder Classes](./recorders.md)
161

162
### Iterator Patterns and Data Analysis
163

164
Comprehensive iteration and analysis capabilities for detailed data exploration.
165

166
```java { .api }
167
// Iterator types
168
PercentileIterator percentileIter = new PercentileIterator(histogram, 5);
169
LinearIterator linearIter = new LinearIterator(histogram, 1000);
170
LogarithmicIterator logIter = new LogarithmicIterator(histogram, 1000, 2.0);
171
```
172

173
[Iterator Patterns and Analysis](./iterators.md)
174

175
### Serialization and Persistence
176

177
Encoding, decoding, and log processing for data persistence and exchange.
178

179
```java { .api }
180
// Serialization support
181
int encodeIntoByteBuffer(ByteBuffer buffer);
182
int encodeIntoCompressedByteBuffer(ByteBuffer buffer, int compressionLevel);
183
static Histogram decodeFromByteBuffer(ByteBuffer buffer, long minBarForHighestTrackableValue);
184
```
185

186
[Serialization and Persistence](./serialization.md)
187

188
### Utility and Helper Classes
189

190
Supporting classes for synchronization, encoding, and specialized operations.
191

192
```java { .api }
193
// Utility classes
194
WriterReaderPhaser phaser = new WriterReaderPhaser();
195
Base64Helper.printBase64Binary(bytes);
196
ZigZagEncoding.putLong(buffer, value);
197
```
198

199
[Utility Classes](./utilities.md)
200

201
## Common Patterns
202

203
### Single-Threaded Recording
204
Use `Histogram` or `DoubleHistogram` for simple scenarios without concurrent access requirements.
205

206
### Multi-Threaded Recording
207
Use `ConcurrentHistogram` for wait-free recording with multiple threads, or `SynchronizedHistogram` for simpler synchronized access.
208

209
### Continuous Monitoring
210
Use `Recorder` or `SingleWriterRecorder` to continuously record values while periodically extracting interval histograms for analysis.
211

212
### Memory Optimization
213
Use `PackedHistogram` for sparse data distributions or `IntCountsHistogram`/`ShortCountsHistogram` when count limits allow smaller data types.
214

215
### Coordinated Omission Correction
216
Use `recordValueWithExpectedInterval()` methods when measurements might miss high values due to coordinated system pauses.