@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/Transport.luau ADDED
@@ -0,0 +1,498 @@
1
+ --!strict
2
+ -- Bounded asynchronous delivery: one lane per webhook URL and one worker per lane, so
3
+ -- a throttled or dead webhook never holds up another.
4
+
5
+ local Sanitize = require(script.Parent.Sanitize)
6
+
7
+ local Transport = {}
8
+ Transport.__index = Transport
9
+
10
+ export type Response = {
11
+ Ok: boolean,
12
+ Status: number?,
13
+ Headers: { [string]: string }?,
14
+ Body: string?,
15
+ Error: string?,
16
+ }
17
+
18
+ export type Http = { Post: (url: string, body: string) -> Response }
19
+ export type Clock = { Now: () -> number, Monotonic: () -> number }
20
+ export type Scheduler = { Spawn: (fn: () -> ()) -> (), Wait: (seconds: number) -> () }
21
+ export type Json = { Encode: (value: any) -> string, Decode: (text: string) -> any }
22
+
23
+ export type Deps = {
24
+ Http: Http,
25
+ Clock: Clock,
26
+ Scheduler: Scheduler,
27
+ Json: Json,
28
+ Jitter: () -> number, -- in [0, 1)
29
+ }
30
+
31
+ export type Dropped = {
32
+ Overflow: number,
33
+ Expired: number,
34
+ Malformed: number,
35
+ DeadDestination: number,
36
+ Exhausted: number,
37
+ Stopped: number,
38
+ Coalesced: number,
39
+ }
40
+
41
+ function Transport.EmptyDropped(): Dropped
42
+ return {
43
+ Overflow = 0,
44
+ Expired = 0,
45
+ Malformed = 0,
46
+ DeadDestination = 0,
47
+ Exhausted = 0,
48
+ Stopped = 0,
49
+ Coalesced = 0,
50
+ }
51
+ end
52
+
53
+ export type Stats = {
54
+ Queued: number,
55
+ QueuedBytes: number,
56
+ Delivered: number,
57
+ Retries: number,
58
+ Uncertain: number,
59
+ Dropped: Dropped,
60
+ LastDeliveredAt: number?,
61
+ Destinations: { [string]: DestinationStats },
62
+ }
63
+
64
+ export type Limits = {
65
+ MaxQueued: number,
66
+ MaxQueuedBytes: number,
67
+ PerDestinationQueued: number,
68
+ MaxAge: number,
69
+ MaxAttempts: number,
70
+ MaxRetryDelay: number,
71
+ }
72
+
73
+ type Item = {
74
+ Id: string,
75
+ Destination: string,
76
+ Category: string,
77
+ GroupKey: string?,
78
+ Priority: number,
79
+ Payload: string,
80
+ Bytes: number,
81
+ CreatedAt: number,
82
+ ExpiresAt: number,
83
+ NotBefore: number,
84
+ Attempts: number,
85
+ InFlight: boolean,
86
+ }
87
+
88
+ type Lane = {
89
+ Url: string,
90
+ Queue: { Item },
91
+ Bytes: number,
92
+ NotBefore: number, -- rate-limit pacing, monotonic
93
+ Dead: boolean,
94
+ Working: boolean,
95
+ }
96
+
97
+ export type DestinationStats = {
98
+ State: string, -- Ready, Dead, Stopped
99
+ Queued: number,
100
+ Delivered: number,
101
+ Failures: number,
102
+ LastDeliveredAt: number?,
103
+ LastError: string?,
104
+ }
105
+
106
+ local DEAD_STATUSES = { [401] = true, [403] = true, [404] = true, [410] = true }
107
+ local MALFORMED_STATUSES = { [400] = true, [413] = true, [422] = true }
108
+
109
+ local function header(headers: { [string]: string }?, name: string): string?
110
+ if headers == nil then
111
+ return nil
112
+ end
113
+ local lower = string.lower(name)
114
+ for key, value in headers do
115
+ if string.lower(key) == lower then
116
+ return value
117
+ end
118
+ end
119
+ return nil
120
+ end
121
+
122
+ function Transport.new(limits: Limits, deps: Deps)
123
+ local self = setmetatable({}, Transport)
124
+ self.limits = limits
125
+ self.deps = deps
126
+ self.running = true
127
+ self.lanes = {} :: { [string]: Lane }
128
+ self.destinationLane = {} :: { [string]: string }
129
+ self.destinations = {} :: { [string]: DestinationStats }
130
+ self.queued = 0
131
+ self.queuedBytes = 0
132
+ self.stats = {
133
+ Delivered = 0,
134
+ Retries = 0,
135
+ Uncertain = 0,
136
+ Dropped = Transport.EmptyDropped(),
137
+ LastDeliveredAt = nil :: number?,
138
+ }
139
+ return self
140
+ end
141
+
142
+ --- Declares a destination. Two names on one URL share a lane.
143
+ function Transport.AddDestination(self: any, name: string, url: string)
144
+ self.destinationLane[name] = url
145
+ if self.lanes[url] == nil then
146
+ self.lanes[url] = { Url = url, Queue = {}, Bytes = 0, NotBefore = 0, Dead = false, Working = false }
147
+ end
148
+ self.destinations[name] =
149
+ { State = "Ready", Queued = 0, Delivered = 0, Failures = 0, LastDeliveredAt = nil, LastError = nil }
150
+ end
151
+
152
+ local function take(self: any, lane: Lane, index: number): Item
153
+ local item = table.remove(lane.Queue, index) :: Item
154
+ lane.Bytes -= item.Bytes
155
+ self.queued -= 1
156
+ self.queuedBytes -= item.Bytes
157
+ self.destinations[item.Destination].Queued -= 1
158
+ return item
159
+ end
160
+
161
+ local function dropItem(self: any, lane: Lane, index: number, reason: string)
162
+ take(self, lane, index)
163
+ self.stats.Dropped[reason] += 1
164
+ end
165
+
166
+ -- Short, and carrying no URL, so an echoed body or error is safe in LastError.
167
+ local function shortBody(body: string?): string
168
+ local text = if body then string.gsub(body, "%c", " ") else ""
169
+ text = string.gsub(text, "https?://%S+", "[url]")
170
+ return Sanitize.Truncate(text, 160)
171
+ end
172
+
173
+ -- Expired first, then the lowest priority no higher than `floor`, oldest among equals;
174
+ -- never the item in flight. Asked at most once per Enqueue, so it needs no plan.
175
+ local function victim(lane: Lane, now: number, floor: number): Item?
176
+ local best: Item? = nil
177
+ for _, item in lane.Queue do
178
+ if item.InFlight then
179
+ continue
180
+ end
181
+ if item.ExpiresAt <= now then
182
+ return item
183
+ end
184
+ if item.Priority <= floor and (best == nil or item.Priority < best.Priority) then
185
+ best = item
186
+ end
187
+ end
188
+ return best
189
+ end
190
+
191
+ -- Across every lane, oldest among equals: for a limit every lane shares.
192
+ local function globalVictim(self: any, now: number, floor: number, planned: { [Item]: boolean }): (Lane?, Item?)
193
+ local bestLane: Lane? = nil
194
+ local best: Item? = nil
195
+ for _, lane in self.lanes do
196
+ for _, item in lane.Queue do
197
+ if item.InFlight or planned[item] then
198
+ continue
199
+ end
200
+ if item.ExpiresAt <= now then
201
+ return lane, item
202
+ end
203
+ if item.Priority > floor then
204
+ continue
205
+ end
206
+ if
207
+ best == nil
208
+ or item.Priority < best.Priority
209
+ or (item.Priority == best.Priority and item.CreatedAt < best.CreatedAt)
210
+ then
211
+ bestLane, best = lane, item
212
+ end
213
+ end
214
+ end
215
+ return bestLane, best
216
+ end
217
+
218
+ --- Queues `payload` for `destination`. Returns false with a reason when it was refused.
219
+ function Transport.Enqueue(
220
+ self: any,
221
+ destination: string,
222
+ id: string,
223
+ category: string,
224
+ groupKey: string?,
225
+ priority: number,
226
+ payload: string
227
+ ): (boolean, string?)
228
+ if not self.running then
229
+ return false, "stopped"
230
+ end
231
+ local url = self.destinationLane[destination]
232
+ local lane: Lane? = if url then self.lanes[url] else nil
233
+ if lane == nil then
234
+ return false, "unknown-destination"
235
+ end
236
+ if lane.Dead then
237
+ self.stats.Dropped.DeadDestination += 1
238
+ return false, "dead-destination"
239
+ end
240
+ local now = self.deps.Clock.Monotonic()
241
+ local bytes = #payload
242
+ -- A repetition summary supersedes the one still waiting for the same group.
243
+ if groupKey ~= nil then
244
+ for _, queued in lane.Queue do
245
+ if queued.GroupKey == groupKey and not queued.InFlight then
246
+ if self.queuedBytes + bytes - queued.Bytes > self.limits.MaxQueuedBytes then
247
+ self.stats.Dropped.Overflow += 1
248
+ return false, "overflow"
249
+ end
250
+ lane.Bytes += bytes - queued.Bytes
251
+ self.queuedBytes += bytes - queued.Bytes
252
+ queued.Payload = payload
253
+ queued.Bytes = bytes
254
+ queued.Id = id
255
+ queued.CreatedAt = now
256
+ queued.ExpiresAt = now + self.limits.MaxAge
257
+ self.stats.Dropped.Coalesced += 1
258
+ return true, nil
259
+ end
260
+ end
261
+ end
262
+ -- Planned first, so a report no eviction could admit leaves the queue untouched. A full
263
+ -- lane gives up one of its own; a shared limit takes the lowest priority anywhere.
264
+ local planned: { [Item]: boolean } = {}
265
+ local plan: { { Lane: Lane, Item: Item } } = {}
266
+ local laneCount, count, queuedBytes = #lane.Queue, self.queued, self.queuedBytes
267
+ while
268
+ laneCount >= self.limits.PerDestinationQueued
269
+ or count >= self.limits.MaxQueued
270
+ or queuedBytes + bytes > self.limits.MaxQueuedBytes
271
+ do
272
+ local target: Lane? = lane
273
+ local item: Item? = nil
274
+ if laneCount >= self.limits.PerDestinationQueued then
275
+ item = victim(lane, now, priority)
276
+ else
277
+ target, item = globalVictim(self, now, priority, planned)
278
+ end
279
+ if target == nil or item == nil then
280
+ self.stats.Dropped.Overflow += 1
281
+ return false, "overflow"
282
+ end
283
+ local chosenLane, chosen = target :: Lane, item :: Item
284
+ planned[chosen] = true
285
+ table.insert(plan, { Lane = chosenLane, Item = chosen })
286
+ count -= 1
287
+ queuedBytes -= chosen.Bytes
288
+ if chosenLane == lane then
289
+ laneCount -= 1
290
+ end
291
+ end
292
+ for _, entry in plan do
293
+ local index = table.find(entry.Lane.Queue, entry.Item)
294
+ if index ~= nil then
295
+ dropItem(self, entry.Lane, index, "Overflow")
296
+ end
297
+ end
298
+ table.insert(lane.Queue, {
299
+ Id = id,
300
+ Destination = destination,
301
+ Category = category,
302
+ GroupKey = groupKey,
303
+ Priority = priority,
304
+ Payload = payload,
305
+ Bytes = bytes,
306
+ CreatedAt = now,
307
+ ExpiresAt = now + self.limits.MaxAge,
308
+ NotBefore = 0,
309
+ Attempts = 0,
310
+ InFlight = false,
311
+ })
312
+ lane.Bytes += bytes
313
+ self.queued += 1
314
+ self.queuedBytes += bytes
315
+ self.destinations[destination].Queued += 1
316
+ self:startWorker(lane)
317
+ return true, nil
318
+ end
319
+
320
+ -- A zero would post again without yielding.
321
+ local RETRY_AFTER_MIN = 1
322
+
323
+ local function retryAfterSeconds(self: any, response: Response): number
324
+ local body = response.Body
325
+ local delay: number? = nil
326
+ if body ~= nil and body ~= "" then
327
+ local ok, decoded = pcall(self.deps.Json.Decode, body)
328
+ if ok and type(decoded) == "table" and type(decoded.retry_after) == "number" then
329
+ delay = decoded.retry_after
330
+ end
331
+ end
332
+ if delay == nil then
333
+ delay = tonumber(header(response.Headers, "Retry-After") or header(response.Headers, "X-RateLimit-Reset-After"))
334
+ end
335
+ return math.max(RETRY_AFTER_MIN, delay or 5)
336
+ end
337
+
338
+ local function markDead(self: any, lane: Lane, err: string)
339
+ lane.Dead = true
340
+ for name, url in self.destinationLane do
341
+ if url == lane.Url then
342
+ local stats = self.destinations[name]
343
+ stats.State = "Dead"
344
+ stats.LastError = err
345
+ end
346
+ end
347
+ while #lane.Queue > 0 do
348
+ dropItem(self, lane, 1, "DeadDestination")
349
+ end
350
+ end
351
+
352
+ function Transport.startWorker(self: any, lane: Lane)
353
+ if lane.Working then
354
+ return
355
+ end
356
+ lane.Working = true
357
+ self.deps.Scheduler.Spawn(function()
358
+ self:work(lane)
359
+ lane.Working = false
360
+ end)
361
+ end
362
+
363
+ function Transport.work(self: any, lane: Lane)
364
+ local limits: Limits = self.limits
365
+ while self.running and not lane.Dead do
366
+ local item: Item? = lane.Queue[1]
367
+ if item == nil then
368
+ return
369
+ end
370
+ local now = self.deps.Clock.Monotonic()
371
+ if item.ExpiresAt <= now then
372
+ dropItem(self, lane, 1, "Expired")
373
+ continue
374
+ end
375
+ local notBefore = math.max(lane.NotBefore, item.NotBefore)
376
+ if notBefore > now then
377
+ if notBefore >= item.ExpiresAt then
378
+ dropItem(self, lane, 1, "Expired")
379
+ continue
380
+ end
381
+ self.deps.Scheduler.Wait(notBefore - now)
382
+ continue
383
+ end
384
+
385
+ local stats: DestinationStats = self.destinations[item.Destination]
386
+ item.InFlight = true
387
+ local ok, response = pcall(self.deps.Http.Post, lane.Url, item.Payload)
388
+ item.InFlight = false
389
+ if not self.running then
390
+ return
391
+ end
392
+ local res: Response = if ok then response else { Ok = false, Error = tostring(response) }
393
+ now = self.deps.Clock.Monotonic()
394
+ -- Still the head: evictions skip it and enqueues append.
395
+ local index = 1
396
+
397
+ if res.Ok and res.Status ~= nil and res.Status >= 200 and res.Status < 300 then
398
+ take(self, lane, index)
399
+ self.stats.Delivered += 1
400
+ self.stats.LastDeliveredAt = self.deps.Clock.Now()
401
+ stats.Delivered += 1
402
+ stats.Failures = 0
403
+ stats.LastDeliveredAt = self.stats.LastDeliveredAt
404
+ stats.State = "Ready"
405
+ if header(res.Headers, "X-RateLimit-Remaining") == "0" then
406
+ lane.NotBefore = now + (tonumber(header(res.Headers, "X-RateLimit-Reset-After")) or 1)
407
+ end
408
+ continue
409
+ end
410
+
411
+ local status = res.Status
412
+ if status == 429 then
413
+ local delay = retryAfterSeconds(self, res)
414
+ lane.NotBefore = now + delay
415
+ self.stats.Retries += 1
416
+ continue
417
+ end
418
+ if status ~= nil and DEAD_STATUSES[status] then
419
+ local reason = `webhook refused with HTTP {status}`
420
+ if status == 403 and string.match(lane.Url, "^https://[%w%.%-]*discord%.com/") then
421
+ reason ..= "; Discord refuses requests from Roblox servers, so route the webhook through a proxy"
422
+ end
423
+ markDead(self, lane, reason)
424
+ return
425
+ end
426
+ if status ~= nil and MALFORMED_STATUSES[status] then
427
+ stats.LastError = `HTTP {status}: {shortBody(res.Body)}`
428
+ dropItem(self, lane, index, "Malformed")
429
+ continue
430
+ end
431
+
432
+ -- Transient; a timeout may have landed, hence Uncertain.
433
+ if res.Error ~= nil and string.find(string.lower(res.Error), "time", 1, true) then
434
+ self.stats.Uncertain += 1
435
+ end
436
+ stats.Failures += 1
437
+ stats.LastError = if status then `HTTP {status}` else shortBody(tostring(res.Error or "request failed"))
438
+ item.Attempts += 1
439
+ if item.Attempts >= limits.MaxAttempts then
440
+ dropItem(self, lane, index, "Exhausted")
441
+ continue
442
+ end
443
+ local backoff = math.min(limits.MaxRetryDelay, 2 ^ (item.Attempts - 1)) * (0.5 + self.deps.Jitter())
444
+ item.NotBefore = now + backoff
445
+ self.stats.Retries += 1
446
+ if item.NotBefore >= item.ExpiresAt then
447
+ dropItem(self, lane, index, "Expired")
448
+ end
449
+ end
450
+ end
451
+
452
+ --- Waits until every lane is empty, or `timeout` seconds. Returns whether it drained.
453
+ function Transport.Flush(self: any, timeout: number): boolean
454
+ local deadline = self.deps.Clock.Monotonic() + timeout
455
+ while self.running and self.queued > 0 do
456
+ if self.deps.Clock.Monotonic() >= deadline then
457
+ return false
458
+ end
459
+ self.deps.Scheduler.Wait(0.05)
460
+ end
461
+ return self.queued == 0
462
+ end
463
+
464
+ --- Stops delivery. Queued items are released; a request already in flight may complete,
465
+ --- but its result starts nothing.
466
+ function Transport.Stop(self: any)
467
+ if not self.running then
468
+ return
469
+ end
470
+ self.running = false
471
+ for _, lane in self.lanes do
472
+ while #lane.Queue > 0 do
473
+ dropItem(self, lane, 1, "Stopped")
474
+ end
475
+ end
476
+ for _, stats in self.destinations do
477
+ stats.State = "Stopped"
478
+ end
479
+ end
480
+
481
+ function Transport.Stats(self: any): Stats
482
+ local destinations = {}
483
+ for name, stats in self.destinations do
484
+ destinations[name] = table.clone(stats)
485
+ end
486
+ return {
487
+ Queued = self.queued,
488
+ QueuedBytes = self.queuedBytes,
489
+ Delivered = self.stats.Delivered,
490
+ Retries = self.stats.Retries,
491
+ Uncertain = self.stats.Uncertain,
492
+ Dropped = table.clone(self.stats.Dropped),
493
+ LastDeliveredAt = self.stats.LastDeliveredAt,
494
+ Destinations = destinations,
495
+ }
496
+ end
497
+
498
+ return Transport
package/index.d.ts ADDED
@@ -0,0 +1,150 @@
1
+ import type Scribe from "@rbxts/scribe";
2
+
3
+ /** Optional server-side diagnostics reporter. Importing it does not start reporting. */
4
+ declare namespace ScribeTelemetry {
5
+ const Version: string;
6
+ const LogoUrl: string;
7
+ const DefaultWarningCodes: readonly string[];
8
+ type LogEntry = Scribe.LogEntry;
9
+
10
+ type Category = "Health" | "Issues" | "Warnings" | "Performance" | "Summaries" | "Leaderboards";
11
+ type MentionKind = "Fatal" | "Error" | "Outage" | "Degraded" | "Recovery" | "Performance";
12
+ type Route<Destination extends string = string> = Destination | readonly Destination[] | false;
13
+ type PreviewKind =
14
+ | "All" | "Health" | "Issues" | "Warnings" | "Grouping" | "Performance" | "Leaderboards" | "Summaries" | "Formatting"
15
+ | "HealthyStartup" | "Degraded" | "Outage" | "PartialRecovery" | "Recovery" | "IncidentUnderway"
16
+ | "Warning" | "Error" | "Fatal" | "Repeat" | "UpstreamSuppressed"
17
+ | "SlowLoad" | "SlowLeavingHook" | "ReceiptCapacity" | "ReceiptRoutingRetry"
18
+ | "LeaderboardDegraded" | "LeaderboardRecovery"
19
+ | "SlowSaves" | "SlowSavesCleared" | "SaveFailures" | "SaveFailuresCleared" | "Traffic" | "TrafficCleared"
20
+ | "Summary" | "SummaryNoSamples" | "SummaryNoBudget" | "LongMessage" | "RedactedContext";
21
+
22
+ interface WebhookOptions {
23
+ Url: string;
24
+ Enabled?: boolean;
25
+ Mention?: { RoleId: string; On?: readonly MentionKind[]; Cooldown?: number };
26
+ }
27
+ interface RuleOptions {
28
+ /** Positive threshold; a rule has no default threshold. */
29
+ Threshold: number;
30
+ MinSamples?: number;
31
+ Enabled?: boolean;
32
+ }
33
+ interface RuleSetOptions {
34
+ SlowSaves?: RuleOptions;
35
+ SaveFailures?: RuleOptions;
36
+ Traffic?: RuleOptions;
37
+ }
38
+ interface WarningOptions { Include?: readonly string[]; Categories?: readonly string[] }
39
+ interface IssueOptions { ExcludeCodes?: readonly string[]; ExcludeCategories?: readonly string[] }
40
+ interface GroupingOptions { Interval?: number; Expiry?: number; MaxGroups?: number }
41
+ interface SummaryOptions { Enabled?: boolean; Interval?: number }
42
+ /** Observes cached leaderboard snapshots; never requests a leaderboard refresh. */
43
+ interface LeaderboardOptions { Enabled?: boolean; Interval?: number; MaxBoards?: number }
44
+ interface PerformanceOptions { Interval?: number; Checks?: number; Rules?: RuleSetOptions }
45
+ interface LimitOptions {
46
+ MaxQueued?: number;
47
+ MaxQueuedBytes?: number;
48
+ PerDestination?: number;
49
+ MaxAge?: number;
50
+ MaxAttempts?: number;
51
+ MaxRetryDelay?: number;
52
+ }
53
+ interface HttpResponse {
54
+ Ok: boolean;
55
+ Status?: number;
56
+ Headers?: { [name: string]: string | undefined };
57
+ Body?: string;
58
+ Error?: string;
59
+ }
60
+ interface Http { readonly Post: (this: void, url: string, body: string) => HttpResponse }
61
+ interface Clock { readonly Now: (this: void) => number; readonly Monotonic: (this: void) => number }
62
+ interface Scheduler { readonly Spawn: (this: void, callback: (this: void) => void) => void; readonly Wait: (this: void, seconds: number) => void }
63
+ interface Json { readonly Encode: (this: void, value: unknown) => string; readonly Decode: (this: void, text: string) => unknown }
64
+
65
+ interface Options<Destination extends string = string> {
66
+ Webhooks: { [K in Destination]: WebhookOptions };
67
+ Default?: NoInfer<Destination>;
68
+ Routes?: Partial<Record<Category, Route<NoInfer<Destination>>>>;
69
+ Warnings?: WarningOptions;
70
+ Issues?: IssueOptions;
71
+ Grouping?: GroupingOptions;
72
+ Summaries?: SummaryOptions;
73
+ Leaderboards?: LeaderboardOptions;
74
+ Performance?: PerformanceOptions;
75
+ Limits?: LimitOptions;
76
+ IncludePlayerIds?: boolean;
77
+ Environment?: string;
78
+ AllowStudio?: boolean;
79
+ ReportHealthyStartup?: boolean;
80
+ /** Dependency seams for tests. Omit in normal game code. */
81
+ Http?: Http;
82
+ Clock?: Clock;
83
+ Scheduler?: Scheduler;
84
+ Json?: Json;
85
+ Jitter?: (this: void) => number;
86
+ Studio?: boolean;
87
+ }
88
+
89
+ interface Dropped {
90
+ Overflow: number;
91
+ Expired: number;
92
+ Malformed: number;
93
+ DeadDestination: number;
94
+ Exhausted: number;
95
+ Stopped: number;
96
+ Coalesced: number;
97
+ }
98
+ interface DestinationStats {
99
+ State: "Ready" | "Dead" | "Stopped";
100
+ Queued: number;
101
+ Delivered: number;
102
+ Failures: number;
103
+ LastDeliveredAt?: number;
104
+ LastError?: string;
105
+ }
106
+ type LeaderboardMonitorState = "Available" | "Unavailable" | "Disabled" | "DisabledInStudio" | "Stopped";
107
+ interface LeaderboardStats {
108
+ State: LeaderboardMonitorState;
109
+ Monitored: number;
110
+ Omitted: number;
111
+ SnapshotAge?: number;
112
+ LastError?: string;
113
+ }
114
+ interface Stats<Destination extends string = string> {
115
+ State: "Running" | "DisabledInStudio" | "Stopped";
116
+ Queued: number;
117
+ QueuedBytes: number;
118
+ Delivered: number;
119
+ Retries: number;
120
+ Uncertain: number;
121
+ Dropped: Dropped;
122
+ LastDeliveredAt?: number;
123
+ /** Empty when disabled in Studio; entries must be checked before reading. */
124
+ Destinations: Partial<Record<Destination, DestinationStats>>;
125
+ Reports: number;
126
+ Previews: number;
127
+ Skipped: Partial<Record<Category, number>>;
128
+ Filtered: { Issues: number; Warnings: number; Ignored: number };
129
+ Groups: number;
130
+ EncodeFailures: number;
131
+ LastTickError?: string;
132
+ Leaderboards: LeaderboardStats;
133
+ }
134
+ interface Handle<Destination extends string = string> {
135
+ Test(destination: Destination): LuaTuple<[boolean, string | undefined]>;
136
+ Preview(destination: Destination, kind?: PreviewKind): LuaTuple<[boolean, string | undefined]>;
137
+ Flush(timeout?: number): boolean;
138
+ GetStats(): Stats<Destination>;
139
+ Stop(): void;
140
+ }
141
+ type ScribeModule = Pick<typeof Scribe,
142
+ "AddLogSink" | "GetStatus" | "GetMetrics" | "GetPercentiles"
143
+ > & { readonly OnStatusChanged: Pick<typeof Scribe.OnStatusChanged, "Connect"> }
144
+ & Partial<Pick<typeof Scribe, "Version" | "GetBudgetSnapshot" | "GetLeaderboardSnapshot" | "GetProfileKeyPrefix" | "RegisterAddon">>;
145
+
146
+ /** One handle may run per Scribe module. Stop the previous handle before starting another. */
147
+ function Start<Destination extends string>(scribe: ScribeModule, options: Options<Destination>): Handle<Destination>;
148
+ }
149
+
150
+ export = ScribeTelemetry;