Histogram.d.ts 9.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195
  1. export declare const NO_TAG = "NO TAG";
  2. export declare type BitBucketSize = 8 | 16 | 32 | 64 | "packed";
  3. export interface HistogramSummary {
  4. p50: number;
  5. p75: number;
  6. p90: number;
  7. p97_5: number;
  8. p99: number;
  9. p99_9: number;
  10. p99_99: number;
  11. p99_999: number;
  12. max: number;
  13. totalCount: number;
  14. }
  15. export default interface Histogram {
  16. /**
  17. * Flag to enable automatic resizing of the underlying array
  18. */
  19. autoResize: boolean;
  20. /**
  21. * The current highest trackable value. May change if autoresize flag is set to true
  22. */
  23. readonly highestTrackableValue: number;
  24. /**
  25. * Total count of all recorded values in the histogram
  26. */
  27. readonly totalCount: number;
  28. /**
  29. * The computed standard deviation of all recorded values in the histogram
  30. */
  31. readonly stdDeviation: number;
  32. /**
  33. * The computed mean value of all recorded values in the histogram
  34. */
  35. readonly mean: number;
  36. /**
  37. * Main percentiles, max value and total number of recorded values
  38. */
  39. readonly summary: HistogramSummary;
  40. /**
  41. * A (conservatively high) estimate of the Histogram's total footprint in bytes
  42. */
  43. readonly estimatedFootprintInBytes: number;
  44. readonly maxValue: number;
  45. readonly minNonZeroValue: number;
  46. readonly numberOfSignificantValueDigits: number;
  47. startTimeStampMsec: number;
  48. endTimeStampMsec: number;
  49. tag: string;
  50. /**
  51. * Record a value in the histogram
  52. *
  53. * @param value The value to be recorded
  54. * @throws may throw Error if value is exceeds highestTrackableValue
  55. */
  56. recordValue(value: number): void;
  57. /**
  58. * Record a value in the histogram (adding to the value's current count)
  59. *
  60. * @param value The value to be recorded
  61. * @param count The number of occurrences of this value to record
  62. * @throws ArrayIndexOutOfBoundsException (may throw) if value is exceeds highestTrackableValue
  63. */
  64. recordValueWithCount(value: number, count: number): void;
  65. /**
  66. * Get the value at a given percentile.
  67. * When the given percentile is > 0.0, the value returned is the value that the given
  68. * percentage of the overall recorded value entries in the histogram are either smaller than
  69. * or equivalent to. When the given percentile is 0.0, the value returned is the value that all value
  70. * entries in the histogram are either larger than or equivalent to.
  71. * <p>
  72. * Note that two values are "equivalent" in this statement if
  73. * {@link org.HdrHistogram.JsHistogram#valuesAreEquivalent} would return true.
  74. *
  75. * @param percentile The percentile for which to return the associated value
  76. * @return The value that the given percentage of the overall recorded value entries in the
  77. * histogram are either smaller than or equivalent to. When the percentile is 0.0, returns the
  78. * value that all value entries in the histogram are either larger than or equivalent to.
  79. */
  80. getValueAtPercentile(percentile: number): number;
  81. /**
  82. * Produce textual representation of the value distribution of histogram data by percentile. The distribution is
  83. * output with exponentially increasing resolution, with each exponentially decreasing half-distance containing
  84. * <i>dumpTicksPerHalf</i> percentile reporting tick points.
  85. *
  86. * @param printStream Stream into which the distribution will be output
  87. * <p>
  88. * @param percentileTicksPerHalfDistance The number of reporting points per exponentially decreasing half-distance
  89. * <p>
  90. * @param outputValueUnitScalingRatio The scaling factor by which to divide histogram recorded values units in
  91. * output
  92. * @param useCsvFormat Output in CSV format if true. Otherwise use plain text form.
  93. */
  94. outputPercentileDistribution(percentileTicksPerHalfDistance?: number, outputValueUnitScalingRatio?: number, useCsvFormat?: false): string;
  95. toJSON(): HistogramSummary;
  96. /**
  97. * Record a value in the histogram.
  98. * <p>
  99. * To compensate for the loss of sampled values when a recorded value is larger than the expected
  100. * interval between value samples, Histogram will auto-generate an additional series of decreasingly-smaller
  101. * (down to the expectedIntervalBetweenValueSamples) value records.
  102. * <p>
  103. * Note: This is a at-recording correction method, as opposed to the post-recording correction method provided
  104. * by {@link #copyCorrectedForCoordinatedOmission(long)}.
  105. * The two methods are mutually exclusive, and only one of the two should be be used on a given data set to correct
  106. * for the same coordinated omission issue.
  107. * <p>
  108. * See notes in the description of the Histogram calls for an illustration of why this corrective behavior is
  109. * important.
  110. *
  111. * @param value The value to record
  112. * @param expectedIntervalBetweenValueSamples If expectedIntervalBetweenValueSamples is larger than 0, add
  113. * auto-generated value records as appropriate if value is larger
  114. * than expectedIntervalBetweenValueSamples
  115. * @throws ArrayIndexOutOfBoundsException (may throw) if value is exceeds highestTrackableValue
  116. */
  117. recordValueWithExpectedInterval(value: number, expectedIntervalBetweenValueSamples: number): void;
  118. /**
  119. * Add the contents of another histogram to this one, while correcting the incoming data for coordinated omission.
  120. * <p>
  121. * To compensate for the loss of sampled values when a recorded value is larger than the expected
  122. * interval between value samples, the values added will include an auto-generated additional series of
  123. * decreasingly-smaller (down to the expectedIntervalBetweenValueSamples) value records for each count found
  124. * in the current histogram that is larger than the expectedIntervalBetweenValueSamples.
  125. *
  126. * Note: This is a post-recording correction method, as opposed to the at-recording correction method provided
  127. * by {@link #recordValueWithExpectedInterval(long, long) recordValueWithExpectedInterval}. The two
  128. * methods are mutually exclusive, and only one of the two should be be used on a given data set to correct
  129. * for the same coordinated omission issue.
  130. * by
  131. * <p>
  132. * See notes in the description of the Histogram calls for an illustration of why this corrective behavior is
  133. * important.
  134. *
  135. * @param otherHistogram The other histogram. highestTrackableValue and largestValueWithSingleUnitResolution must match.
  136. * @param expectedIntervalBetweenValueSamples If expectedIntervalBetweenValueSamples is larger than 0, add
  137. * auto-generated value records as appropriate if value is larger
  138. * than expectedIntervalBetweenValueSamples
  139. * @throws ArrayIndexOutOfBoundsException (may throw) if values exceed highestTrackableValue
  140. */
  141. addWhileCorrectingForCoordinatedOmission(otherHistogram: Histogram, expectedIntervalBetweenValueSamples: number): void;
  142. /**
  143. * Get a copy of this histogram, corrected for coordinated omission.
  144. * <p>
  145. * To compensate for the loss of sampled values when a recorded value is larger than the expected
  146. * interval between value samples, the new histogram will include an auto-generated additional series of
  147. * decreasingly-smaller (down to the expectedIntervalBetweenValueSamples) value records for each count found
  148. * in the current histogram that is larger than the expectedIntervalBetweenValueSamples.
  149. *
  150. * Note: This is a post-correction method, as opposed to the at-recording correction method provided
  151. * by {@link #recordValueWithExpectedInterval(long, long) recordValueWithExpectedInterval}. The two
  152. * methods are mutually exclusive, and only one of the two should be be used on a given data set to correct
  153. * for the same coordinated omission issue.
  154. * by
  155. * <p>
  156. * See notes in the description of the Histogram calls for an illustration of why this corrective behavior is
  157. * important.
  158. *
  159. * @param expectedIntervalBetweenValueSamples If expectedIntervalBetweenValueSamples is larger than 0, add
  160. * auto-generated value records as appropriate if value is larger
  161. * than expectedIntervalBetweenValueSamples
  162. * @return a copy of this histogram, corrected for coordinated omission.
  163. */
  164. copyCorrectedForCoordinatedOmission(expectedIntervalBetweenValueSamples: number): Histogram;
  165. /**
  166. * Add the contents of another histogram to this one.
  167. * <p>
  168. * As part of adding the contents, the start/end timestamp range of this histogram will be
  169. * extended to include the start/end timestamp range of the other histogram.
  170. *
  171. * @param otherHistogram The other histogram.
  172. * @throws (may throw) if values in fromHistogram's are
  173. * higher than highestTrackableValue.
  174. */
  175. add(otherHistogram: Histogram): void;
  176. /**
  177. * Subtract the contents of another histogram from this one.
  178. * <p>
  179. * The start/end timestamps of this histogram will remain unchanged.
  180. *
  181. * @param otherHistogram The other histogram.
  182. * @throws ArrayIndexOutOfBoundsException (may throw) if values in otherHistogram's are higher than highestTrackableValue.
  183. *
  184. */
  185. subtract(otherHistogram: Histogram): void;
  186. reset(): void;
  187. /**
  188. * Clean up memory associated to this histogram. Useful for WebAssembly implementations
  189. */
  190. destroy(): void;
  191. }
  192. export interface HistogramConstructor {
  193. new (lowestDiscernibleValue: number, highestTrackableValue: number, numberOfSignificantValueDigits: number): Histogram;
  194. }
  195. export declare const toSummary: (histogram: Histogram) => HistogramSummary;