@rbxts/scribe-telemetry 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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ericplane
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,146 @@
1
+ --!strict
2
+ -- Polls cached board status; never refreshes a leaderboard.
3
+
4
+ local Monitor = {}
5
+ Monitor.__index = Monitor
6
+
7
+ export type Entry = {
8
+ BundleId: number,
9
+ Name: string,
10
+ Status: "Starting" | "Healthy" | "Degraded",
11
+ PendingWrites: number,
12
+ RetryingWrites: number,
13
+ RejectedWrites: number,
14
+ ReadAge: number?,
15
+ LastReadError: string?,
16
+ LastWriteError: string?,
17
+ }
18
+
19
+ local function nonnegative(value: any): boolean
20
+ return type(value) == "number" and value == value and value >= 0 and value < math.huge
21
+ end
22
+
23
+ local function copyEntry(value: any): Entry?
24
+ if
25
+ type(value) ~= "table"
26
+ or not nonnegative(value.BundleId)
27
+ or value.BundleId < 1
28
+ or value.BundleId % 1 ~= 0
29
+ or type(value.Name) ~= "string"
30
+ or value.Name == ""
31
+ or not table.find({ "Starting", "Healthy", "Degraded" }, value.Status)
32
+ then
33
+ return nil
34
+ end
35
+ for _, name in { "PendingWrites", "RetryingWrites", "RejectedWrites" } do
36
+ if not nonnegative(value[name]) then
37
+ return nil
38
+ end
39
+ end
40
+ if value.ReadAge ~= nil and not nonnegative(value.ReadAge) then
41
+ return nil
42
+ end
43
+ return {
44
+ BundleId = value.BundleId,
45
+ Name = value.Name,
46
+ Status = value.Status,
47
+ PendingWrites = value.PendingWrites,
48
+ RetryingWrites = value.RetryingWrites,
49
+ RejectedWrites = value.RejectedWrites,
50
+ ReadAge = value.ReadAge,
51
+ LastReadError = if type(value.LastReadError) == "string" then value.LastReadError else nil,
52
+ LastWriteError = if type(value.LastWriteError) == "string" then value.LastWriteError else nil,
53
+ }
54
+ end
55
+
56
+ function Monitor.new(scribe: any, config: any, clock: () -> number, report: (Entry, string?, number?) -> ())
57
+ return setmetatable({
58
+ scribe = scribe,
59
+ config = config,
60
+ clock = clock,
61
+ report = report,
62
+ Due = 0,
63
+ Stopped = false,
64
+ State = if config.LeaderboardsEnabled then "Unavailable" else "Disabled",
65
+ Entries = {} :: { Entry },
66
+ States = {} :: { [string]: { Status: string, Since: number, DegradedSince: number? } },
67
+ Omitted = 0,
68
+ ObservedAt = nil :: number?,
69
+ LastError = nil :: string?,
70
+ }, Monitor)
71
+ end
72
+
73
+ function Monitor.Poll(self: any)
74
+ if self.Stopped or not self.config.LeaderboardsEnabled then
75
+ return
76
+ end
77
+ local now = self.clock()
78
+ self.Due = now + self.config.LeaderboardInterval
79
+ local getter = self.scribe.GetLeaderboardSnapshot
80
+ if type(getter) ~= "function" then
81
+ self.State, self.LastError = "Unavailable", "this Scribe version has no leaderboard snapshot API"
82
+ return
83
+ end
84
+ local ok, snapshot = pcall(getter)
85
+ if self.Stopped then
86
+ return
87
+ end
88
+ if not ok or type(snapshot) ~= "table" then
89
+ self.State, self.LastError = "Unavailable", "leaderboard snapshot could not be read"
90
+ return
91
+ end
92
+ local entries: { Entry } = {}
93
+ local seen = {}
94
+ for i = 1, math.min(#snapshot, self.config.MaxBoards) do
95
+ local entry = copyEntry(snapshot[i])
96
+ local key = if entry then `{entry.BundleId}:{entry.Name}` else ""
97
+ if entry == nil or seen[key] then
98
+ self.State, self.LastError = "Unavailable", "leaderboard snapshot contained an invalid or duplicate board"
99
+ return
100
+ end
101
+ seen[key] = true
102
+ table.insert(entries, entry)
103
+ end
104
+ local states = {}
105
+ for _, entry in entries do
106
+ local key = `{entry.BundleId}:{entry.Name}`
107
+ local previous = self.States[key]
108
+ local degradedSince = previous and previous.DegradedSince
109
+ if entry.Status == "Degraded" and degradedSince == nil then
110
+ self.report(entry, previous and previous.Status, previous and now - previous.Since)
111
+ degradedSince = now
112
+ elseif entry.Status == "Healthy" and degradedSince ~= nil then
113
+ self.report(entry, "Degraded", now - degradedSince)
114
+ degradedSince = nil
115
+ end
116
+ if self.Stopped then
117
+ return
118
+ end
119
+ states[key] = {
120
+ Status = entry.Status,
121
+ Since = if previous and previous.Status == entry.Status then previous.Since else now,
122
+ DegradedSince = degradedSince,
123
+ }
124
+ end
125
+ self.States = states
126
+ self.Entries = entries
127
+ self.Omitted = math.max(0, #snapshot - #entries)
128
+ self.ObservedAt = now
129
+ self.State, self.LastError = "Available", nil
130
+ end
131
+
132
+ function Monitor.Tick(self: any)
133
+ if self.config.LeaderboardsEnabled and self.clock() >= self.Due then
134
+ self:Poll()
135
+ end
136
+ end
137
+
138
+ function Monitor.Stop(self: any)
139
+ self.State = "Stopped"
140
+ self.Stopped = true
141
+ self.report = function() end
142
+ table.clear(self.States)
143
+ table.clear(self.Entries)
144
+ end
145
+
146
+ return Monitor
package/NOTICE ADDED
@@ -0,0 +1,21 @@
1
+ Scribe
2
+ Copyright (c) 2026 ericplane
3
+ Licensed under the MIT License (see LICENSE).
4
+
5
+ This product bundles a modified copy of ProfileStore v1.0.3:
6
+
7
+ ProfileStore
8
+ Copyright (c) loleris / MAD STUDIO
9
+ https://github.com/MadStudioRoblox/ProfileStore
10
+ Licensed under the Apache License, Version 2.0.
11
+
12
+ The bundled copy lives at src/Internal/Store/ProfileStore.luau and HAS BEEN
13
+ MODIFIED. Every modification is marked `SCRIBE PATCH` in that file and summarised
14
+ in its header. A copy of the Apache License, Version 2.0 is included at
15
+ licenses/ProfileStore-Apache-2.0.txt.
16
+
17
+ The licence text is kept OUTSIDE src/ on purpose. Everything under src/ is packed
18
+ into the released .rbxm, where a plain text file has no place and whose contents
19
+ Roblox scans for off-platform links -- and the licence is full of them. Attribution
20
+ travels with the code in the file header, which is what Apache-2.0 section 4
21
+ actually asks for; the full text travels with the source package.
package/Preview.luau ADDED
@@ -0,0 +1,396 @@
1
+ --!strict
2
+ -- Synthetic examples of every report the add-on sends, built by the real builders.
3
+
4
+ local Router = require(script.Parent.Router)
5
+
6
+ local Preview = {}
7
+
8
+ export type Kind =
9
+ "All"
10
+ | "Health"
11
+ | "Issues"
12
+ | "Warnings"
13
+ | "Grouping"
14
+ | "Performance"
15
+ | "Leaderboards"
16
+ | "Summaries"
17
+ | "Formatting"
18
+ | "HealthyStartup"
19
+ | "Degraded"
20
+ | "Outage"
21
+ | "PartialRecovery"
22
+ | "Recovery"
23
+ | "IncidentUnderway"
24
+ | "Warning"
25
+ | "Error"
26
+ | "Fatal"
27
+ | "Repeat"
28
+ | "UpstreamSuppressed"
29
+ | "SlowLoad"
30
+ | "SlowLeavingHook"
31
+ | "ReceiptCapacity"
32
+ | "ReceiptRoutingRetry"
33
+ | "LeaderboardDegraded"
34
+ | "LeaderboardRecovery"
35
+ | "SlowSaves"
36
+ | "SlowSavesCleared"
37
+ | "SaveFailures"
38
+ | "SaveFailuresCleared"
39
+ | "Traffic"
40
+ | "TrafficCleared"
41
+ | "Summary"
42
+ | "SummaryNoSamples"
43
+ | "SummaryNoBudget"
44
+ | "LongMessage"
45
+ | "RedactedContext"
46
+
47
+ export type Scenario = { Name: string, Group: string, Run: (handle: any, preview: any) -> () }
48
+
49
+ local USER = 1234567
50
+
51
+ local function issue(level: string, code: string, category: string, message: string, context: { [string]: any })
52
+ return function(handle: any, preview: any)
53
+ handle:reportRecord(handle:recordFrom("Issues", level, code, category, message, context, 0), preview)
54
+ end
55
+ end
56
+
57
+ local function warning(code: string, category: string, message: string, context: { [string]: any }, repeats: number?)
58
+ return function(handle: any, preview: any)
59
+ handle:reportRecord(
60
+ handle:recordFrom("Warnings", "Warn", code, category, message, context, repeats or 0),
61
+ preview
62
+ )
63
+ end
64
+ end
65
+
66
+ local function health(previous: string?, current: string, observedFor: number?)
67
+ return function(handle: any, preview: any)
68
+ handle:reportHealth(previous, current, observedFor, preview)
69
+ end
70
+ end
71
+
72
+ local function performance(name: string, detail: string, streak: number, cleared: boolean)
73
+ return function(handle: any, preview: any)
74
+ handle:reportPerformance(name, detail, streak, cleared, preview)
75
+ end
76
+ end
77
+
78
+ local function summary(shape: string)
79
+ return function(handle: any, preview: any)
80
+ local metrics = {
81
+ ActiveSessions = 42,
82
+ ProfilesLoaded = 180,
83
+ ProfileLoadFailures = 1,
84
+ SavesOk = 620,
85
+ SavesFailed = 2,
86
+ BytesOut = 52428800,
87
+ ReceiptHistoryRefusals = 1,
88
+ LogSinkDropped = 12,
89
+ LogSinkErrors = 2,
90
+ LbWrites = 1240,
91
+ LbWritesSkipped = 810,
92
+ LbReadFailures = 2,
93
+ LbWriteFailures = 3,
94
+ LbQueueDepth = 4,
95
+ LbBudgetDeferred = 18,
96
+ LbQueueOverflow = 0,
97
+ }
98
+ local percentiles: { [string]: any } = {
99
+ SaveDuration = { P50 = 0.42, P90 = 0.9, P99 = 1.6, Samples = 620, Window = 600, Age = 3 },
100
+ ProfileSize = { P50 = 24000, P90 = 61000, P99 = 118000, Samples = 180, Window = 600, Age = 12 },
101
+ ProfileLoadDuration = { P50 = 0.6, P90 = 1.8, P99 = 5.2, Samples = 180, Window = 600, Age = 12 },
102
+ LoadDuration = { P50 = 0.9, P90 = 2.4, P99 = 8.5, Samples = 180, Window = 600, Age = 12 },
103
+ PlayerLeavingHookDuration = { P50 = 0.01, P90 = 0.2, P99 = 1.1, Samples = 150, Window = 600, Age = 18 },
104
+ }
105
+ local budget: { [string]: any }? = {
106
+ Available = true,
107
+ Budgets = { UpdateAsync = 812, GetAsync = 954, SetIncrementSortedAsync = 190 },
108
+ }
109
+ if shape == "nosamples" then
110
+ metrics = { ActiveSessions = 0, ProfilesLoaded = 0, ProfileLoadFailures = 0, SavesOk = 0, SavesFailed = 0 }
111
+ percentiles = {}
112
+ elseif shape == "nobudget" then
113
+ budget = { Available = false, Reason = "budget API unavailable in this context" }
114
+ end
115
+ handle:reportSummary({
116
+ Status = "Healthy",
117
+ Elapsed = handle.config.SummaryInterval,
118
+ Metrics = metrics,
119
+ Previous = { LbWrites = 1000, LbWritesSkipped = 500, LbBudgetDeferred = 10 },
120
+ Percentiles = percentiles,
121
+ Budget = budget,
122
+ LeaderboardFields = {
123
+ {
124
+ Name = "Leaderboard health",
125
+ Value = "1 healthy · 0 degraded · 0 starting\n4 pending · 0 retrying · 0 rejected writes",
126
+ },
127
+ {
128
+ Name = "Leaderboard details",
129
+ Value = "TopCoins (bundle 1): Healthy; 4 pending, 0 retrying, 0 rejected; cache 2.00s",
130
+ },
131
+ },
132
+ }, preview)
133
+ end
134
+ end
135
+
136
+ local function repeatGroup(handle: any, preview: any)
137
+ local now = handle.deps.Clock.Now()
138
+ local sample = handle:recordFrom(
139
+ "Issues",
140
+ "Error",
141
+ "SAVE_FAILED",
142
+ "Persistence",
143
+ "UpdateAsync failed: 502 (Bad Gateway); the profile stays in memory and the next autosave retries",
144
+ { Attempt = 2, UserId = USER },
145
+ 0
146
+ )
147
+ handle:reportGroup(
148
+ {
149
+ Key = "preview",
150
+ Sample = sample,
151
+ FirstAt = now - 900,
152
+ LatestAt = now,
153
+ Count = 14,
154
+ WindowCount = 6,
155
+ Upstream = 3,
156
+ SummaryDue = nil,
157
+ LastSeen = 0,
158
+ Touched = 0,
159
+ } :: Router.Group,
160
+ preview
161
+ )
162
+ end
163
+
164
+ local manyKeys: { [string]: any } = {}
165
+ for i = 1, 10 do
166
+ manyKeys[`Key{i}`] = `value {i}`
167
+ end
168
+
169
+ Preview.SCENARIOS = table.freeze({
170
+ {
171
+ Name = "HealthyStartup",
172
+ Group = "Health",
173
+ Run = function(handle: any, preview: any)
174
+ handle:reportStartup(preview)
175
+ end,
176
+ },
177
+ { Name = "Degraded", Group = "Health", Run = health("Healthy", "Degraded", 3 * 3600 + 120) },
178
+ { Name = "Outage", Group = "Health", Run = health("Degraded", "Outage", 240) },
179
+ { Name = "PartialRecovery", Group = "Health", Run = health("Outage", "Degraded", 95) },
180
+ { Name = "Recovery", Group = "Health", Run = health("Degraded", "Healthy", 1500) },
181
+ { Name = "IncidentUnderway", Group = "Health", Run = health(nil, "Outage", nil) },
182
+ {
183
+ Name = "LeaderboardDegraded",
184
+ Group = "Leaderboards",
185
+ Run = function(handle: any, preview: any)
186
+ handle:reportLeaderboard({
187
+ BundleId = 1,
188
+ Name = "TopCoins",
189
+ Status = "Degraded",
190
+ PendingWrites = 8,
191
+ RetryingWrites = 3,
192
+ RejectedWrites = 0,
193
+ ReadAge = 180,
194
+ LastReadError = "HTTP 503 (Service Unavailable)",
195
+ LastWriteError = "OrderedDataStore write throttled",
196
+ }, "Healthy", 120, preview)
197
+ end,
198
+ },
199
+ {
200
+ Name = "LeaderboardRecovery",
201
+ Group = "Leaderboards",
202
+ Run = function(handle: any, preview: any)
203
+ handle:reportLeaderboard({
204
+ BundleId = 1,
205
+ Name = "TopCoins",
206
+ Status = "Healthy",
207
+ PendingWrites = 0,
208
+ RetryingWrites = 0,
209
+ RejectedWrites = 0,
210
+ ReadAge = 2,
211
+ }, "Degraded", 300, preview)
212
+ end,
213
+ },
214
+ {
215
+ Name = "Warning",
216
+ Group = "Warnings",
217
+ Run = warning(
218
+ "PROFILE_SIZE",
219
+ "Persistence",
220
+ "Profile is 3.9 MB of the 4 MB DataStore limit; saves fail once it grows past it",
221
+ { Bytes = 3900000, Limit = 4194304, UserId = USER, Root = "Inventory" }
222
+ ),
223
+ },
224
+ {
225
+ Name = "Error",
226
+ Group = "Issues",
227
+ Run = issue(
228
+ "Error",
229
+ "SAVE_FAILED",
230
+ "Persistence",
231
+ "UpdateAsync failed after 3 attempts: 502 (Bad Gateway); the profile stays in memory and the next autosave retries",
232
+ { Attempt = 3, UserId = USER, Store = "PlayerData" }
233
+ ),
234
+ },
235
+ {
236
+ Name = "Fatal",
237
+ Group = "Issues",
238
+ Run = issue(
239
+ "Fatal",
240
+ "LOAD_FAILED",
241
+ "Persistence",
242
+ "The profile could not be loaded after 5 attempts; the player was kicked so nothing is written over their data",
243
+ { Attempts = 5, UserId = USER, LastError = "HTTP 500 (Internal Server Error)" }
244
+ ),
245
+ },
246
+ { Name = "Repeat", Group = "Grouping", Run = repeatGroup },
247
+ {
248
+ Name = "SlowLoad",
249
+ Group = "Warnings",
250
+ Run = warning("SLOW_LOAD", "Persistence", "profile load exceeded 10s; inspect its phase and store errors", {
251
+ UserId = USER,
252
+ Phase = "ProfileAcquisition",
253
+ Duration = 12.4,
254
+ }),
255
+ },
256
+ {
257
+ Name = "SlowLeavingHook",
258
+ Group = "Warnings",
259
+ Run = warning("PLAYER_LEAVING_HOOK_SLOW", "Lifecycle", "OnPlayerLeaving exceeded 10s before the final save", {
260
+ UserId = USER,
261
+ Reason = "Left",
262
+ Duration = 11.2,
263
+ }),
264
+ },
265
+ {
266
+ Name = "ReceiptCapacity",
267
+ Group = "Issues",
268
+ Run = issue(
269
+ "Error",
270
+ "RECEIPT_HISTORY_FULL",
271
+ "Monetization",
272
+ "receipt history is full; grant deferred without dropping recent completed IDs",
273
+ {
274
+ UserId = USER,
275
+ Bytes = 1048590,
276
+ Limit = 1048576,
277
+ ProfileBytes = 1700000,
278
+ }
279
+ ),
280
+ },
281
+ {
282
+ Name = "ReceiptRoutingRetry",
283
+ Group = "Warnings",
284
+ Run = warning(
285
+ "RECEIPT_RETRY",
286
+ "Monetization",
287
+ "gift route or recipient proof unavailable; letting Roblox retry",
288
+ {
289
+ UserId = USER,
290
+ Product = "GiftVIP",
291
+ PurchaseId = "preview-receipt",
292
+ }
293
+ ),
294
+ },
295
+ {
296
+ Name = "UpstreamSuppressed",
297
+ Group = "Grouping",
298
+ Run = warning(
299
+ "LB_WRITE_FAIL",
300
+ "Leaderboards",
301
+ "leaderboard write is still pending after repeated failures; retrying with backoff",
302
+ { Board = "TopCoins", UserId = USER },
303
+ 12
304
+ ),
305
+ },
306
+ {
307
+ Name = "SlowSaves",
308
+ Group = "Performance",
309
+ Run = performance("SlowSaves", "Save p99 is 2.4s against a threshold of 2s", 3, false),
310
+ },
311
+ {
312
+ Name = "SlowSavesCleared",
313
+ Group = "Performance",
314
+ Run = performance("SlowSaves", "Save p99 is 800ms against a threshold of 2s", 0, true),
315
+ },
316
+ {
317
+ Name = "SaveFailures",
318
+ Group = "Performance",
319
+ Run = performance("SaveFailures", "Save failures at 4.0 per minute against a threshold of 1.0", 3, false),
320
+ },
321
+ {
322
+ Name = "SaveFailuresCleared",
323
+ Group = "Performance",
324
+ Run = performance("SaveFailures", "Save failures at 0.0 per minute against a threshold of 1.0", 0, true),
325
+ },
326
+ {
327
+ Name = "Traffic",
328
+ Group = "Performance",
329
+ Run = performance("Traffic", "Outbound traffic at 260 KB/s against a threshold of 200 KB/s", 3, false),
330
+ },
331
+ {
332
+ Name = "TrafficCleared",
333
+ Group = "Performance",
334
+ Run = performance("Traffic", "Outbound traffic at 40 KB/s against a threshold of 200 KB/s", 0, true),
335
+ },
336
+ { Name = "Summary", Group = "Summaries", Run = summary("full") },
337
+ { Name = "SummaryNoSamples", Group = "Summaries", Run = summary("nosamples") },
338
+ { Name = "SummaryNoBudget", Group = "Summaries", Run = summary("nobudget") },
339
+ {
340
+ Name = "LongMessage",
341
+ Group = "Formatting",
342
+ Run = issue(
343
+ "Error",
344
+ "LONG_MESSAGE",
345
+ "Preview",
346
+ string.rep("A long message that would otherwise run past what an embed can carry. ", 60),
347
+ manyKeys
348
+ ),
349
+ },
350
+ {
351
+ Name = "RedactedContext",
352
+ Group = "Formatting",
353
+ Run = warning(
354
+ "REDACTED",
355
+ "Preview",
356
+ "A message naming a webhook https://discord.com/api/webhooks/1234/abcd and a player",
357
+ {
358
+ UserId = USER,
359
+ PlayerId = 7654321,
360
+ RecipientId = 1111111,
361
+ Note = "player ids are redacted unless IncludePlayerIds is on",
362
+ }
363
+ ),
364
+ },
365
+ } :: { Scenario })
366
+
367
+ local kinds = { "All" }
368
+ local seen: { [string]: boolean } = {}
369
+ for _, scenario in Preview.SCENARIOS do
370
+ if not seen[scenario.Group] then
371
+ seen[scenario.Group] = true
372
+ table.insert(kinds, scenario.Group)
373
+ end
374
+ end
375
+ for _, scenario in Preview.SCENARIOS do
376
+ table.insert(kinds, scenario.Name)
377
+ end
378
+ --- Every kind, in menu order.
379
+ Preview.KINDS = table.freeze(kinds)
380
+
381
+ --- Runs the scenarios `kind` names on `handle` under `preview`; returns why nothing ran, or nil.
382
+ function Preview.Run(handle: any, kind: string, preview: any): string?
383
+ local ran = 0
384
+ for _, scenario in Preview.SCENARIOS do
385
+ if kind == "All" or kind == scenario.Group or kind == scenario.Name then
386
+ scenario.Run(handle, preview)
387
+ ran += 1
388
+ end
389
+ end
390
+ if ran == 0 then
391
+ return `no preview named "{tostring(kind)}"`
392
+ end
393
+ return nil
394
+ end
395
+
396
+ return Preview
package/README.md ADDED
@@ -0,0 +1,5 @@
1
+ # @rbxts/scribe-telemetry
2
+
3
+ Optional Scribe addon. Install only if you use it.
4
+
5
+ See [the roblox-ts guide](https://scribe.ericplane.dev/roblox-ts/) for usage.