1 | "use strict";
|
---|
2 | /*
|
---|
3 | * This is a TypeScript port of the original Java version, which was written by
|
---|
4 | * Gil Tene as described in
|
---|
5 | * https://github.com/HdrHistogram/HdrHistogram
|
---|
6 | * and released to the public domain, as explained at
|
---|
7 | * http://creativecommons.org/publicdomain/zero/1.0/
|
---|
8 | */
|
---|
9 | Object.defineProperty(exports, "__esModule", { value: true });
|
---|
10 | const HistogramBuilder_1 = require("./HistogramBuilder");
|
---|
11 | /**
|
---|
12 | * Records integer values, and provides stable interval {@link Histogram} samples from
|
---|
13 | * live recorded data without interrupting or stalling active recording of values. Each interval
|
---|
14 | * histogram provided contains all value counts accumulated since the previous interval histogram
|
---|
15 | * was taken.
|
---|
16 | * <p>
|
---|
17 | * This pattern is commonly used in logging interval histogram information while recording is ongoing.
|
---|
18 | * <p>
|
---|
19 | * {@link Recorder} supports concurrent
|
---|
20 | * {@link Recorder#recordValue} or
|
---|
21 | * {@link Recorder#recordValueWithExpectedInterval} calls.
|
---|
22 | *
|
---|
23 | */
|
---|
24 | class Recorder {
|
---|
25 | /**
|
---|
26 | * Construct an auto-resizing {@link Recorder} with a lowest discernible value of
|
---|
27 | * 1 and an auto-adjusting highestTrackableValue. Can auto-resize up to track values up to Number.MAX_SAFE_INTEGER.
|
---|
28 | *
|
---|
29 | * @param histogramBuildRequest parameters used to build histograms while using this recorder.
|
---|
30 | * @param clock (for testing purpose) an action that give current time in ms since 1970
|
---|
31 | */
|
---|
32 | constructor(histogramBuildRequest = HistogramBuilder_1.defaultRequest, clock = () => new Date().getTime()) {
|
---|
33 | this.histogramBuildRequest = histogramBuildRequest;
|
---|
34 | this.clock = clock;
|
---|
35 | this.activeHistogram = HistogramBuilder_1.build(this.histogramBuildRequest);
|
---|
36 | Recorder.idGenerator++;
|
---|
37 | this.activeHistogram.containingInstanceId = Recorder.idGenerator;
|
---|
38 | this.activeHistogram.startTimeStampMsec = clock();
|
---|
39 | }
|
---|
40 | /**
|
---|
41 | * Record a value in the histogram
|
---|
42 | *
|
---|
43 | * @param value The value to be recorded
|
---|
44 | * @throws may throw Error if value is exceeds highestTrackableValue
|
---|
45 | */
|
---|
46 | recordValue(value) {
|
---|
47 | this.activeHistogram.recordValue(value);
|
---|
48 | }
|
---|
49 | /**
|
---|
50 | * Record a value in the histogram (adding to the value's current count)
|
---|
51 | *
|
---|
52 | * @param value The value to be recorded
|
---|
53 | * @param count The number of occurrences of this value to record
|
---|
54 | * @throws ArrayIndexOutOfBoundsException (may throw) if value is exceeds highestTrackableValue
|
---|
55 | */
|
---|
56 | recordValueWithCount(value, count) {
|
---|
57 | this.activeHistogram.recordValueWithCount(value, count);
|
---|
58 | }
|
---|
59 | /**
|
---|
60 | * Record a value
|
---|
61 | * <p>
|
---|
62 | * To compensate for the loss of sampled values when a recorded value is larger than the expected
|
---|
63 | * interval between value samples, Histogram will auto-generate an additional series of decreasingly-smaller
|
---|
64 | * (down to the expectedIntervalBetweenValueSamples) value records.
|
---|
65 | * <p>
|
---|
66 | * See related notes {@link Histogram#recordValueWithExpectedInterval(long, long)}
|
---|
67 | * for more explanations about coordinated omission and expected interval correction.
|
---|
68 | * *
|
---|
69 | * @param value The value to record
|
---|
70 | * @param expectedIntervalBetweenValueSamples If expectedIntervalBetweenValueSamples is larger than 0, add
|
---|
71 | * auto-generated value records as appropriate if value is larger
|
---|
72 | * than expectedIntervalBetweenValueSamples
|
---|
73 | * @throws ArrayIndexOutOfBoundsException (may throw) if value is exceeds highestTrackableValue
|
---|
74 | */
|
---|
75 | recordValueWithExpectedInterval(value, expectedIntervalBetweenValueSamples) {
|
---|
76 | this.activeHistogram.recordValueWithExpectedInterval(value, expectedIntervalBetweenValueSamples);
|
---|
77 | }
|
---|
78 | /**
|
---|
79 | * Get an interval histogram, which will include a stable, consistent view of all value counts
|
---|
80 | * accumulated since the last interval histogram was taken.
|
---|
81 | * <p>
|
---|
82 | * {@link Recorder#getIntervalHistogram(Histogram histogramToRecycle)
|
---|
83 | * getIntervalHistogram(histogramToRecycle)}
|
---|
84 | * accepts a previously returned interval histogram that can be recycled internally to avoid allocation
|
---|
85 | * and content copying operations, and is therefore significantly more efficient for repeated use than
|
---|
86 | * {@link Recorder#getIntervalHistogram()} and
|
---|
87 | * {@link Recorder#getIntervalHistogramInto getIntervalHistogramInto()}. The provided
|
---|
88 | * {@code histogramToRecycle} must
|
---|
89 | * be either be null or an interval histogram returned by a previous call to
|
---|
90 | * {@link Recorder#getIntervalHistogram(Histogram histogramToRecycle)
|
---|
91 | * getIntervalHistogram(histogramToRecycle)} or
|
---|
92 | * {@link Recorder#getIntervalHistogram()}.
|
---|
93 | * <p>
|
---|
94 | * NOTE: The caller is responsible for not recycling the same returned interval histogram more than once. If
|
---|
95 | * the same interval histogram instance is recycled more than once, behavior is undefined.
|
---|
96 | * <p>
|
---|
97 | * Calling {@link Recorder#getIntervalHistogram(Histogram histogramToRecycle)
|
---|
98 | * getIntervalHistogram(histogramToRecycle)} will reset the value counts, and start accumulating value
|
---|
99 | * counts for the next interval
|
---|
100 | *
|
---|
101 | * @param histogramToRecycle a previously returned interval histogram that may be recycled to avoid allocation and
|
---|
102 | * copy operations.
|
---|
103 | * @return a histogram containing the value counts accumulated since the last interval histogram was taken.
|
---|
104 | */
|
---|
105 | getIntervalHistogram(histogramToRecycle) {
|
---|
106 | if (histogramToRecycle) {
|
---|
107 | const histogramToRecycleWithId = histogramToRecycle;
|
---|
108 | if (histogramToRecycleWithId.containingInstanceId !==
|
---|
109 | this.activeHistogram.containingInstanceId) {
|
---|
110 | throw "replacement histogram must have been obtained via a previous getIntervalHistogram() call from this Recorder";
|
---|
111 | }
|
---|
112 | }
|
---|
113 | this.inactiveHistogram = histogramToRecycle;
|
---|
114 | this.performIntervalSample();
|
---|
115 | const sampledHistogram = this.inactiveHistogram;
|
---|
116 | this.inactiveHistogram = null; // Once we expose the sample, we can't reuse it internally until it is recycled
|
---|
117 | return sampledHistogram;
|
---|
118 | }
|
---|
119 | /**
|
---|
120 | * Place a copy of the value counts accumulated since accumulated (since the last interval histogram
|
---|
121 | * was taken) into {@code targetHistogram}.
|
---|
122 | *
|
---|
123 | * Calling {@link Recorder#getIntervalHistogramInto getIntervalHistogramInto()} will reset
|
---|
124 | * the value counts, and start accumulating value counts for the next interval.
|
---|
125 | *
|
---|
126 | * @param targetHistogram the histogram into which the interval histogram's data should be copied
|
---|
127 | */
|
---|
128 | getIntervalHistogramInto(targetHistogram) {
|
---|
129 | this.performIntervalSample();
|
---|
130 | if (this.inactiveHistogram) {
|
---|
131 | targetHistogram.add(this.inactiveHistogram);
|
---|
132 | targetHistogram.startTimeStampMsec = this.inactiveHistogram.startTimeStampMsec;
|
---|
133 | targetHistogram.endTimeStampMsec = this.inactiveHistogram.endTimeStampMsec;
|
---|
134 | }
|
---|
135 | }
|
---|
136 | /**
|
---|
137 | * Reset any value counts accumulated thus far.
|
---|
138 | */
|
---|
139 | reset() {
|
---|
140 | this.activeHistogram.reset();
|
---|
141 | this.activeHistogram.startTimeStampMsec = this.clock();
|
---|
142 | }
|
---|
143 | performIntervalSample() {
|
---|
144 | if (!this.inactiveHistogram) {
|
---|
145 | this.inactiveHistogram = HistogramBuilder_1.build(this.histogramBuildRequest);
|
---|
146 | this.inactiveHistogram.containingInstanceId = this.activeHistogram.containingInstanceId;
|
---|
147 | }
|
---|
148 | this.inactiveHistogram.reset();
|
---|
149 | const tempHistogram = this.activeHistogram;
|
---|
150 | this.activeHistogram = this.inactiveHistogram;
|
---|
151 | this.inactiveHistogram = tempHistogram;
|
---|
152 | const currentTimeInMs = this.clock();
|
---|
153 | this.inactiveHistogram.endTimeStampMsec = currentTimeInMs;
|
---|
154 | this.activeHistogram.startTimeStampMsec = currentTimeInMs;
|
---|
155 | }
|
---|
156 | /**
|
---|
157 | * Release memory associated to this recorder by destroying
|
---|
158 | * histograms used under the cover.
|
---|
159 | * Useful when webassembly histograms are used.
|
---|
160 | */
|
---|
161 | destroy() {
|
---|
162 | var _a;
|
---|
163 | this.activeHistogram.destroy();
|
---|
164 | (_a = this.inactiveHistogram) === null || _a === void 0 ? void 0 : _a.destroy();
|
---|
165 | }
|
---|
166 | }
|
---|
167 | Recorder.idGenerator = 0;
|
---|
168 | exports.default = Recorder;
|
---|
169 | //# sourceMappingURL=Recorder.js.map |
---|