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.