@rbxts/scribe 2.5.0

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 (56) hide show
  1. package/LICENSE +21 -0
  2. package/NOTICE +21 -0
  3. package/README.md +100 -0
  4. package/Scribe-source-map.json +1 -0
  5. package/licenses/ProfileStore-Apache-2.0.txt +201 -0
  6. package/package.json +32 -0
  7. package/src/Client/DebugHook.luau +457 -0
  8. package/src/Client/init.luau +1607 -0
  9. package/src/Internal/Addons.luau +68 -0
  10. package/src/Internal/Big.luau +582 -0
  11. package/src/Internal/Budget.luau +377 -0
  12. package/src/Internal/Clock.luau +75 -0
  13. package/src/Internal/Config.luau +17 -0
  14. package/src/Internal/Conform.luau +400 -0
  15. package/src/Internal/Datatypes.luau +653 -0
  16. package/src/Internal/Defaults.luau +12 -0
  17. package/src/Internal/Derived.luau +428 -0
  18. package/src/Internal/Exchange.luau +556 -0
  19. package/src/Internal/ExchangeLeg.luau +1368 -0
  20. package/src/Internal/ExchangeVerdict.luau +179 -0
  21. package/src/Internal/Failure.luau +148 -0
  22. package/src/Internal/Health.luau +320 -0
  23. package/src/Internal/LeaderboardDiagnostics.luau +36 -0
  24. package/src/Internal/Log.luau +378 -0
  25. package/src/Internal/Marker.luau +76 -0
  26. package/src/Internal/Metrics.luau +152 -0
  27. package/src/Internal/Node.luau +3954 -0
  28. package/src/Internal/Profile.luau +69 -0
  29. package/src/Internal/Rng.luau +83 -0
  30. package/src/Internal/Sched.luau +56 -0
  31. package/src/Internal/Signal.luau +199 -0
  32. package/src/Internal/Store/ProfileStore.luau +3019 -0
  33. package/src/Internal/Store/init.luau +18 -0
  34. package/src/Internal/StudioCodec.luau +155 -0
  35. package/src/Internal/Template.luau +1848 -0
  36. package/src/Internal/Transport.luau +169 -0
  37. package/src/Internal/Util.luau +517 -0
  38. package/src/Internal/Version.luau +4 -0
  39. package/src/Internal/Wire.luau +1283 -0
  40. package/src/Server/Analytics.luau +223 -0
  41. package/src/Server/Commands.luau +728 -0
  42. package/src/Server/DebugHook.luau +1490 -0
  43. package/src/Server/Exchanges.luau +737 -0
  44. package/src/Server/Leaderboards.luau +2143 -0
  45. package/src/Server/Monetization.luau +3212 -0
  46. package/src/Server/Persistence.luau +3775 -0
  47. package/src/Server/Replication.luau +1253 -0
  48. package/src/Server/ServerStore.luau +81 -0
  49. package/src/Server/Timed.luau +579 -0
  50. package/src/Server/init.luau +672 -0
  51. package/src/Types.luau +480 -0
  52. package/src/init.luau +2231 -0
  53. package/types/api.d.ts +252 -0
  54. package/types/common.d.ts +355 -0
  55. package/types/index.d.ts +226 -0
  56. package/types/schema.d.ts +276 -0
@@ -0,0 +1,378 @@
1
+ --!strict
2
+ -- Structured logger. Library-level singleton.
3
+ -- Every entry: { At, Level, Category, Code, Message, Context }.
4
+
5
+ local LogService = game:GetService("LogService")
6
+ local RunService = game:GetService("RunService")
7
+ local HttpService = game:GetService("HttpService")
8
+
9
+ local Util = require(script.Parent.Util)
10
+ local Signal = require(script.Parent.Signal)
11
+ local Types = require(script.Parent.Parent.Types)
12
+ local Clock = require(script.Parent.Clock)
13
+ local Sched = require(script.Parent.Sched)
14
+ local Metrics = require(script.Parent.Metrics)
15
+
16
+ type LogEntry = Types.LogEntry
17
+
18
+ -- Entries retained for Log.GetRecent; the bundle option LogRingSize raises it for
19
+ -- runs long enough that 512 truncates the interesting part.
20
+ local DEFAULT_RING_SIZE = 512
21
+ local ringSize = DEFAULT_RING_SIZE
22
+ local MAX_MESSAGE_LEN = 400
23
+ local MAX_STRUCTURED_CONTEXT_BYTES = 1000 -- keep structured-log context under ~1 KiB
24
+
25
+ local LEVEL_ORDER: { [string]: number } = {
26
+ Debug = 1,
27
+ Info = 2,
28
+ Warn = 3,
29
+ Error = 4,
30
+ Fatal = 5,
31
+ }
32
+
33
+ local Log = {}
34
+
35
+ Log.OnIssue = Signal.new() :: Signal.Signal<Types.LogEntry> -- fires (entry) for every Error/Fatal entry
36
+
37
+ local minLevel = if RunService:IsStudio() then LEVEL_ORDER.Debug else LEVEL_ORDER.Warn
38
+ local ringLevel = minLevel
39
+ local ring: { LogEntry } = table.create(ringSize) :: any
40
+ local ringNext = 1
41
+ local ringCount = 0
42
+ type Sink = {
43
+ Fn: (entry: LogEntry) -> (),
44
+ Level: number?,
45
+ MaxQueued: number,
46
+ Queue: { { Entry: LogEntry, Severity: number } },
47
+ Running: boolean,
48
+ Attached: boolean,
49
+ }
50
+ local sinks: { Sink } = {}
51
+
52
+ local function sinkErrorText(err: any): string
53
+ local ok, message = pcall(tostring, err)
54
+ if not ok then
55
+ return "[unprintable error]"
56
+ end
57
+ if #message > MAX_MESSAGE_LEN then
58
+ message = string.sub(message, 1, MAX_MESSAGE_LEN)
59
+ for _ = 1, 3 do
60
+ if utf8.len(message) ~= nil then
61
+ break
62
+ end
63
+ message = string.sub(message, 1, -2)
64
+ end
65
+ message ..= "…"
66
+ end
67
+ return message
68
+ end
69
+
70
+ local function enqueue(sink: Sink, entry: LogEntry, severity: number)
71
+ local queue = sink.Queue
72
+ if #queue >= sink.MaxQueued then
73
+ local victim: number? = nil
74
+ local lowest = severity
75
+ for i, pending in queue do
76
+ if pending.Severity < lowest then
77
+ victim, lowest = i, pending.Severity
78
+ end
79
+ end
80
+ Metrics.Add("LogSinkDropped")
81
+ if victim == nil then
82
+ return
83
+ end
84
+ table.remove(queue, victim)
85
+ end
86
+ table.insert(queue, { Entry = entry, Severity = severity })
87
+ if sink.Running then
88
+ return
89
+ end
90
+ sink.Running = true
91
+ Sched.Defer(function()
92
+ local batch = 0
93
+ local warned = false
94
+ while sink.Attached and #queue > 0 do
95
+ local nextEntry = table.remove(queue, 1)
96
+ if nextEntry == nil then
97
+ break
98
+ end
99
+ local ok, err = pcall(sink.Fn, nextEntry.Entry)
100
+ if not ok then
101
+ Metrics.Add("LogSinkErrors")
102
+ if not warned then
103
+ warn(`[Scribe] log sink error: {sinkErrorText(err)}`)
104
+ warned = true
105
+ end
106
+ end
107
+ batch += 1
108
+ if batch >= 32 and #queue > 0 then
109
+ batch = 0
110
+ Clock.Wait()
111
+ end
112
+ end
113
+ sink.Running = false
114
+ end)
115
+ end
116
+
117
+ -- LogService structured logging, feature-detected with a print/warn fallback.
118
+ local structuredAvailable = pcall(function()
119
+ return typeof((LogService :: any).Output) == "function"
120
+ end) and typeof((LogService :: any).Output) == "function"
121
+
122
+ local function trimContext(context: { [string]: any }?): { [string]: any }?
123
+ if context == nil then
124
+ return nil
125
+ end
126
+ local sanitized = Util.sanitizeContext(context)
127
+ local ok, encoded = pcall(HttpService.JSONEncode, HttpService, sanitized)
128
+ if ok and #encoded <= MAX_STRUCTURED_CONTEXT_BYTES then
129
+ return sanitized
130
+ end
131
+ -- Too large for the cloud pipeline: keep only shallow scalar fields.
132
+ local slim = {}
133
+ if type(sanitized) == "table" then
134
+ for k, v in sanitized do
135
+ local vt = type(v)
136
+ if vt == "string" or vt == "number" or vt == "boolean" then
137
+ slim[k] = v
138
+ end
139
+ end
140
+ end
141
+ slim._trimmed = true
142
+ return slim
143
+ end
144
+
145
+ local function defaultSink(entry: LogEntry)
146
+ -- Stable template per code, never the message: Creator Analytics aggregates by
147
+ -- template, and a caller-supplied string would mint unbounded cardinality.
148
+ local template = `Scribe {entry.Code}`
149
+ if structuredAvailable then
150
+ local context: { [string]: any } = trimContext(entry.Context) or {}
151
+ context.code = entry.Code
152
+ context.category = entry.Category
153
+ context.message = entry.Message
154
+ local ok = pcall(function()
155
+ local ls = LogService :: any
156
+ if entry.Level == "Debug" then
157
+ ls:Output(template, context)
158
+ elseif entry.Level == "Info" then
159
+ ls:Info(template, context)
160
+ elseif entry.Level == "Warn" then
161
+ ls:Warn(template, context)
162
+ else
163
+ ls:Error(template, context)
164
+ end
165
+ end)
166
+ if ok then
167
+ return
168
+ end
169
+ end
170
+ local suffix = ""
171
+ if entry.Context then
172
+ local ok, encoded = pcall(HttpService.JSONEncode, HttpService, Util.sanitizeContext(entry.Context))
173
+ if ok then
174
+ suffix = " " .. encoded
175
+ end
176
+ end
177
+ if LEVEL_ORDER[entry.Level] >= LEVEL_ORDER.Warn then
178
+ warn(`[Scribe][{entry.Category}][{entry.Code}] {entry.Message}{suffix}`)
179
+ else
180
+ print(`[Scribe][{entry.Category}][{entry.Code}] {entry.Message}{suffix}`)
181
+ end
182
+ end
183
+
184
+ local function emit(
185
+ level: Types.LogLevel,
186
+ category: Types.LogCategory,
187
+ code: Types.LogCode,
188
+ message: string,
189
+ context: { [string]: any }?
190
+ )
191
+ local severity = LEVEL_ORDER[level]
192
+ local capture = severity >= ringLevel
193
+ local output = severity >= minLevel
194
+ local wanted = capture or output or severity >= LEVEL_ORDER.Error
195
+ if not wanted then
196
+ for _, sink in sinks do
197
+ if severity >= (sink.Level or minLevel) then
198
+ wanted = true
199
+ break
200
+ end
201
+ end
202
+ end
203
+ if not wanted then
204
+ return
205
+ end
206
+ -- Capped so a client-supplied string or a long traceback cannot bloat the ring
207
+ -- buffer, the console fallback, or the structured context.
208
+ if #message > MAX_MESSAGE_LEN then
209
+ local cut = string.sub(message, 1, MAX_MESSAGE_LEN)
210
+ -- A cut inside a character leaves invalid UTF-8, which no sink can JSON-encode.
211
+ for _ = 1, 3 do
212
+ if utf8.len(cut) ~= nil then
213
+ break
214
+ end
215
+ cut = string.sub(cut, 1, -2)
216
+ end
217
+ message = cut .. "…"
218
+ end
219
+ local entry: LogEntry = {
220
+ At = Clock.Now(),
221
+ Level = level,
222
+ Category = category,
223
+ Code = code,
224
+ Message = message,
225
+ Context = context,
226
+ }
227
+
228
+ if capture then
229
+ ring[ringNext] = entry
230
+ ringNext = (ringNext % ringSize) + 1
231
+ ringCount = math.min(ringCount + 1, ringSize)
232
+ end
233
+
234
+ if output then
235
+ defaultSink(entry)
236
+ end
237
+
238
+ for _, sink in sinks do
239
+ if severity >= (sink.Level or minLevel) then
240
+ enqueue(sink, entry, severity)
241
+ end
242
+ end
243
+
244
+ if LEVEL_ORDER[level] >= LEVEL_ORDER.Error then
245
+ Log.OnIssue:Fire(entry)
246
+ end
247
+ end
248
+
249
+ function Log.SetLevel(level: string)
250
+ minLevel = LEVEL_ORDER[level] or minLevel
251
+ end
252
+
253
+ function Log.SetRingLevel(level: string?)
254
+ ringLevel = (if level then LEVEL_ORDER[level] else nil)
255
+ or (if RunService:IsStudio() then LEVEL_ORDER.Debug else LEVEL_ORDER.Warn)
256
+ end
257
+
258
+ function Log.Debug(category: Types.LogCategory, code: Types.LogCode, message: string, context: { [string]: any }?)
259
+ emit("Debug", category, code, message, context)
260
+ end
261
+
262
+ function Log.Info(category: Types.LogCategory, code: Types.LogCode, message: string, context: { [string]: any }?)
263
+ emit("Info", category, code, message, context)
264
+ end
265
+
266
+ function Log.Warn(category: Types.LogCategory, code: Types.LogCode, message: string, context: { [string]: any }?)
267
+ emit("Warn", category, code, message, context)
268
+ end
269
+
270
+ function Log.Error(category: Types.LogCategory, code: Types.LogCode, message: string, context: { [string]: any }?)
271
+ emit("Error", category, code, message, context)
272
+ end
273
+
274
+ function Log.Fatal(category: Types.LogCategory, code: Types.LogCode, message: string, context: { [string]: any }?)
275
+ emit("Fatal", category, code, message, context)
276
+ end
277
+
278
+ -- One worker per sink, with a bounded queue and filtering before dispatch.
279
+ function Log.AddSink(fn: (entry: LogEntry) -> (), options: Types.LogSinkOptions?): () -> ()
280
+ assert(type(fn) == "function", "Scribe: log sink must be a function")
281
+ local level = if options then options.Level else nil
282
+ assert(level == nil or LEVEL_ORDER[level] ~= nil, "Scribe: invalid log sink Level")
283
+ local maxQueued = if options and options.MaxQueued ~= nil then options.MaxQueued else 128
284
+ assert(
285
+ type(maxQueued) == "number" and maxQueued >= 1 and maxQueued <= 4096 and maxQueued % 1 == 0,
286
+ "Scribe: log sink MaxQueued must be an integer from 1 to 4096"
287
+ )
288
+ local sink: Sink = {
289
+ Fn = fn,
290
+ Level = if level then LEVEL_ORDER[level] else nil,
291
+ MaxQueued = maxQueued,
292
+ Queue = {},
293
+ Running = false,
294
+ Attached = true,
295
+ }
296
+ table.insert(sinks, sink)
297
+ return function()
298
+ sink.Attached = false
299
+ table.clear(sink.Queue)
300
+ local index = table.find(sinks, sink)
301
+ if index ~= nil then
302
+ table.remove(sinks, index)
303
+ end
304
+ end
305
+ end
306
+
307
+ export type LogFilter = {
308
+ Level: Types.LogLevel?,
309
+ Category: Types.LogCategory?,
310
+ Code: Types.LogCode?,
311
+ Limit: number?,
312
+ }
313
+
314
+ --- Resize the retained-entry ring, keeping the most recent entries. A resize is a
315
+ --- configuration change, not a request to forget what already happened.
316
+ function Log.SetRingSize(size: number?)
317
+ local next = if type(size) == "number" and size >= 1 then math.floor(size) else DEFAULT_RING_SIZE
318
+ if next == ringSize then
319
+ return
320
+ end
321
+
322
+ local kept: { LogEntry } = {}
323
+ for i = 1, ringCount do
324
+ local idx = ((ringNext - 1 - ringCount + i - 1) % ringSize) + 1
325
+ local entry = ring[idx]
326
+ if entry then
327
+ table.insert(kept, entry)
328
+ end
329
+ end
330
+ while #kept > next do
331
+ table.remove(kept, 1) -- drop oldest first
332
+ end
333
+
334
+ ringSize = next
335
+ ring = table.create(ringSize) :: any
336
+ for i, entry in kept do
337
+ ring[i] = entry
338
+ end
339
+ ringCount = #kept
340
+ ringNext = (#kept % ringSize) + 1
341
+ end
342
+
343
+ --- Entries currently retained, and the configured capacity.
344
+ function Log.RingInfo(): { Size: number, Count: number }
345
+ return { Size = ringSize, Count = ringCount }
346
+ end
347
+ -- Retained entries, oldest first, optionally filtered by level, category or code.
348
+ function Log.GetRecent(filter: LogFilter?): { LogEntry }
349
+ local out = {}
350
+ local minFilter = if filter and filter.Level then LEVEL_ORDER[filter.Level] else nil
351
+ for i = 1, ringCount do
352
+ -- Oldest first: start after the write cursor.
353
+ local idx = ((ringNext - 1 - ringCount + i - 1) % ringSize) + 1
354
+ local entry = ring[idx]
355
+ if entry then
356
+ if minFilter and LEVEL_ORDER[entry.Level] < minFilter then
357
+ continue
358
+ end
359
+ if filter and filter.Category and entry.Category ~= filter.Category then
360
+ continue
361
+ end
362
+ if filter and filter.Code and entry.Code ~= filter.Code then
363
+ continue
364
+ end
365
+ table.insert(out, entry)
366
+ end
367
+ end
368
+ if filter and filter.Limit and #out > filter.Limit then
369
+ local trimmed = table.create(filter.Limit) :: { LogEntry }
370
+ for i = #out - filter.Limit + 1, #out do
371
+ table.insert(trimmed, out[i])
372
+ end
373
+ return trimmed
374
+ end
375
+ return out
376
+ end
377
+
378
+ return Log
@@ -0,0 +1,76 @@
1
+ --!strict
2
+ -- Declarator markers. Declarators return marker tables at runtime (cast to their
3
+ -- base Luau type at the type level); the template compiler strips them into
4
+ -- (defaultValue, schemaMeta) and deep-freezes the rest.
5
+
6
+ local MARKER_KEY = "__scribeMarker"
7
+
8
+ export type MarkerKind =
9
+ "Int"
10
+ | "Number"
11
+ | "Big"
12
+ | "String"
13
+ | "Enum"
14
+ | "Flags"
15
+ | "Timed"
16
+ | "Datatype"
17
+ | "Dynamic"
18
+ | "Derived"
19
+ | "Optional"
20
+ | "ArrayOf"
21
+ | "SetOf"
22
+ | "DictOf"
23
+ | "MapOf"
24
+ | "ServerOnly"
25
+ | "Shared"
26
+ | "Session"
27
+
28
+ export type Meta = {
29
+ Min: number?,
30
+ Max: number?,
31
+ -- Scribe.Number only: opts the field out of f64 on the wire. "f32" selects
32
+ -- IEEE binary32; a positive number selects a fixed-point grid of that step
33
+ -- over [Min, Max]. Absent means f64, which is the default and stays it.
34
+ Precision: (number | string)?,
35
+ MaxLength: number?,
36
+ Members: { string }?,
37
+ Datatype: string?, -- typeof() name for Datatype markers (e.g. "Vector3")
38
+ Factory: (() -> any)?, -- Dynamic markers: produces the per-new-profile default
39
+ Inputs: { string }?, -- Derived markers: dotted paths of the fields it reads
40
+ Compute: ((...any) -> any)?, -- Derived markers: pure function of those inputs
41
+ Element: any?, -- ArrayOf/DictOf markers: the raw element shape, compiled into AnyChild
42
+ MaxItems: number?, -- ArrayOf: cardinality cap
43
+ Evict: string?, -- ArrayOf: "Front" or "Back", which end an Insert at the cap drops
44
+ Unique: boolean?, -- SetOf: entries are deduplicated and kept in sorted order
45
+ KeyType: string?, -- MapOf: "integer" or "string"
46
+ MaxKeys: number?, -- DictOf/MapOf: cardinality cap
47
+ MaxKeyLength: number?, -- DictOf: per-key byte cap
48
+ }
49
+
50
+ local Marker = {}
51
+
52
+ function Marker.make(kind: MarkerKind, default: any, meta: Meta?): any
53
+ local marker = {
54
+ [MARKER_KEY] = kind,
55
+ Default = default,
56
+ Meta = meta,
57
+ }
58
+ -- For Timed fields the static type is { __scribeTimed: T }; the type
59
+ -- function keys off that property name, the runtime keys off MARKER_KEY.
60
+ if kind == "Timed" then
61
+ (marker :: any).__scribeTimed = default
62
+ end
63
+ return marker
64
+ end
65
+
66
+ -- Returns (kind, default, meta) when the value is a marker, otherwise nil.
67
+ function Marker.inspect(value: any): (MarkerKind?, any, Meta?)
68
+ if type(value) == "table" and rawget(value, MARKER_KEY) ~= nil then
69
+ return rawget(value, MARKER_KEY) :: MarkerKind, rawget(value, "Default"), rawget(value, "Meta")
70
+ end
71
+ return nil, nil, nil
72
+ end
73
+
74
+ Marker.KEY = MARKER_KEY
75
+
76
+ return Marker
@@ -0,0 +1,152 @@
1
+ --!strict
2
+ -- Metrics counters. Library-level singleton.
3
+ --
4
+ -- Pull only: a host reads Metrics.Get() (published as Scribe.GetMetrics) on whatever
5
+ -- cadence it wants, as DebugHook does on a 1 Hz timer. Do not add a sink hook to Add;
6
+ -- counters are bumped on hot paths, and a sink there would put arbitrary game code
7
+ -- inside a save.
8
+
9
+ local Metrics = {}
10
+
11
+ local Clock = require(script.Parent.Clock)
12
+
13
+ -- Samples kept per observed name, for percentiles. A ring, not a growing list: an
14
+ -- unbounded sample set on a metric observed once per save is a slow leak. 256
15
+ -- samples is about 2 KB per name and enough for a stable P99.
16
+ local RESERVOIR = 256
17
+
18
+ type Observation = {
19
+ Count: number,
20
+ Sum: number,
21
+ Max: number,
22
+ -- Ring of the most recent samples. `Filled` is how many slots are live, which
23
+ -- is not the same as Count once the ring wraps.
24
+ Samples: { number },
25
+ -- When each slot was observed, for Window.
26
+ Times: { number },
27
+ Next: number,
28
+ Filled: number,
29
+ LastAt: number,
30
+ }
31
+
32
+ local counters: { [string]: number } = {}
33
+ local gauges: { [string]: number } = {}
34
+ local observations: { [string]: Observation } = {}
35
+
36
+ function Metrics.Add(name: string, n: number?)
37
+ counters[name] = (counters[name] or 0) + (n or 1)
38
+ end
39
+
40
+ function Metrics.Set(name: string, value: number)
41
+ gauges[name] = value
42
+ end
43
+
44
+ -- Record one sample of a distribution (durations, byte counts).
45
+ function Metrics.Observe(name: string, value: number)
46
+ local obs = observations[name]
47
+ if not obs then
48
+ obs = {
49
+ Count = 0,
50
+ Sum = 0,
51
+ Max = 0,
52
+ Samples = table.create(RESERVOIR) :: { number },
53
+ Times = table.create(RESERVOIR) :: { number },
54
+ Next = 1,
55
+ Filled = 0,
56
+ LastAt = 0,
57
+ }
58
+ observations[name] = obs
59
+ end
60
+ local now = Clock.Monotonic()
61
+ obs.Count += 1
62
+ obs.Sum += value
63
+ if value > obs.Max then
64
+ obs.Max = value
65
+ end
66
+ obs.Samples[obs.Next] = value
67
+ obs.Times[obs.Next] = now
68
+ obs.LastAt = now
69
+ obs.Next = (obs.Next % RESERVOIR) + 1
70
+ if obs.Filled < RESERVOIR then
71
+ obs.Filled += 1
72
+ end
73
+ end
74
+
75
+ export type Percentiles = {
76
+ P50: number,
77
+ P90: number,
78
+ P99: number,
79
+ Samples: number, -- in the window
80
+ Age: number, -- seconds since the newest sample
81
+ Window: number, -- seconds from the oldest sample to the newest
82
+ }
83
+
84
+ --- Nearest-rank percentiles over the retained samples, or nil if there are none. The
85
+ --- sort target is a fresh table per call, not a shared scratch buffer: a buffer left
86
+ --- longer by a previous name would mix that name's tail into this one's percentiles,
87
+ --- with no error to notice.
88
+ function Metrics.Percentiles(name: string): Percentiles?
89
+ local obs = observations[name]
90
+ if obs == nil or obs.Filled == 0 then
91
+ return nil
92
+ end
93
+
94
+ local sorted: { number } = table.create(obs.Filled) :: { number }
95
+ table.move(obs.Samples, 1, obs.Filled, 1, sorted)
96
+ table.sort(sorted)
97
+
98
+ local function at(p: number): number
99
+ local index = math.ceil((p / 100) * obs.Filled)
100
+ return sorted[math.clamp(index, 1, obs.Filled)]
101
+ end
102
+ -- Once the ring has wrapped, the slot about to be overwritten is the oldest.
103
+ local oldest = if obs.Filled < RESERVOIR then obs.Times[1] else obs.Times[obs.Next]
104
+ return {
105
+ P50 = at(50),
106
+ P90 = at(90),
107
+ P99 = at(99),
108
+ Samples = obs.Filled,
109
+ Age = Clock.Monotonic() - obs.LastAt,
110
+ Window = obs.LastAt - oldest,
111
+ }
112
+ end
113
+
114
+ --- Percentiles for every observed name.
115
+ function Metrics.GetPercentiles(): { [string]: Percentiles }
116
+ local out = {}
117
+ for name in observations do
118
+ local p = Metrics.Percentiles(name)
119
+ if p ~= nil then
120
+ out[name] = p
121
+ end
122
+ end
123
+ return out
124
+ end
125
+
126
+ function Metrics.Get(): { [string]: any }
127
+ local out: { [string]: any } = table.clone(counters)
128
+ for name, value in gauges do
129
+ out[name] = value
130
+ end
131
+ for name, obs in observations do
132
+ out[name] = {
133
+ Count = obs.Count,
134
+ Average = if obs.Count > 0 then obs.Sum / obs.Count else 0,
135
+ Max = obs.Max,
136
+ }
137
+ end
138
+ return out
139
+ end
140
+
141
+ --- Clear every counter, gauge and sample. Nothing else holds a reference into these
142
+ --- tables: Get returns a fresh one and the observation records are private, so
143
+ --- clearing them cannot strand a reader.
144
+ function Metrics.Reset()
145
+ table.clear(counters)
146
+ table.clear(gauges)
147
+ table.clear(observations)
148
+ end
149
+
150
+ Metrics.RESERVOIR = RESERVOIR
151
+
152
+ return Metrics