@tinyshed/tinystore 0.1.0-rc.4 → 0.1.0-rc.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (122) hide show
  1. package/README.md +37 -37
  2. package/bin/tinystore.js +12 -1
  3. package/dist/backup.d.ts +33 -0
  4. package/dist/backup.js +49 -0
  5. package/dist/blobs.d.ts +160 -79
  6. package/dist/blobs.js +510 -217
  7. package/dist/channels.d.ts +90 -0
  8. package/dist/channels.js +291 -0
  9. package/dist/clock.js +3 -3
  10. package/dist/config.d.ts +209 -86
  11. package/dist/config.js +581 -538
  12. package/dist/connection.d.ts +64 -2
  13. package/dist/connection.js +201 -16
  14. package/dist/console.d.ts +27 -3
  15. package/dist/console.js +165 -12
  16. package/dist/dotenv.d.ts +7 -0
  17. package/dist/dotenv.js +79 -0
  18. package/dist/errors.d.ts +61 -1
  19. package/dist/errors.js +81 -1
  20. package/dist/handles.d.ts +44 -2
  21. package/dist/handles.js +81 -2
  22. package/dist/index.d.ts +17 -11
  23. package/dist/index.js +5 -3
  24. package/dist/instruments.d.ts +177 -0
  25. package/dist/instruments.js +819 -0
  26. package/dist/jobs.d.ts +335 -239
  27. package/dist/jobs.js +716 -536
  28. package/dist/json.d.ts +2 -0
  29. package/dist/json.js +122 -0
  30. package/dist/kv.d.ts +130 -243
  31. package/dist/kv.js +273 -640
  32. package/dist/limits.d.ts +80 -0
  33. package/dist/limits.js +139 -0
  34. package/dist/locks.d.ts +62 -0
  35. package/dist/locks.js +237 -0
  36. package/dist/logger.d.ts +45 -9
  37. package/dist/logger.js +150 -38
  38. package/dist/metrics.d.ts +210 -209
  39. package/dist/metrics.js +319 -556
  40. package/dist/once.d.ts +19 -18
  41. package/dist/once.js +74 -63
  42. package/dist/query.d.ts +181 -0
  43. package/dist/query.js +788 -0
  44. package/dist/records.d.ts +241 -150
  45. package/dist/records.js +507 -291
  46. package/dist/runtime/addon.d.ts +14 -0
  47. package/dist/runtime/addon.js +69 -0
  48. package/dist/runtime/bun.js +5 -7
  49. package/dist/runtime/node.js +5 -7
  50. package/dist/runtime/pipe.d.ts +17 -0
  51. package/dist/runtime/pipe.js +133 -0
  52. package/dist/runtime/shared.d.ts +6 -0
  53. package/dist/runtime/shared.js +19 -0
  54. package/dist/runtime.d.ts +5 -2
  55. package/dist/search.d.ts +189 -0
  56. package/dist/search.js +281 -0
  57. package/dist/session.d.ts +31 -3
  58. package/dist/session.js +153 -41
  59. package/dist/sql.d.ts +228 -78
  60. package/dist/sql.js +745 -240
  61. package/dist/store.d.ts +244 -24
  62. package/dist/store.js +270 -67
  63. package/dist/time.d.ts +5 -1
  64. package/dist/time.js +22 -2
  65. package/dist/tx.d.ts +61 -0
  66. package/dist/tx.js +314 -0
  67. package/dist/wire/codec.d.ts +23 -7
  68. package/dist/wire/codec.js +56 -35
  69. package/dist/wire/frame.d.ts +2 -0
  70. package/dist/wire/frame.js +31 -14
  71. package/dist/wire/messages.d.ts +259 -0
  72. package/dist/wire/messages.js +22 -0
  73. package/dist/wire/msgpack.d.ts +49 -1
  74. package/dist/wire/msgpack.js +293 -56
  75. package/dist/wire/protocol.d.ts +2683 -0
  76. package/dist/wire/protocol.js +10846 -0
  77. package/package.json +39 -38
  78. package/src/backup.ts +81 -0
  79. package/src/blobs.ts +678 -301
  80. package/src/channels.ts +377 -0
  81. package/src/clock.ts +4 -4
  82. package/src/config.ts +902 -612
  83. package/src/connection.ts +279 -21
  84. package/src/console.ts +180 -12
  85. package/src/dotenv.ts +82 -0
  86. package/src/errors.ts +105 -0
  87. package/src/handles.ts +157 -8
  88. package/src/index.ts +158 -52
  89. package/src/instruments.ts +1042 -0
  90. package/src/jobs.ts +1017 -733
  91. package/src/json.ts +133 -0
  92. package/src/kv.ts +424 -847
  93. package/src/limits.ts +202 -0
  94. package/src/locks.ts +320 -0
  95. package/src/logger.ts +209 -40
  96. package/src/metrics.ts +557 -752
  97. package/src/once.ts +86 -83
  98. package/src/query.ts +1005 -0
  99. package/src/records.ts +795 -418
  100. package/src/runtime/addon.ts +99 -0
  101. package/src/runtime/bun.ts +5 -7
  102. package/src/runtime/node.ts +5 -7
  103. package/src/runtime/pipe.ts +178 -0
  104. package/src/runtime/shared.ts +20 -0
  105. package/src/runtime.ts +5 -2
  106. package/src/search.ts +480 -0
  107. package/src/session.ts +187 -41
  108. package/src/sql.ts +993 -306
  109. package/src/store.ts +473 -78
  110. package/src/time.ts +48 -3
  111. package/src/tx.ts +426 -0
  112. package/src/wire/codec.ts +78 -37
  113. package/src/wire/frame.ts +44 -14
  114. package/src/wire/messages.ts +25 -0
  115. package/src/wire/msgpack.ts +327 -56
  116. package/src/wire/protocol.ts +11709 -0
  117. package/dist/limiter.d.ts +0 -45
  118. package/dist/limiter.js +0 -68
  119. package/dist/quota.d.ts +0 -44
  120. package/dist/quota.js +0 -98
  121. package/src/limiter.ts +0 -99
  122. package/src/quota.ts +0 -137
package/src/metrics.ts CHANGED
@@ -1,896 +1,701 @@
1
- // Series of samples in metrics.db, as Go's metrics package keeps them: a
2
- // sample is kept bit for bit, a range read exactly, an aggregate computed
3
- // exactly and rounded once. Instruments live in the SDK and are ingested
4
- // every flush.
1
+ // Numbers that move over time, as docs/guides/metrics/README.md has them, over
2
+ // the protocol: series by their name and labels, written whole by ingest and
3
+ // read back by range, in buckets and as their newest samples; what a store
4
+ // holds of them; and a program's instruments, whose totals the store keeps.
5
+ // A series' samples travel as two columns, an int64 time and a float64 value
6
+ // a sample, so that every value's bits come back as they were written.
5
7
 
6
- import { FailureLog, messageOf } from './background.ts'
7
8
  import { download, type Link } from './connection.ts'
8
- import { type Code, errorOf, InvalidError, type LimitError, TinystoreError } from './errors.ts'
9
- import { sayOwn } from './logger.ts'
10
- import { type Duration, ms, type Time, unixMs } from './time.ts'
11
- import { byCodePoint } from './wire/codec.ts'
9
+ import { InvalidError } from './errors.ts'
12
10
  import {
13
- MetricsBatch,
14
- MetricsBuckets,
15
- MetricsDropped,
16
- MetricsLabels,
11
+ Counter,
12
+ Gauge,
13
+ type GaugeFuncOptions,
14
+ Histogram,
15
+ type HistogramOptions,
16
+ type InstrumentOptions,
17
+ type Instruments,
18
+ type LabelValue,
19
+ labelsOf,
20
+ Timer,
21
+ type TimerOptions,
22
+ } from './instruments.ts'
23
+ import { type Duration, type DurationText, ms, type Time, unixMs } from './time.ts'
24
+ import {
25
+ Empty,
26
+ MetricsAggregateAsked,
27
+ MetricsAggregates,
28
+ MetricsDamages,
29
+ MetricsDeleted,
30
+ MetricsDescription,
31
+ MetricsIngest,
32
+ MetricsLatest,
33
+ MetricsNameAsked,
34
+ MetricsNamePage,
35
+ MetricsPageAsked,
17
36
  MetricsPlan,
18
- MetricsRange,
19
- MetricsSeries,
37
+ MetricsQuery,
38
+ MetricsRead,
39
+ MetricsSeriesNamed,
40
+ MetricsTextPage,
20
41
  methods,
21
- } from './wire/messages.ts'
22
-
23
- export type SeriesKind = 'gauge' | 'counter'
42
+ } from './wire/protocol.ts'
43
+
44
+ export {
45
+ type Buckets,
46
+ Counter,
47
+ exponentialBuckets,
48
+ Gauge,
49
+ type GaugeFuncOptions,
50
+ Histogram,
51
+ type HistogramOptions,
52
+ type InstrumentLabels,
53
+ type InstrumentOptions,
54
+ type LabelValue,
55
+ Timer,
56
+ type TimerOptions,
57
+ Timing,
58
+ } from './instruments.ts'
59
+
60
+ /** What a series' samples are. */
61
+ export type SeriesKind = 'gauge' | 'counter' | 'histogram'
62
+
63
+ /** What tells the series of one name apart: a host, a route, a status. */
64
+ export type Labels = Record<string, string>
24
65
 
25
66
  /**
26
- * What tells the series of one name apart: a host, a route, a status. A label
27
- * whose name begins with __ is the store's own, and refused.
67
+ * What a label's value must be: a value, one of a list, none of them with
68
+ * `not` (or the label absent), or a prefix. A number or a boolean is its
69
+ * text, as in an instrument's `with`.
28
70
  */
29
- export type Labels = Record<string, string>
71
+ export type Condition =
72
+ | LabelValue
73
+ | readonly LabelValue[]
74
+ | { not: LabelValue | readonly LabelValue[] }
75
+ | { prefix: string }
30
76
 
77
+ /**
78
+ * The series a call finds and its range: `{ name: 'cpu', where: { host:
79
+ * 'web-1' }, since: '1h' }`. A query is data, the same in every language.
80
+ */
81
+ export interface Query {
82
+ /** the series of this name; a timer's name, the series it writes */
83
+ name?: string | undefined
84
+ where?: Record<string, Condition> | undefined
85
+ /** the span before now the range covers; or from and to */
86
+ since?: Duration | undefined
87
+ /** the range's start, included */
88
+ from?: Time | undefined
89
+ /** the range's end, excluded; now, a sample taken now in the range, unless given */
90
+ to?: Time | undefined
91
+ }
92
+
93
+ /** A series to write: its samples as [time, value] pairs, or as times and values columns. */
31
94
  export interface SeriesInput {
32
- /** the metric: 'http_requests_total' */
33
95
  name: string
34
96
  kind: SeriesKind
35
- labels?: Labels
36
- /** samples as [time, value] pairs, or as columns: unix milliseconds and their values */
37
- samples:
38
- | readonly (readonly [time: Time, value: number])[]
39
- | { times: readonly number[] | BigInt64Array; values: readonly number[] | Float64Array }
97
+ labels?: Record<string, LabelValue>
98
+ samples?: readonly (readonly [time: Time, value: number])[]
99
+ times?: readonly Time[] | Float64Array
100
+ values?: readonly number[] | Float64Array
101
+ /** how long the name's samples stay: its own, kept in the file; unless given, what it keeps already */
102
+ keep?: Duration | undefined
40
103
  }
41
104
 
105
+ /** A series as a read gives it: its samples as two columns. */
42
106
  export interface Series {
43
107
  name: string
44
108
  kind: SeriesKind
45
109
  labels: Labels
46
- /** unix milliseconds, in time order */
47
- times: number[]
48
- /** the values, their bits as they were ingested: -0 and a NaN's payload survive */
110
+ /** unix milliseconds, in the order of their times */
111
+ times: Float64Array
112
+ /** the values, whose bytes keep each one's bits: -0 and a NaN's payload survive */
49
113
  values: Float64Array
50
114
  }
51
115
 
52
- /**
53
- * The series of a name, of labels, or of both, each matched exactly, and
54
- * their samples over the last `since` or from `from` to `to`.
55
- *
56
- * ```ts
57
- * { name: 'cpu', since: '1h' } // the last hour of every cpu series
58
- * { match: { host: 'web-1' }, from: start, to: end } // every series of web-1
59
- * ```
60
- */
61
- /**
62
- * What a label's value must be beyond equality, made by oneOf, noneOf or
63
- * prefix: an object of the SDK's own, so that a stored value is never read as
64
- * a query.
65
- */
66
- export class Condition {
67
- readonly kind: 'one_of' | 'none_of' | 'prefix'
68
- readonly values: readonly string[]
69
-
70
- constructor(kind: Condition['kind'], values: readonly string[]) {
71
- this.kind = kind
72
- this.values = values
73
- }
74
- }
75
-
76
- /** The label is one of the values. */
77
- export function oneOf(...values: string[]): Condition {
78
- return new Condition('one_of', values)
79
- }
80
-
81
- /** The label is none of the values, or the series has none. */
82
- export function noneOf(...values: string[]): Condition {
83
- return new Condition('none_of', values)
84
- }
85
-
86
- /** The label's value begins with the prefix. */
87
- export function prefix(start: string): Condition {
88
- return new Condition('prefix', [start])
89
- }
90
-
91
- /** What a read or an aggregate would spend, each use beside its limit. */
92
- export interface Plan {
93
- series: number
94
- blocks: number
95
- /** the blocks an aggregate answers from their summaries, decoding none of their samples */
96
- summarized: number
97
- bytes: number
98
- decoded: number
99
- limits: { series: number; blocks: number; bytes: number; decoded: number; answered: number }
100
- /** the limit the call would reach, which it would end with; undefined when it fits */
101
- stops: LimitError | undefined
116
+ /** p and a rank: 'p95', 'p99.9'. The ranks offered are those asked most; any other is written the same way. */
117
+ export type Percentile =
118
+ | 'p50'
119
+ | 'p75'
120
+ | 'p90'
121
+ | 'p95'
122
+ | 'p99'
123
+ | 'p99.9'
124
+ // kept apart from the ranks offered, which it would otherwise fold in
125
+ | (`p${number}` & Record<never, never>)
126
+
127
+ /** What a bucket answers: count … last, or a percentile; rate is a second's increase. */
128
+ export type Op =
129
+ | 'count'
130
+ | 'sum'
131
+ | 'avg'
132
+ | 'min'
133
+ | 'max'
134
+ | 'increase'
135
+ | 'rate'
136
+ | 'delta'
137
+ | 'first'
138
+ | 'last'
139
+ | Percentile
140
+
141
+ /** An aggregate: a query cut into buckets of every, each one exact value of op, by groups. */
142
+ export interface AggregateQuery<O extends Op = Op> extends Query {
143
+ /** the buckets' span, counted from 1970 in UTC; the range is one bucket without it */
144
+ every?: Duration | undefined
145
+ op: O
146
+ /** the labels a group keeps; without by and without, every series of a name is one group */
147
+ by?: readonly string[] | undefined
148
+ /** the labels a group leaves out, keeping every other; [] keeps every series apart */
149
+ without?: readonly string[] | undefined
150
+ /** a timer's percentile also gives a point between its bounds, interpolated: an estimate */
151
+ estimate?: boolean | undefined
152
+ }
153
+
154
+ /** What every bucket of an aggregate says of itself. */
155
+ interface Spanned {
156
+ /** where it begins */
157
+ at: Date
158
+ /** how many samples it comes from; a timer's, how many durations */
159
+ samples: number
160
+ resets: number
161
+ /** its value comes from less than its span: the range, the clock or retention cut it */
162
+ partial: boolean
163
+ /** its first step began before the bucket before it: a whole bucket between had no samples */
164
+ gap: boolean
102
165
  }
103
166
 
104
- export interface Range {
105
- name?: string
106
- /** labels a series holds, each exactly */
107
- match?: Labels
108
- /**
109
- * labels under a condition: `{ status: oneOf('500', '502'), env: noneOf('dev'), host: prefix('api-') }`;
110
- * a plain value is equality. A range of noneOf alone is refused, since it would scan every series.
111
- */
112
- where?: Record<string, Condition | string>
113
- /** the span before now the range covers: '1h', '15m', or milliseconds */
114
- since?: Duration
115
- /** the range's start, included; the oldest sample kept when absent */
116
- from?: Time
117
- /** excluded; the open end when absent */
118
- to?: Time
119
- /** each narrows the server's: series matched, blocks decoded, bytes fetched, samples decoded, answered */
120
- limits?: { series?: number; blocks?: number; bytes?: number; decoded?: number; answered?: number }
167
+ /** A bucket of count … last: its one exact value. */
168
+ export interface ValueBucket extends Spanned {
169
+ value: number
121
170
  }
122
171
 
123
172
  /**
124
- * Each computed exactly and rounded once, a group's too: avg is the mean of
125
- * every sample, rate a counter's increase a second, delta a gauge's last
126
- * sample less its first.
173
+ * A bucket of a percentile: a gauge's sample at the rank, as value, or a
174
+ * timer's bucket of its spread that holds it, from lower to upper, and with
175
+ * estimate asked a point between them.
127
176
  */
128
- export type AggregateOp = 'count' | 'sum' | 'min' | 'max' | 'avg' | 'increase' | 'rate' | 'delta'
129
-
130
- /**
131
- * An aggregate's buckets and, to join series, what groups them: by these
132
- * labels, or without them, each group one result. `by: []` joins every series
133
- * of a name. A group never joins two names or two kinds.
134
- */
135
- export interface AggregateRange extends Range {
136
- width: Duration
137
- op: AggregateOp
138
- by?: string[]
139
- without?: string[]
177
+ export interface PercentileBucket extends Spanned {
178
+ value?: number
179
+ lower?: number
180
+ /** Infinity past the last bound */
181
+ upper?: number
182
+ estimate?: number
140
183
  }
141
184
 
142
- export interface Bucket {
143
- from: Date
144
- to: Date
145
- /** the samples it counted */
146
- count: number
147
- /** the resets among them, a counter's */
148
- resets: number
149
- /** computed exactly and rounded once */
150
- value: number
151
- /** the value overflowed to an infinity */
152
- overflow: boolean
153
- /** retention cut the bucket, which counted only its samples from the cutoff on */
154
- partial: boolean
155
- }
185
+ /** A bucket of an aggregate of op: a value, or what a percentile gives. */
186
+ export type Bucket<O extends Op = Op> = O extends Percentile ? PercentileBucket : ValueBucket
156
187
 
157
- export interface Aggregate {
188
+ export interface Aggregate<O extends Op = Op> {
158
189
  name: string
159
- kind: SeriesKind
190
+ /** the labels by kept or without left */
160
191
  labels: Labels
161
- /** only buckets holding samples */
162
- buckets: Bucket[]
192
+ /** a bucket without samples is left out */
193
+ buckets: Bucket<O>[]
163
194
  }
164
195
 
165
- const openEnd = 0x7fff_ffff_ffff_ffffn
166
-
167
- /** The label the wire carries a series' name as, the store's own spelling. */
168
- const wireName = '__name__'
169
-
170
- /** A series' name and labels as the wire spells them, its name among its labels. */
171
- function wireLabels(name: string | undefined, labels: Labels | undefined): Labels {
172
- const spelled: Labels = {}
173
- for (const [key, value] of Object.entries(labels ?? {})) {
174
- if (key.startsWith('__')) {
175
- throw new InvalidError(`the label ${key}: a name beginning with __ is the store's own`)
176
- }
177
- spelled[key] = value
178
- }
179
- if (name !== undefined) {
180
- spelled[wireName] = name
181
- }
182
- return spelled
196
+ /** A series' newest sample in the range. */
197
+ export interface Newest {
198
+ name: string
199
+ labels: Labels
200
+ at: Date
201
+ value: number
183
202
  }
184
203
 
185
- /** A series as the wire spelled it: its name apart from its labels. */
186
- function namedSeries(spelled: Labels | undefined): { name: string; labels: Labels } {
187
- const { [wireName]: name = '', ...labels } = spelled ?? {}
188
- return { name, labels }
204
+ /** What a read or an aggregate would spend of each bound, and the bound it would stop at. */
205
+ export interface Plan {
206
+ series: number
207
+ bytes: number
208
+ decoded: number
209
+ exceeds: { limit: string; wanted: number; bound: number } | undefined
189
210
  }
190
211
 
191
- function rangeOf(
192
- r: Range,
193
- extra?: {
194
- width?: number
195
- op?: AggregateOp
196
- by?: string[] | undefined
197
- without?: string[] | undefined
198
- },
199
- ): Parameters<typeof MetricsRange.encode>[0] {
200
- const { match, where } = conditionsOf(r)
201
- if (r.name === undefined && Object.keys(match).length === 0 && !where.some(finds)) {
202
- throw new InvalidError('a range names a series, a label to match, or a oneOf or a prefix')
203
- }
204
- if (r.since !== undefined && r.from !== undefined) {
205
- throw new InvalidError('a range starts since a span before now or from a time, not both')
206
- }
207
- const from =
208
- r.since !== undefined ? Date.now() - ms(r.since) : r.from === undefined ? 0 : unixMs(r.from)
209
- return {
210
- matchers: wireLabels(r.name, match),
211
- where: where.length > 0 ? where : undefined,
212
- from: BigInt(from),
213
- to: r.to === undefined ? openEnd : BigInt(unixMs(r.to)),
214
- limitSeries: r.limits?.series,
215
- limitBlocks: r.limits?.blocks,
216
- limitBytes: r.limits?.bytes,
217
- limitDecoded: r.limits?.decoded,
218
- limitAnswered: r.limits?.answered,
219
- ...extra,
220
- }
212
+ /** A page's options: a prefix, how many, and where the page before ended. */
213
+ export interface PageOptions {
214
+ prefix?: string | undefined
215
+ /** 1000 unless given, 10,000 at most */
216
+ limit?: number | undefined
217
+ /** a page's next, so that a page's options can be the one before's */
218
+ after?: string | undefined
221
219
  }
222
220
 
223
- /** A range's equality, plain values of where included, and its conditions in the order of their labels. */
224
- function conditionsOf(r: Range): {
225
- match: Labels
226
- where: { label: string; kind: Condition['kind']; values: string[] }[]
227
- } {
228
- const match: Labels = { ...r.match }
229
- const where = []
230
- for (const [label, condition] of Object.entries(r.where ?? {}).sort(([a], [b]) =>
231
- byCodePoint(a, b),
232
- )) {
233
- if (label in match) {
234
- throw new InvalidError(`label ${label} is matched and has a condition`)
235
- }
236
- if (typeof condition === 'string') {
237
- match[label] = condition
238
- } else if (condition instanceof Condition) {
239
- where.push({ label, kind: condition.kind, values: [...condition.values] })
240
- } else {
241
- throw new InvalidError(`label ${label}: a condition is made by oneOf, noneOf or prefix`)
242
- }
243
- }
244
- return { match, where }
221
+ /** A name the store holds samples of. */
222
+ export interface NameInfo {
223
+ name: string
224
+ kind: SeriesKind
225
+ seriesCount: number
226
+ unit: string
227
+ help: string
228
+ keep: DurationText
229
+ /** its oldest sample, or where its keep begins while it holds samples from before */
230
+ retainedFrom: Date
231
+ newest: Date
245
232
  }
246
233
 
247
- function finds(condition: { kind: Condition['kind'] }): boolean {
248
- return condition.kind !== 'none_of'
234
+ export interface NamePage {
235
+ names: NameInfo[]
236
+ /** where the next page starts; none on the last */
237
+ next?: string
249
238
  }
250
239
 
251
- function columnsOf(samples: SeriesInput['samples']): {
252
- times: BigInt64Array
253
- values: Float64Array
254
- } {
255
- if (Array.isArray(samples)) {
256
- const pairs = samples as readonly (readonly [Time, number])[]
257
- return {
258
- times: BigInt64Array.from(pairs, ([t]) => BigInt(unixMs(t))),
259
- values: Float64Array.from(pairs, ([, v]) => v),
260
- }
261
- }
262
- const columns = samples as {
263
- times: readonly number[] | BigInt64Array
264
- values: readonly number[] | Float64Array
265
- }
266
- return {
267
- times:
268
- columns.times instanceof BigInt64Array
269
- ? columns.times
270
- : BigInt64Array.from(columns.times, t => BigInt(t)),
271
- values:
272
- columns.values instanceof Float64Array ? columns.values : Float64Array.from(columns.values),
273
- }
240
+ export interface LabelPage {
241
+ labels: string[]
242
+ next?: string
274
243
  }
275
244
 
276
- /** Joins the pieces a series longer than a body came in, one after another with its name and labels. */
277
- function joined<T extends { name: string; labels: Labels }>(
278
- pieces: T[],
279
- join: (into: T, piece: T) => void,
280
- ): T[] {
281
- const out: T[] = []
282
- for (const piece of pieces) {
283
- const last = out.at(-1)
284
- if (last !== undefined && last.name === piece.name && sameLabels(last.labels, piece.labels)) {
285
- join(last, piece)
286
- } else {
287
- out.push(piece)
288
- }
289
- }
290
- return out
245
+ export interface ValuePage {
246
+ values: string[]
247
+ next?: string
291
248
  }
292
249
 
293
- function sameLabels(a: Labels, b: Labels): boolean {
294
- const keys = Object.keys(a)
295
- return keys.length === Object.keys(b).length && keys.every(k => a[k] === b[k])
250
+ /** A name's unit and help; empty ones remove them. */
251
+ export interface Description {
252
+ unit?: string
253
+ help?: string
296
254
  }
297
255
 
298
- function concatFloats(a: Float64Array, b: Float64Array): Float64Array {
299
- const out = new Float64Array(a.length + b.length)
300
- out.set(a)
301
- out.set(b, a.length)
302
- return out
256
+ /** A series whose bytes no longer read, which delete removes. */
257
+ export interface Damage {
258
+ name: string
259
+ labels: Labels
260
+ error: string
303
261
  }
304
262
 
263
+ /**
264
+ * A store's metrics: series by name and labels, their reads and aggregates,
265
+ * what the store holds of them, and the program's instruments.
266
+ */
305
267
  export class Metrics {
306
268
  readonly #link: Link
307
- readonly #instruments = new Map<string, Instrument>()
308
- readonly #timers = new Map<string, TimerInstrument>()
309
- #interval: ReturnType<typeof setInterval> | undefined
310
- readonly #failureLog = new FailureLog('metrics instruments', sayOwn)
311
- /** instruments' flushes that failed, and why the last did */
312
- failures = 0
313
- lastFailure: Error | undefined
314
-
315
- constructor(link: Link) {
269
+ readonly #instruments: Instruments
270
+
271
+ /** The store's close stops instruments, sending what they changed last. */
272
+ constructor(link: Link, instruments: Instruments) {
316
273
  this.#link = link
274
+ this.#instruments = instruments
317
275
  }
318
276
 
319
- /** Stores series and their samples, all or none; a refused series is named by its labels. */
277
+ /** Writes series and their samples, every one or none: a refused series names itself. */
320
278
  async ingest(series: SeriesInput | readonly SeriesInput[]): Promise<void> {
321
- const batch = (Array.isArray(series) ? series : [series as SeriesInput]).map(s => ({
322
- labels: wireLabels(s.name, s.labels),
323
- kind: s.kind,
324
- ...columnsOf(s.samples),
325
- }))
279
+ const given = Array.isArray(series)
280
+ ? (series as readonly SeriesInput[])
281
+ : [series as SeriesInput]
282
+ const body = MetricsIngest.encode({ series: given.map(newSeries) })
326
283
  await this.#link.run('write', connection =>
327
- connection.session.call(methods['metrics.ingest'], MetricsBatch.encode({ series: batch })),
284
+ connection.session.call(methods['metrics.ingest'], body),
328
285
  )
329
286
  }
330
287
 
331
- /** Every sample of the series a range matches, exactly, read whole before the first leaves the server. */
332
- async read(range: Range): Promise<Series[]> {
333
- const got = await this.#link.run('read', connection =>
334
- download(connection, methods['metrics.read'], MetricsRange.encode(rangeOf(range))),
335
- )
336
- const pieces = got.items.map(item => {
337
- const s = MetricsSeries.decode(item)
338
- return {
339
- ...namedSeries(s.labels as Labels | undefined),
340
- kind: (s.kind ?? 'gauge') as SeriesKind,
341
- times: Array.from(s.times ?? [], Number),
342
- values: s.values ?? new Float64Array(0),
288
+ /** The samples of each series the query finds, in its range: whole, or a limit error naming its bound. */
289
+ async read(query: Query): Promise<Series[]> {
290
+ const parts = await this.#download('metrics.read', MetricsQuery.encode(queryOf(query)))
291
+ const series: Series[] = []
292
+ let more = false
293
+ for (const piece of parts.flatMap(part => MetricsRead.decode(part).series ?? [])) {
294
+ const times = timesOf(piece.times ?? new Uint8Array(0))
295
+ const values = valuesOf(piece.values ?? new Uint8Array(0))
296
+ const last = series.at(-1)
297
+ if (more && last !== undefined) {
298
+ last.times = joined(last.times, times)
299
+ last.values = joined(last.values, values)
300
+ } else {
301
+ const kind = (piece.kind ?? 'gauge') as SeriesKind
302
+ series.push({ name: piece.name ?? '', kind, labels: piece.labels ?? {}, times, values })
343
303
  }
344
- })
345
- return joined(pieces, (into, piece) => {
346
- into.times.push(...piece.times)
347
- into.values = concatFloats(into.values, piece.values)
348
- })
349
- }
350
-
351
- /** Buckets of a width from the range's start, each computed exactly: a counter's increase counts its resets. */
352
- async aggregate(range: AggregateRange): Promise<Aggregate[]> {
353
- if (range.by !== undefined && range.without !== undefined) {
354
- throw new InvalidError('an aggregate groups by labels or without them, not both')
304
+ more = piece.more === true
355
305
  }
356
- const grouping = { by: range.by, without: range.without }
357
- const got = await this.#link.run('read', connection =>
358
- download(
359
- connection,
360
- methods['metrics.aggregate'],
361
- MetricsRange.encode(rangeOf(range, { width: ms(range.width), op: range.op, ...grouping })),
362
- ),
306
+ return series
307
+ }
308
+
309
+ /** The newest sample of each series the query finds, when it has one in the range. */
310
+ async latest(query: Query): Promise<Newest[]> {
311
+ const parts = await this.#download('metrics.latest', MetricsQuery.encode(queryOf(query)))
312
+ return parts.flatMap(part =>
313
+ (MetricsLatest.decode(part).series ?? []).map(newest => ({
314
+ name: newest.name ?? '',
315
+ labels: newest.labels ?? {},
316
+ at: new Date(newest.at ?? 0),
317
+ value: newest.value ?? 0,
318
+ })),
363
319
  )
364
- const pieces = got.items.map(item => {
365
- const b = MetricsBuckets.decode(item)
366
- const values = b.values ?? new Float64Array(0)
367
- const buckets: Bucket[] = Array.from(values, (value, i) => ({
368
- from: new Date(Number(b.from?.[i] ?? 0n)),
369
- to: new Date(Number(b.to?.[i] ?? 0n)),
370
- count: Number(b.count?.[i] ?? 0n),
371
- resets: Number(b.resets?.[i] ?? 0n),
372
- value,
373
- overflow: ((b.flags?.[i] ?? 0) & 1) !== 0,
374
- partial: ((b.flags?.[i] ?? 0) & 2) !== 0,
375
- }))
376
- return {
377
- ...namedSeries(b.labels as Labels | undefined),
378
- kind: (b.kind ?? 'gauge') as SeriesKind,
379
- buckets,
380
- }
381
- })
382
- return joined(pieces, (into, piece) => {
383
- into.buckets.push(...piece.buckets)
384
- })
385
320
  }
386
321
 
387
322
  /**
388
- * What read(range), or aggregate(range) when it names an op, would spend
389
- * of its limits, found without a payload fetched or a sample decoded: the
390
- * series, the blocks, those an aggregate answers from their summaries, the
391
- * bytes and the samples, beside the limits; stops is the LimitError the
392
- * call would end with, undefined when it fits.
323
+ * The buckets of each group of the series the query finds, each one exact
324
+ * value of op, rounded once; a bucket of count … last has its value.
393
325
  */
394
- async explain(
395
- range: Range & Partial<Pick<AggregateRange, 'width' | 'op' | 'by' | 'without'>>,
396
- ): Promise<Plan> {
397
- const extra =
398
- range.op === undefined
399
- ? {}
400
- : { width: ms(range.width ?? 0), op: range.op, by: range.by, without: range.without }
401
- const body = await this.#link.run('read', connection =>
402
- connection.session.call(
403
- methods['metrics.explain'],
404
- MetricsRange.encode(rangeOf(range, extra)),
405
- ),
326
+ async aggregate<O extends Op>(query: AggregateQuery<O>): Promise<Aggregate<O>[]> {
327
+ const parts = await this.#download(
328
+ 'metrics.aggregate',
329
+ MetricsAggregateAsked.encode(aggregateOf(query)),
406
330
  )
407
- const p = MetricsPlan.decode(body)
408
- const stops = p.stops === undefined || p.stops === null ? undefined : p.stops
331
+ const groups: Aggregate<O>[] = []
332
+ let more = false
333
+ for (const piece of parts.flatMap(part => MetricsAggregates.decode(part).groups ?? [])) {
334
+ const buckets = (piece.buckets ?? []).map(bucket => bucketOf(bucket) as Bucket<O>)
335
+ const last = groups.at(-1)
336
+ if (more && last !== undefined) {
337
+ last.buckets.push(...buckets)
338
+ } else {
339
+ groups.push({ name: piece.name ?? '', labels: piece.labels ?? {}, buckets })
340
+ }
341
+ more = piece.more === true
342
+ }
343
+ return groups
344
+ }
345
+
346
+ /** What a read, or an aggregate when given its op, would spend of each bound; it decodes no sample. */
347
+ async explain(query: Query & Partial<Omit<AggregateQuery, keyof Query>>): Promise<Plan> {
348
+ const asked =
349
+ query.op === undefined ? { query: queryOf(query) } : aggregateOf(query as AggregateQuery)
350
+ const answer = await this.#read('metrics.explain', MetricsAggregateAsked.encode(asked))
351
+ const plan = MetricsPlan.decode(answer)
352
+ const exceeds = plan.exceeds
409
353
  return {
410
- series: Number(p.series ?? 0),
411
- blocks: Number(p.blocks ?? 0),
412
- summarized: Number(p.summarized ?? 0),
413
- bytes: Number(p.bytes ?? 0),
414
- decoded: Number(p.decoded ?? 0),
415
- limits: {
416
- series: Number(p.limitSeries ?? 0),
417
- blocks: Number(p.limitBlocks ?? 0),
418
- bytes: Number(p.limitBytes ?? 0),
419
- decoded: Number(p.limitDecoded ?? 0),
420
- answered: Number(p.limitAnswered ?? 0),
421
- },
422
- stops:
423
- stops === undefined
354
+ series: plan.series ?? 0,
355
+ bytes: plan.bytes ?? 0,
356
+ decoded: plan.decoded ?? 0,
357
+ exceeds:
358
+ exceeds === undefined
424
359
  ? undefined
425
- : (errorOf(stops.code ?? 'limit', stops.message ?? '', stops.what ?? {}) as LimitError),
360
+ : { limit: exceeds.limit ?? '', wanted: exceeds.wanted ?? 0, bound: exceeds.bound ?? 0 },
426
361
  }
427
362
  }
428
363
 
429
- /** Removes one series and everything it holds, whether it still reads or not. */
430
- async drop(series: {
431
- name: string
432
- labels?: Labels
433
- }): Promise<{ found: boolean; unreadableGroups: number }> {
434
- const labels = wireLabels(series.name, series.labels)
435
- const body = await this.#link.run('write', connection =>
436
- connection.session.call(methods['metrics.drop'], MetricsLabels.encode({ labels })),
437
- )
438
- const dropped = MetricsDropped.decode(body)
439
- return { found: dropped.found === true, unreadableGroups: dropped.unreadableGroups ?? 0 }
364
+ /** A page of the names the store holds samples of, in the byte order of their text. */
365
+ async names(options: PageOptions = {}): Promise<NamePage> {
366
+ const answer = await this.#read('metrics.names', MetricsPageAsked.encode(pageOf(options)))
367
+ const page = MetricsNamePage.decode(answer)
368
+ const names = (page.names ?? []).map(name => ({
369
+ name: name.name ?? '',
370
+ kind: (name.kind ?? 'gauge') as SeriesKind,
371
+ seriesCount: name.seriesCount ?? 0,
372
+ unit: name.unit ?? '',
373
+ help: name.help ?? '',
374
+ keep: spelled(name.keep ?? 0),
375
+ retainedFrom: new Date(name.retainedFrom ?? 0),
376
+ newest: new Date(name.newest ?? 0),
377
+ }))
378
+ return page.next === undefined ? { names } : { names, next: page.next }
440
379
  }
441
380
 
442
- /** A counter: its total since this process started, ingested every flush; a restart is a reset. */
443
- counter(name: string): Counter {
444
- return new Counter(this.#instrument(name, 'counter'), {})
381
+ /** A page of a name's label names, but the store's own. */
382
+ async labelNames(name: string, options: PageOptions = {}): Promise<LabelPage> {
383
+ const page = await this.#texts('metrics.labelNames', { ...pageOf(options), name })
384
+ return page.next === undefined
385
+ ? { labels: page.texts }
386
+ : { labels: page.texts, next: page.next }
445
387
  }
446
388
 
447
- /** A gauge: its value at each flush. */
448
- gauge(name: string): Gauge {
449
- return new Gauge(this.#instrument(name, 'gauge'), {})
389
+ /** A page of the values a label of a name's series holds. */
390
+ async labelValues(name: string, label: string, options: PageOptions = {}): Promise<ValuePage> {
391
+ const page = await this.#texts('metrics.labelValues', { ...pageOf(options), name, label })
392
+ return page.next === undefined
393
+ ? { values: page.texts }
394
+ : { values: page.texts, next: page.next }
450
395
  }
451
396
 
452
- /** A gauge read by a function at each flush; a function that throws skips that sample. */
453
- gaugeFunc(name: string, read: () => number | Promise<number>): void {
454
- this.#instrument(name, 'gauge').read = read
397
+ async #texts(
398
+ method: 'metrics.labelNames' | 'metrics.labelValues',
399
+ asked: Parameters<typeof MetricsPageAsked.encode>[0],
400
+ ): Promise<{ texts: string[]; next: string | undefined }> {
401
+ const page = MetricsTextPage.decode(await this.#read(method, MetricsPageAsked.encode(asked)))
402
+ return { texts: page.texts ?? [], next: page.next }
455
403
  }
456
404
 
457
405
  /**
458
- * A timer: how many durations it measured and their sum in milliseconds,
459
- * ingested every flush as the counters name_count and name_sum, and the
460
- * longest since the flush before as the gauge name_max, left out when it
461
- * measured none. A range's mean is its sum's increase over its count's.
406
+ * Sets a name's unit and help in place of what it had, as the Rust metrics
407
+ * crate's describe_counter! does: what is not given is removed, and `{}`
408
+ * removes both. They belong to the name, so a delete of its series leaves them.
462
409
  */
463
- timer(name: string): Timer {
464
- return new Timer(this.#timer(name), {})
465
- }
466
-
467
- #instrument(name: string, kind: SeriesKind): Instrument {
468
- let instrument = this.#instruments.get(name)
469
- if (instrument === undefined) {
470
- const timer = timerWriting(name, this.#timers)
471
- if (timer !== undefined) {
472
- throw new InvalidError(`${name} is written by the timer ${timer}`)
473
- }
474
- instrument = { name, kind, series: new Map(), refused: new Set(), lastRead: undefined }
475
- this.#instruments.set(name, instrument)
476
- this.#flushing()
477
- } else if (instrument.kind !== kind) {
478
- throw new InvalidError(`${name} is a ${instrument.kind}, not a ${kind}`)
479
- }
480
- return instrument
481
- }
482
-
483
- #timer(name: string): TimerInstrument {
484
- let timer = this.#timers.get(name)
485
- if (timer === undefined) {
486
- for (const { suffix } of timerSeries) {
487
- const writer = this.#instruments.get(name + suffix)
488
- if (writer !== undefined) {
489
- throw new InvalidError(
490
- `${name + suffix} is a ${writer.kind}; the timer ${name} would write it`,
491
- )
492
- }
493
- }
494
- timer = { name, series: new Map(), refused: new Set() }
495
- this.#timers.set(name, timer)
496
- this.#flushing()
497
- }
498
- return timer
410
+ async describe(name: string, description: Description): Promise<void> {
411
+ const body = MetricsDescription.encode({
412
+ name,
413
+ unit: description.unit ?? '',
414
+ help: description.help ?? '',
415
+ })
416
+ await this.#link.run('write', connection =>
417
+ connection.session.call(methods['metrics.describe'], body),
418
+ )
499
419
  }
500
420
 
501
- #flushing(): void {
502
- this.#interval ??= setInterval(() => void this.#flushInBackground(), flushEvery)
503
- this.#interval.unref?.()
421
+ /** A name's unit and help; both empty when nothing described it. */
422
+ async description(name: string): Promise<{ unit: string; help: string }> {
423
+ const answer = MetricsDescription.decode(
424
+ await this.#read('metrics.description', MetricsNameAsked.encode({ name })),
425
+ )
426
+ return { unit: answer.unit ?? '', help: answer.help ?? '' }
504
427
  }
505
428
 
506
- // a flush no caller awaits says its failure, as Go's background work does
507
- async #flushInBackground(): Promise<void> {
508
- try {
509
- await this.flush()
510
- this.#failureLog.succeeded()
511
- } catch (err) {
512
- this.#failureLog.failed(err)
429
+ /**
430
+ * Removes the one series of exactly this name and these labels, no more
431
+ * and no fewer, with every sample it holds, whether they still read or
432
+ * not; true when the store held it. `labels: {}` is the series without labels.
433
+ */
434
+ async delete(series: { name: string; labels: Record<string, LabelValue> }): Promise<boolean> {
435
+ const labels: Labels = {}
436
+ for (const [label, value] of Object.entries(series.labels)) {
437
+ labels[label] = String(value)
513
438
  }
439
+ const body = MetricsSeriesNamed.encode({ name: series.name, labels })
440
+ const answer = await this.#link.run('write', connection =>
441
+ connection.session.call(methods['metrics.delete'], body),
442
+ )
443
+ return MetricsDeleted.decode(answer).found === true
514
444
  }
515
445
 
516
446
  /**
517
- * Ingests every instrument's value now, as the timer does every 15 s. A
518
- * series the store refuses is left out from then on, said once, so that one
519
- * bad instrument keeps no other out.
447
+ * The series whose bytes no longer read, 1000 at most, each with what
448
+ * broke; deleting them shows the next.
449
+ *
450
+ * for (let damaged = await store.metrics.damaged(); damaged.length > 0; damaged = await store.metrics.damaged()) {
451
+ * for (const series of damaged) await store.metrics.delete(series)
452
+ * }
520
453
  */
454
+ async damaged(): Promise<Damage[]> {
455
+ const answer = MetricsDamages.decode(await this.#read('metrics.damaged', Empty.encode({})))
456
+ return (answer.damages ?? []).map(damage => ({
457
+ name: damage.name ?? '',
458
+ labels: damage.labels ?? {},
459
+ error: damage.error ?? '',
460
+ }))
461
+ }
462
+
463
+ /** Sends what every instrument changed and has the store write its totals now, as it does every 15 seconds. */
521
464
  async flush(): Promise<void> {
522
- const at = BigInt(Date.now())
523
- const batch = await this.#instrumentSamples(at)
524
- const taken = this.#takeTimers(at, batch)
525
- if (batch.length === 0) {
465
+ if (await this.#instruments.flush()) {
526
466
  return
527
467
  }
528
- try {
529
- await this.#ingestLeavingRefusedOut(batch)
530
- } catch (err) {
531
- for (const [timing, longest] of taken) {
532
- timing.longest = Math.max(timing.longest, longest)
533
- timing.measured = true
534
- }
535
- this.failures++
536
- this.lastFailure = err as Error
537
- throw err
538
- }
468
+ await this.#link.run('write', connection =>
469
+ connection.session.call(methods['metrics.flush'], Empty.encode({})),
470
+ )
539
471
  }
540
472
 
541
- // every instrument's value now; a gauge whose function throws skips this
542
- // flush, said once while its error stays the same
543
- async #instrumentSamples(at: bigint): Promise<Owned[]> {
544
- const batch: Owned[] = []
545
- for (const instrument of this.#instruments.values()) {
546
- if (instrument.read !== undefined && !(await readGauge(instrument, instrument.read))) {
547
- continue
548
- }
549
- for (const [key, s] of instrument.series) {
550
- batch.push({
551
- sample: sampleAt(at, instrument.name, s.labels, instrument.kind, s.value),
552
- owner: {
553
- series: formatSeries(instrument.name, s.labels),
554
- refuse: () => refuse(instrument, key),
555
- },
556
- })
557
- }
558
- }
559
- return batch
560
- }
561
-
562
- // sends the batch until the store takes what is left of it: a refusal that
563
- // names one of its series leaves that series out, for good, and goes again
564
- async #ingestLeavingRefusedOut(batch: Owned[]): Promise<void> {
565
- let sending = batch
566
- while (sending.length > 0) {
567
- try {
568
- const series = sending.map(owned => owned.sample)
569
- await this.#link.run('write', connection =>
570
- connection.session.call(methods['metrics.ingest'], MetricsBatch.encode({ series })),
571
- )
572
- return
573
- } catch (err) {
574
- const refused = refusedIn(sending, err)
575
- if (refused === undefined) {
576
- throw err
577
- }
578
- refused.refuse()
579
- sayOwn('warn', 'instrument refused', { series: refused.series, error: messageOf(err) })
580
- sending = sending.filter(owned => owned.owner !== refused)
581
- }
582
- }
473
+ /**
474
+ * A total that only goes up, which the store keeps: processes counting
475
+ * into one series count into one total. Its label names, when given,
476
+ * `counter<'route' | 'status'>(…)`, are the only ones `with` compiles with.
477
+ */
478
+ counter<L extends string = string>(name: string, options: InstrumentOptions = {}): Counter<L> {
479
+ return new Counter(this.#instruments, this.#instruments.declare(name, 'counter', options), {})
583
480
  }
584
481
 
585
- // adds what the timers ingest to batch and starts their longest again,
586
- // answering what it took so that a failed flush gives it back; a timer's
587
- // series of one label set share an owner, so a refusal leaves all three out
588
- #takeTimers(at: bigint, batch: Owned[]): [Timing, number][] {
589
- const taken: [Timing, number][] = []
590
- for (const timer of this.#timers.values()) {
591
- for (const [key, t] of timer.series) {
592
- const owner = {
593
- series: formatSeries(timer.name, t.labels),
594
- refuse: () => refuse(timer, key),
595
- }
596
- const add = (suffix: string, kind: SeriesKind, value: number) =>
597
- batch.push({ sample: sampleAt(at, timer.name + suffix, t.labels, kind, value), owner })
598
- add('_count', 'counter', t.count)
599
- add('_sum', 'counter', t.sum)
600
- if (t.measured) {
601
- add('_max', 'gauge', t.longest)
602
- taken.push([t, t.longest])
603
- t.longest = 0
604
- t.measured = false
605
- }
606
- }
607
- }
608
- return taken
482
+ /** A value that goes up and down: a queue's length, a temperature. */
483
+ gauge<L extends string = string>(name: string, options: InstrumentOptions = {}): Gauge<L> {
484
+ return new Gauge(this.#instruments, this.#instruments.declare(name, 'gauge', options), {})
609
485
  }
610
486
 
611
- /** Stops flushing every 15 s and ingests the instruments' last values; the store's close calls it. */
612
- async stop(): Promise<void> {
613
- if (this.#interval !== undefined) {
614
- clearInterval(this.#interval)
615
- this.#interval = undefined
616
- }
617
- if (this.instruments > 0) {
618
- await this.#flushInBackground()
619
- }
487
+ /**
488
+ * A gauge whose value read gives every 15 seconds, of the set of labels
489
+ * given; another set of the name takes a function of its own, and a set
490
+ * is read by one. It may be async, is never called again while a call of
491
+ * it runs, and an error or an answer that is not a number writes nothing
492
+ * that time, said once while it repeats.
493
+ *
494
+ * store.metrics.gaugeFunc('queue_depth', () => emails.depth(), { labels: { queue: 'emails' } })
495
+ */
496
+ gaugeFunc(
497
+ name: string,
498
+ read: () => number | Promise<number>,
499
+ options: GaugeFuncOptions = {},
500
+ ): void {
501
+ const { labels, ...told } = options
502
+ this.#instruments.reader(name, labelsOf(labels ?? {}, false), told, read)
503
+ }
504
+
505
+ /** How many things took how long: their count, sum and longest in milliseconds, and with buckets their spread. */
506
+ timer<L extends string = string>(name: string, options: TimerOptions = {}): Timer<L> {
507
+ return new Timer(this.#instruments, this.#instruments.declare(name, 'timer', options), {})
508
+ }
509
+
510
+ /** A timer of numbers that are not durations: a response's size in bytes. */
511
+ histogram<L extends string = string>(name: string, options: HistogramOptions = {}): Histogram<L> {
512
+ return new Histogram(
513
+ this.#instruments,
514
+ this.#instruments.declare(name, 'histogram', options),
515
+ {},
516
+ )
620
517
  }
621
518
 
622
- get instruments(): number {
623
- return this.#instruments.size + this.#timers.size
519
+ #read(method: keyof typeof methods, body: Uint8Array): Promise<Uint8Array> {
520
+ return this.#link.run('read', connection => connection.session.call(methods[method], body))
624
521
  }
625
- }
626
-
627
- const flushEvery = 15_000
628
-
629
- interface Instrument {
630
- name: string
631
- kind: SeriesKind
632
- /** by the canonical spelling of each label set */
633
- series: Map<string, { labels: Labels; value: number }>
634
- /** the spellings of the label sets the store refused, whose writes are left out */
635
- refused: Set<string>
636
- read?: () => number | Promise<number>
637
- /** the error a gauge's function last threw, said once while it stays the same */
638
- lastRead: string | undefined
639
- }
640
522
 
641
- /** what a timer ingests, each series its name and a suffix */
642
- const timerSeries = [
643
- { suffix: '_count', kind: 'counter' },
644
- { suffix: '_sum', kind: 'counter' },
645
- { suffix: '_max', kind: 'gauge' },
646
- ] as const
647
-
648
- interface TimerInstrument {
649
- name: string
650
- /** by the canonical spelling of each label set */
651
- series: Map<string, Timing>
652
- refused: Set<string>
653
- }
654
-
655
- interface Timing {
656
- labels: Labels
657
- count: number
658
- /** milliseconds */
659
- sum: number
660
- /** milliseconds, since the flush before */
661
- longest: number
662
- /** since the flush before */
663
- measured: boolean
664
- }
665
-
666
- /** the timer that writes the series name, if one does */
667
- function timerWriting(name: string, timers: Map<string, TimerInstrument>): string | undefined {
668
- for (const { suffix } of timerSeries) {
669
- const base = name.slice(0, -suffix.length)
670
- if (name.endsWith(suffix) && timers.has(base)) {
671
- return base
672
- }
523
+ async #download(method: keyof typeof methods, body: Uint8Array): Promise<Uint8Array[]> {
524
+ const got = await this.#link.run('read', connection =>
525
+ download(connection, methods[method], body),
526
+ )
527
+ return got.items.length === 0 ? [got.trailer] : [...got.items, got.trailer]
673
528
  }
674
- return undefined
675
- }
676
-
677
- /** one sample of a series, as metrics.ingest takes it */
678
- interface Sampled {
679
- labels: Labels
680
- kind: SeriesKind
681
- times: BigInt64Array
682
- values: Float64Array
683
529
  }
684
530
 
685
- function sampleAt(
686
- at: bigint,
687
- name: string,
688
- labels: Labels,
689
- kind: SeriesKind,
690
- value: number,
691
- ): Sampled {
531
+ /** A query as the wire carries it; a condition given as undefined is refused, never left out. */
532
+ function queryOf(query: Query): Parameters<typeof MetricsQuery.encode>[0] {
533
+ const where: Record<string, { values?: string[]; not?: boolean; prefix?: string }> = {}
534
+ for (const [label, condition] of Object.entries(query.where ?? {})) {
535
+ where[label] = conditionOf(label, condition)
536
+ }
537
+ if (query.since !== undefined && query.from !== undefined) {
538
+ throw new InvalidError('a query starts since a span before now or from a time, not both')
539
+ }
692
540
  return {
693
- labels: { ...labels, [wireName]: name },
694
- kind,
695
- times: BigInt64Array.of(at),
696
- values: Float64Array.of(value),
541
+ name: query.name,
542
+ where,
543
+ since: query.since === undefined ? undefined : ms(query.since),
544
+ from: query.from === undefined ? undefined : unixMs(query.from),
545
+ to: query.to === undefined ? undefined : unixMs(query.to),
697
546
  }
698
547
  }
699
548
 
700
- function keyOf(labels: Labels): string {
701
- return JSON.stringify(Object.entries(labels).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
702
- }
703
-
704
- function seriesOf(instrument: Instrument, labels: Labels): { labels: Labels; value: number } {
705
- const key = keyOf(labels)
706
- let s = instrument.series.get(key)
707
- if (s === undefined) {
708
- s = { labels, value: 0 }
709
- // a refused series' writes go to a value no flush reads
710
- if (!instrument.refused.has(key)) {
711
- instrument.series.set(key, s)
549
+ function conditionOf(
550
+ label: string,
551
+ condition: Condition | undefined,
552
+ ): { values?: string[]; not?: boolean; prefix?: string } {
553
+ if (condition === undefined || condition === null) {
554
+ throw new InvalidError(`where ${label}: a condition given as ${String(condition)}`)
555
+ }
556
+ if (Array.isArray(condition)) {
557
+ return { values: (condition as readonly LabelValue[]).map(String) }
558
+ }
559
+ if (typeof condition === 'object') {
560
+ if ('not' in condition) {
561
+ return { values: [condition.not].flat().map(String), not: true }
562
+ }
563
+ if ('prefix' in condition) {
564
+ return { prefix: condition.prefix }
712
565
  }
566
+ throw new InvalidError(`where ${label}: a value, a list, { not } or { prefix }`)
713
567
  }
714
- return s
568
+ return { values: [String(condition)] }
715
569
  }
716
570
 
717
- /** a sample of an instrument's, and the series a refusal of it leaves out */
718
- interface Owned {
719
- sample: Sampled
720
- owner: Owner
721
- }
722
-
723
- /** an instrument's series, or a timer's three of one label set */
724
- interface Owner {
725
- /** as Go prints a series: name{route="/a"} */
726
- series: string
727
- refuse(): void
728
- }
729
-
730
- function refuse(instrument: Instrument | TimerInstrument, key: string): void {
731
- instrument.series.delete(key)
732
- instrument.refused.add(key)
733
- }
734
-
735
- /** the codes of a refusal that is the series' own doing, as Go's metrics tells them apart */
736
- const seriesRefusals = new Set<Code>([
737
- 'invalid',
738
- 'limit',
739
- 'too_old',
740
- 'too_new',
741
- 'conflict',
742
- 'corrupt',
743
- 'suspended',
744
- ])
745
-
746
- /** the owner of the series a refusal names by its labels, when it names one of these */
747
- function refusedIn(sending: Owned[], err: unknown): Owner | undefined {
748
- if (!(err instanceof TinystoreError) || !seriesRefusals.has(err.code)) {
749
- return undefined
750
- }
751
- const named = Object.entries(err.what)
752
- return sending.find(
753
- ({ sample }) =>
754
- named.length === Object.keys(sample.labels).length &&
755
- named.every(([key, value]) => sample.labels[key] === value),
756
- )?.owner
757
- }
758
-
759
- /** a gauge's value from its function, or false when it threw: said once while the error stays the same */
760
- async function readGauge(
761
- instrument: Instrument,
762
- read: () => number | Promise<number>,
763
- ): Promise<boolean> {
764
- if (instrument.refused.size > 0) {
765
- return false
766
- }
767
- try {
768
- instrument.series.set('{}', { labels: {}, value: await read() })
769
- instrument.lastRead = undefined
770
- return true
771
- } catch (err) {
772
- const error = messageOf(err)
773
- if (error !== instrument.lastRead) {
774
- sayOwn('warn', 'gauge read failed', { series: instrument.name, error })
775
- instrument.lastRead = error
776
- }
777
- return false
571
+ function aggregateOf(query: AggregateQuery): Parameters<typeof MetricsAggregateAsked.encode>[0] {
572
+ return {
573
+ query: queryOf(query),
574
+ every: query.every === undefined ? undefined : ms(query.every),
575
+ op: query.op,
576
+ by: query.by === undefined ? undefined : [...query.by],
577
+ without: query.without === undefined ? undefined : [...query.without],
578
+ estimate: query.estimate === true,
778
579
  }
779
580
  }
780
581
 
781
- /** a series as Go prints one: its name, then its labels sorted and quoted */
782
- function formatSeries(name: string, labels: Labels): string {
783
- const keys = Object.keys(labels).sort()
784
- if (keys.length === 0) {
785
- return name
786
- }
787
- return `${name}{${keys.map(key => `${key}=${JSON.stringify(labels[key])}`).join(',')}}`
582
+ function pageOf(options: PageOptions): Parameters<typeof MetricsPageAsked.encode>[0] {
583
+ return { prefix: options.prefix, limit: options.limit, after: options.after }
788
584
  }
789
585
 
790
- export class Counter {
791
- readonly #instrument: Instrument
792
- readonly #labels: Labels
586
+ /** A bucket as the wire carries it. */
587
+ type WireBucket = NonNullable<
588
+ NonNullable<ReturnType<typeof MetricsAggregates.decode>['groups']>[number]['buckets']
589
+ >[number]
793
590
 
794
- constructor(instrument: Instrument, labels: Labels) {
795
- this.#instrument = instrument
796
- this.#labels = labels
591
+ function bucketOf(bucket: WireBucket): PercentileBucket {
592
+ const answer: PercentileBucket = {
593
+ at: new Date(bucket.at ?? 0),
594
+ samples: bucket.samples ?? 0,
595
+ resets: bucket.resets ?? 0,
596
+ partial: bucket.partial === true,
597
+ gap: bucket.gap === true,
797
598
  }
798
-
799
- /** The counter of these labels besides its own: the same labels in any order are one series. */
800
- with(labels: Labels): Counter {
801
- return new Counter(this.#instrument, { ...this.#labels, ...labels })
599
+ if (bucket.value !== undefined) {
600
+ answer.value = bucket.value
802
601
  }
803
-
804
- inc(): void {
805
- this.add(1)
602
+ if (bucket.lower !== undefined) {
603
+ answer.lower = bucket.lower
604
+ answer.upper = bucket.upper ?? Infinity
806
605
  }
807
-
808
- add(n: number): void {
809
- if (!(n >= 0)) {
810
- throw new InvalidError(`a counter adds ${n}; it only grows`)
811
- }
812
- seriesOf(this.#instrument, this.#labels).value += n
606
+ if (bucket.estimate !== undefined) {
607
+ answer.estimate = bucket.estimate
813
608
  }
609
+ return answer
814
610
  }
815
611
 
816
- export class Gauge {
817
- readonly #instrument: Instrument
818
- readonly #labels: Labels
819
-
820
- constructor(instrument: Instrument, labels: Labels) {
821
- this.#instrument = instrument
822
- this.#labels = labels
823
- }
824
-
825
- with(labels: Labels): Gauge {
826
- return new Gauge(this.#instrument, { ...this.#labels, ...labels })
612
+ /** A series to write, its samples as the two columns the wire carries. */
613
+ function newSeries(
614
+ given: SeriesInput,
615
+ ): NonNullable<Parameters<typeof MetricsIngest.encode>[0]['series']>[number] {
616
+ const labels: Labels = {}
617
+ for (const [label, value] of Object.entries(given.labels ?? {})) {
618
+ labels[label] = String(value)
827
619
  }
828
-
829
- set(value: number): void {
830
- seriesOf(this.#instrument, this.#labels).value = value
831
- }
832
-
833
- add(n: number): void {
834
- seriesOf(this.#instrument, this.#labels).value += n
620
+ const [times, values] = columnsOf(given)
621
+ const timeBytes = new BigInt64Array(times.length)
622
+ for (let i = 0; i < times.length; i++) {
623
+ timeBytes[i] = BigInt(unixMs(times[i]!))
835
624
  }
836
-
837
- inc(): void {
838
- this.add(1)
625
+ // a Float64Array's bytes go as they are, a NaN's payload with them
626
+ const valueBytes =
627
+ values instanceof Float64Array
628
+ ? new Uint8Array(
629
+ values.buffer.slice(values.byteOffset, values.byteOffset + values.byteLength),
630
+ )
631
+ : new Uint8Array(Float64Array.from(values).buffer)
632
+ return {
633
+ name: given.name,
634
+ kind: given.kind,
635
+ labels,
636
+ times: new Uint8Array(timeBytes.buffer),
637
+ values: valueBytes,
638
+ keep: given.keep === undefined ? undefined : ms(given.keep),
839
639
  }
640
+ }
840
641
 
841
- dec(): void {
842
- this.add(-1)
642
+ function columnsOf(given: SeriesInput): [ArrayLike<Time>, ArrayLike<number>] {
643
+ if (given.samples !== undefined) {
644
+ if (given.times !== undefined || given.values !== undefined) {
645
+ throw new InvalidError(`metrics ${given.name}: samples, or times and values, not both`)
646
+ }
647
+ return [given.samples.map(([time]) => time), given.samples.map(([, value]) => value)]
648
+ }
649
+ if (
650
+ given.times === undefined ||
651
+ given.values === undefined ||
652
+ given.times.length !== given.values.length
653
+ ) {
654
+ throw new InvalidError(
655
+ `metrics ${given.name}: samples, or times and values as long as each other`,
656
+ )
843
657
  }
658
+ return [given.times, given.values]
844
659
  }
845
660
 
846
- /** A timer of labels; record and measure add a duration to the next flush. */
847
- export class Timer {
848
- readonly #timer: TimerInstrument
849
- readonly #labels: Labels
850
-
851
- constructor(timer: TimerInstrument, labels: Labels) {
852
- this.#timer = timer
853
- this.#labels = labels
661
+ /** A column of int64 times, read as the unix milliseconds a Float64Array holds. */
662
+ function timesOf(bytes: Uint8Array): Float64Array {
663
+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
664
+ const times = new Float64Array(bytes.byteLength / 8)
665
+ for (let i = 0; i < times.length; i++) {
666
+ times[i] = Number(view.getBigInt64(i * 8, true))
854
667
  }
668
+ return times
669
+ }
855
670
 
856
- /** The timer of these labels besides its own: the same labels in any order are one series. */
857
- with(labels: Labels): Timer {
858
- return new Timer(this.#timer, { ...this.#labels, ...labels })
859
- }
671
+ /**
672
+ * A column of float64 values, its bytes copied as they came, so that each
673
+ * value's bits stay. A socket's bytes are a Buffer, whose slice is a view of
674
+ * a shared pool rather than a copy, so they are copied into a buffer of their own.
675
+ */
676
+ function valuesOf(bytes: Uint8Array): Float64Array {
677
+ const copy = new Uint8Array(bytes.byteLength)
678
+ copy.set(bytes)
679
+ return new Float64Array(copy.buffer)
680
+ }
860
681
 
861
- /** Adds one duration: milliseconds, their fractions kept, or text such as '250ms'. */
862
- record(d: Duration): void {
863
- const millis = typeof d === 'number' ? d : ms(d)
864
- if (!(Number.isFinite(millis) && millis >= 0)) {
865
- throw new InvalidError(`a timer records ${d}; a duration is never negative`)
866
- }
867
- const key = keyOf(this.#labels)
868
- if (this.#timer.refused.has(key)) {
869
- return
870
- }
871
- let t = this.#timer.series.get(key)
872
- if (t === undefined) {
873
- t = { labels: this.#labels, count: 0, sum: 0, longest: 0, measured: false }
874
- this.#timer.series.set(key, t)
875
- }
876
- t.count++
877
- t.sum += millis
878
- t.longest = Math.max(t.longest, millis)
879
- t.measured = true
880
- }
682
+ function joined(a: Float64Array, b: Float64Array): Float64Array {
683
+ const out = new Float64Array(a.length + b.length)
684
+ out.set(a)
685
+ out.set(b, a.length)
686
+ return out
687
+ }
881
688
 
882
- /**
883
- * Runs fn and records how long it took, whether it returned or threw: its
884
- * result comes back, and what it threw is thrown again.
885
- *
886
- * const user = await latency.with({ route: '/users' }).measure(() => users.get(id))
887
- */
888
- async measure<R>(fn: () => R | Promise<R>): Promise<R> {
889
- const start = performance.now()
890
- try {
891
- return await fn()
892
- } finally {
893
- this.record(performance.now() - start)
689
+ function spelled(millis: number): DurationText {
690
+ for (const [unit, size] of [
691
+ ['d', 86_400_000],
692
+ ['h', 3_600_000],
693
+ ['m', 60_000],
694
+ ['s', 1000],
695
+ ] as const) {
696
+ if (millis >= size && millis % size === 0) {
697
+ return `${millis / size}${unit}` as DurationText
894
698
  }
895
699
  }
700
+ return `${millis}ms` as DurationText
896
701
  }