@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.
- package/LICENSE +21 -0
- package/NOTICE +21 -0
- package/README.md +100 -0
- package/Scribe-source-map.json +1 -0
- package/licenses/ProfileStore-Apache-2.0.txt +201 -0
- package/package.json +32 -0
- package/src/Client/DebugHook.luau +457 -0
- package/src/Client/init.luau +1607 -0
- package/src/Internal/Addons.luau +68 -0
- package/src/Internal/Big.luau +582 -0
- package/src/Internal/Budget.luau +377 -0
- package/src/Internal/Clock.luau +75 -0
- package/src/Internal/Config.luau +17 -0
- package/src/Internal/Conform.luau +400 -0
- package/src/Internal/Datatypes.luau +653 -0
- package/src/Internal/Defaults.luau +12 -0
- package/src/Internal/Derived.luau +428 -0
- package/src/Internal/Exchange.luau +556 -0
- package/src/Internal/ExchangeLeg.luau +1368 -0
- package/src/Internal/ExchangeVerdict.luau +179 -0
- package/src/Internal/Failure.luau +148 -0
- package/src/Internal/Health.luau +320 -0
- package/src/Internal/LeaderboardDiagnostics.luau +36 -0
- package/src/Internal/Log.luau +378 -0
- package/src/Internal/Marker.luau +76 -0
- package/src/Internal/Metrics.luau +152 -0
- package/src/Internal/Node.luau +3954 -0
- package/src/Internal/Profile.luau +69 -0
- package/src/Internal/Rng.luau +83 -0
- package/src/Internal/Sched.luau +56 -0
- package/src/Internal/Signal.luau +199 -0
- package/src/Internal/Store/ProfileStore.luau +3019 -0
- package/src/Internal/Store/init.luau +18 -0
- package/src/Internal/StudioCodec.luau +155 -0
- package/src/Internal/Template.luau +1848 -0
- package/src/Internal/Transport.luau +169 -0
- package/src/Internal/Util.luau +517 -0
- package/src/Internal/Version.luau +4 -0
- package/src/Internal/Wire.luau +1283 -0
- package/src/Server/Analytics.luau +223 -0
- package/src/Server/Commands.luau +728 -0
- package/src/Server/DebugHook.luau +1490 -0
- package/src/Server/Exchanges.luau +737 -0
- package/src/Server/Leaderboards.luau +2143 -0
- package/src/Server/Monetization.luau +3212 -0
- package/src/Server/Persistence.luau +3775 -0
- package/src/Server/Replication.luau +1253 -0
- package/src/Server/ServerStore.luau +81 -0
- package/src/Server/Timed.luau +579 -0
- package/src/Server/init.luau +672 -0
- package/src/Types.luau +480 -0
- package/src/init.luau +2231 -0
- package/types/api.d.ts +252 -0
- package/types/common.d.ts +355 -0
- package/types/index.d.ts +226 -0
- 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
|