@smthrs/journal 1.0.0-rc.16 → 1.0.0-rc.18

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 (152) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +26 -8
  3. package/dist/cjs/CallFact.d.ts +8 -8
  4. package/dist/cjs/Consensus.d.ts +26 -6
  5. package/dist/cjs/Consensus.d.ts.map +1 -1
  6. package/dist/cjs/Consensus.js +63 -22
  7. package/dist/cjs/Consensus.js.map +2 -2
  8. package/dist/cjs/EngineEvent.d.ts +23 -23
  9. package/dist/cjs/EngineEvent.d.ts.map +1 -1
  10. package/dist/cjs/EngineEvent.js +3 -2
  11. package/dist/cjs/EngineEvent.js.map +2 -2
  12. package/dist/cjs/ExecutionFact.d.ts +5 -5
  13. package/dist/cjs/Journal.d.ts +77 -2
  14. package/dist/cjs/Journal.d.ts.map +1 -1
  15. package/dist/cjs/Journal.js +1 -0
  16. package/dist/cjs/Journal.js.map +2 -2
  17. package/dist/cjs/JournalGeneration.d.ts +1 -1
  18. package/dist/cjs/JournalGeneration.d.ts.map +1 -1
  19. package/dist/cjs/JournalGeneration.js +10 -1
  20. package/dist/cjs/JournalGeneration.js.map +2 -2
  21. package/dist/cjs/JournalMetrics.d.ts +41 -5
  22. package/dist/cjs/JournalMetrics.d.ts.map +1 -1
  23. package/dist/cjs/JournalMetrics.js +10 -1
  24. package/dist/cjs/JournalMetrics.js.map +2 -2
  25. package/dist/cjs/RedactedLogger.d.ts.map +1 -1
  26. package/dist/cjs/RedactedLogger.js +5 -3
  27. package/dist/cjs/RedactedLogger.js.map +2 -2
  28. package/dist/cjs/Redaction.d.ts +18 -1
  29. package/dist/cjs/Redaction.d.ts.map +1 -1
  30. package/dist/cjs/Redaction.js +142 -12
  31. package/dist/cjs/Redaction.js.map +3 -3
  32. package/dist/cjs/SqlConsensus.d.ts +4 -3
  33. package/dist/cjs/SqlConsensus.d.ts.map +1 -1
  34. package/dist/cjs/SqlConsensus.js +92 -59
  35. package/dist/cjs/SqlConsensus.js.map +2 -2
  36. package/dist/cjs/SqlJournal.d.ts.map +1 -1
  37. package/dist/cjs/SqlJournal.js +370 -131
  38. package/dist/cjs/SqlJournal.js.map +3 -3
  39. package/dist/cjs/StepFact.d.ts +1 -1
  40. package/dist/cjs/TelemetryLog.d.ts +241 -0
  41. package/dist/cjs/TelemetryLog.d.ts.map +1 -0
  42. package/dist/cjs/TelemetryLog.js +349 -0
  43. package/dist/cjs/TelemetryLog.js.map +7 -0
  44. package/dist/cjs/index.d.ts +5 -0
  45. package/dist/cjs/index.d.ts.map +1 -1
  46. package/dist/cjs/index.js +3 -1
  47. package/dist/cjs/index.js.map +2 -2
  48. package/dist/cjs/internal/EventTally.d.ts +31 -0
  49. package/dist/cjs/internal/EventTally.d.ts.map +1 -0
  50. package/dist/cjs/internal/EventTally.js +32 -0
  51. package/dist/cjs/internal/EventTally.js.map +7 -0
  52. package/dist/cjs/internal/JournalDigest.d.ts +24 -0
  53. package/dist/cjs/internal/JournalDigest.d.ts.map +1 -0
  54. package/dist/cjs/internal/JournalDigest.js +44 -0
  55. package/dist/cjs/internal/JournalDigest.js.map +7 -0
  56. package/dist/cjs/internal/JournalTestObserver.d.ts +41 -0
  57. package/dist/cjs/internal/JournalTestObserver.d.ts.map +1 -0
  58. package/dist/cjs/internal/JournalTestObserver.js +38 -0
  59. package/dist/cjs/internal/JournalTestObserver.js.map +7 -0
  60. package/dist/cjs/internal/TelemetryText.d.ts +28 -0
  61. package/dist/cjs/internal/TelemetryText.d.ts.map +1 -0
  62. package/dist/cjs/internal/TelemetryText.js +44 -0
  63. package/dist/cjs/internal/TelemetryText.js.map +7 -0
  64. package/dist/esm/CallFact.d.ts +8 -8
  65. package/dist/esm/Consensus.d.ts +26 -6
  66. package/dist/esm/Consensus.d.ts.map +1 -1
  67. package/dist/esm/Consensus.js +102 -21
  68. package/dist/esm/Consensus.js.map +1 -1
  69. package/dist/esm/EngineEvent.d.ts +23 -23
  70. package/dist/esm/EngineEvent.d.ts.map +1 -1
  71. package/dist/esm/EngineEvent.js +4 -2
  72. package/dist/esm/EngineEvent.js.map +1 -1
  73. package/dist/esm/ExecutionFact.d.ts +5 -5
  74. package/dist/esm/Journal.d.ts +77 -2
  75. package/dist/esm/Journal.d.ts.map +1 -1
  76. package/dist/esm/Journal.js +4 -1
  77. package/dist/esm/Journal.js.map +1 -1
  78. package/dist/esm/JournalGeneration.d.ts +1 -1
  79. package/dist/esm/JournalGeneration.d.ts.map +1 -1
  80. package/dist/esm/JournalGeneration.js +9 -1
  81. package/dist/esm/JournalGeneration.js.map +1 -1
  82. package/dist/esm/JournalMetrics.d.ts +41 -5
  83. package/dist/esm/JournalMetrics.d.ts.map +1 -1
  84. package/dist/esm/JournalMetrics.js +38 -6
  85. package/dist/esm/JournalMetrics.js.map +1 -1
  86. package/dist/esm/RedactedLogger.d.ts.map +1 -1
  87. package/dist/esm/RedactedLogger.js +9 -5
  88. package/dist/esm/RedactedLogger.js.map +1 -1
  89. package/dist/esm/Redaction.d.ts +18 -1
  90. package/dist/esm/Redaction.d.ts.map +1 -1
  91. package/dist/esm/Redaction.js +199 -16
  92. package/dist/esm/Redaction.js.map +1 -1
  93. package/dist/esm/SqlConsensus.d.ts +4 -3
  94. package/dist/esm/SqlConsensus.d.ts.map +1 -1
  95. package/dist/esm/SqlConsensus.js +34 -22
  96. package/dist/esm/SqlConsensus.js.map +1 -1
  97. package/dist/esm/SqlJournal.d.ts.map +1 -1
  98. package/dist/esm/SqlJournal.js +410 -108
  99. package/dist/esm/SqlJournal.js.map +1 -1
  100. package/dist/esm/StepFact.d.ts +1 -1
  101. package/dist/esm/TelemetryLog.d.ts +241 -0
  102. package/dist/esm/TelemetryLog.d.ts.map +1 -0
  103. package/dist/esm/TelemetryLog.js +519 -0
  104. package/dist/esm/TelemetryLog.js.map +1 -0
  105. package/dist/esm/index.d.ts +5 -0
  106. package/dist/esm/index.d.ts.map +1 -1
  107. package/dist/esm/index.js +5 -0
  108. package/dist/esm/index.js.map +1 -1
  109. package/dist/esm/internal/EventTally.d.ts +31 -0
  110. package/dist/esm/internal/EventTally.d.ts.map +1 -0
  111. package/dist/esm/internal/EventTally.js +27 -0
  112. package/dist/esm/internal/EventTally.js.map +1 -0
  113. package/dist/esm/internal/JournalDigest.d.ts +24 -0
  114. package/dist/esm/internal/JournalDigest.d.ts.map +1 -0
  115. package/dist/esm/internal/JournalDigest.js +27 -0
  116. package/dist/esm/internal/JournalDigest.js.map +1 -0
  117. package/dist/esm/internal/JournalTestObserver.d.ts +41 -0
  118. package/dist/esm/internal/JournalTestObserver.d.ts.map +1 -0
  119. package/dist/esm/internal/JournalTestObserver.js +17 -0
  120. package/dist/esm/internal/JournalTestObserver.js.map +1 -0
  121. package/dist/esm/internal/TelemetryText.d.ts +28 -0
  122. package/dist/esm/internal/TelemetryText.d.ts.map +1 -0
  123. package/dist/esm/internal/TelemetryText.js +28 -0
  124. package/dist/esm/internal/TelemetryText.js.map +1 -0
  125. package/docs/README.md +6 -5
  126. package/docs/api.md +244 -49
  127. package/docs/concepts/owner-fence.md +4 -1
  128. package/docs/concepts/redaction.md +45 -2
  129. package/docs/concepts/state-event-authority.md +5 -4
  130. package/docs/concepts/two-channels.md +3 -2
  131. package/docs/guides/read-a-run.md +8 -6
  132. package/docs/guides/redact-log-output.md +4 -2
  133. package/docs/guides/testing.md +4 -2
  134. package/docs/installation.md +23 -9
  135. package/docs/quickstart.md +58 -3
  136. package/docs/troubleshooting.md +4 -2
  137. package/package.json +21 -9
  138. package/src/Consensus.ts +118 -28
  139. package/src/EngineEvent.ts +6 -2
  140. package/src/Journal.ts +85 -2
  141. package/src/JournalGeneration.ts +13 -1
  142. package/src/JournalMetrics.ts +53 -6
  143. package/src/RedactedLogger.ts +10 -4
  144. package/src/Redaction.ts +252 -16
  145. package/src/SqlConsensus.ts +135 -83
  146. package/src/SqlJournal.ts +604 -179
  147. package/src/TelemetryLog.ts +597 -0
  148. package/src/index.ts +6 -0
  149. package/src/internal/EventTally.ts +39 -0
  150. package/src/internal/JournalDigest.ts +30 -0
  151. package/src/internal/JournalTestObserver.ts +48 -0
  152. package/src/internal/TelemetryText.ts +31 -0
@@ -0,0 +1,597 @@
1
+ /**
2
+ * The `telemetry.log` journal record: its durable schema and the bounded,
3
+ * redacted snapshot of an Effect log event that fills it.
4
+ *
5
+ * A log record is written to a run's journal on the lossy channel by two
6
+ * producers: `@smthrs/observability`'s `JournalLogger`, which forwards a whole
7
+ * process's logs to one run, and `@smthrs/engine-store`, which journals what an
8
+ * action attempt's body logs to the attempt's own run. Both build the payload
9
+ * here, so there is one schema and one snapshot. The module depends on nothing
10
+ * but Effect and this package's redaction rules, so it loads in a browser, a
11
+ * Worker, Node and Bun.
12
+ *
13
+ * The snapshot runs inside a logger callback: synchronously, on someone else's
14
+ * fiber, with an arbitrary logged value. It is therefore total (it never
15
+ * throws), detached (it copies the value before any asynchronous delivery, and
16
+ * never runs a caller's getter, `toJSON` or `toISOString`), bounded (in bytes,
17
+ * container members and depth, measured in one forward pass), and redacted
18
+ * before it returns.
19
+ *
20
+ * @since 1.0.0
21
+ */
22
+
23
+ import type * as Cause from "effect/Cause"
24
+ import * as Context from "effect/Context"
25
+ import type * as Logger from "effect/Logger"
26
+ import * as Option from "effect/Option"
27
+ import * as Redacted from "effect/Redacted"
28
+ import * as References from "effect/References"
29
+ import * as Schema from "effect/Schema"
30
+ import * as Tracer from "effect/Tracer"
31
+ import { type operations, TelemetryText } from "./internal/TelemetryText.ts"
32
+ import * as Redaction from "./Redaction.ts"
33
+
34
+ /**
35
+ * The journal event type every log record is written under.
36
+ *
37
+ * @category constants
38
+ * @since 1.0.0
39
+ */
40
+ export const eventType = "telemetry.log"
41
+
42
+ /**
43
+ * Largest encoded payload a snapshot produces, and the default bound.
44
+ *
45
+ * @category constants
46
+ * @since 1.0.0
47
+ */
48
+ export const maximumSnapshotBytes = 1024 * 1024
49
+
50
+ /**
51
+ * Largest number of container members copied into one snapshot.
52
+ *
53
+ * @category constants
54
+ * @since 1.0.0
55
+ */
56
+ export const maximumSnapshotMembers = 4_096
57
+
58
+ /**
59
+ * Deepest container path copied into one snapshot.
60
+ *
61
+ * @category constants
62
+ * @since 1.0.0
63
+ */
64
+ export const maximumSnapshotDepth = 64
65
+
66
+ /**
67
+ * What a hostile or unreadable logged value becomes.
68
+ *
69
+ * @category constants
70
+ * @since 1.0.0
71
+ */
72
+ export const unrenderableMarker = "[Unrenderable]"
73
+
74
+ /**
75
+ * What a value beyond a snapshot ceiling becomes.
76
+ *
77
+ * @category constants
78
+ * @since 1.0.0
79
+ */
80
+ export const truncatedMarker = "[Truncated]"
81
+
82
+ /**
83
+ * What an Effect `Redacted` value becomes: the wrapper's own rendering without
84
+ * its label, and never the value it hides.
85
+ *
86
+ * @category constants
87
+ * @since 1.0.0
88
+ */
89
+ export const redactedMarker = "<redacted>"
90
+
91
+ /**
92
+ * One typed failure retained from an Effect cause.
93
+ *
94
+ * @category schemas
95
+ * @since 1.0.0
96
+ */
97
+ export const Fail = Schema.Struct({
98
+ _tag: Schema.Literal("Fail"),
99
+ error: Schema.Unknown
100
+ })
101
+
102
+ /**
103
+ * One unexpected defect retained from an Effect cause.
104
+ *
105
+ * @category schemas
106
+ * @since 1.0.0
107
+ */
108
+ export const Die = Schema.Struct({
109
+ _tag: Schema.Literal("Die"),
110
+ defect: Schema.Unknown
111
+ })
112
+
113
+ /**
114
+ * One interruption retained from an Effect cause.
115
+ *
116
+ * @category schemas
117
+ * @since 1.0.0
118
+ */
119
+ export const Interrupt = Schema.Struct({
120
+ _tag: Schema.Literal("Interrupt"),
121
+ fiberId: Schema.NullOr(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)))
122
+ })
123
+
124
+ /**
125
+ * One reason in a persisted log cause.
126
+ *
127
+ * @category schemas
128
+ * @since 1.0.0
129
+ */
130
+ export const CauseReason = Schema.Union([Fail, Die, Interrupt])
131
+
132
+ /**
133
+ * One reason in a persisted log cause.
134
+ *
135
+ * @category models
136
+ * @since 1.0.0
137
+ */
138
+ export type CauseReason = typeof CauseReason.Type
139
+
140
+ /**
141
+ * A versioned structural Effect cause.
142
+ *
143
+ * Effect 4 stores composed failures as an ordered reason list. The projection
144
+ * preserves that order and each fail, defect, or interrupt discriminator.
145
+ *
146
+ * @category schemas
147
+ * @since 1.0.0
148
+ */
149
+ export const LogCause = Schema.Struct({
150
+ version: Schema.Literal(1),
151
+ reasons: Schema.Array(CauseReason)
152
+ })
153
+
154
+ /**
155
+ * A versioned structural Effect cause.
156
+ *
157
+ * @category models
158
+ * @since 1.0.0
159
+ */
160
+ export type LogCause = typeof LogCause.Type
161
+
162
+ /**
163
+ * Runtime schema for the log record payload written to the journal.
164
+ *
165
+ * `message` is what the logger was handed: Effect passes one array entry per
166
+ * argument. `annotations` are the fiber's log annotations at the moment of the
167
+ * call, and `timestamp` is that moment as ISO-8601 UTC.
168
+ *
169
+ * @category schemas
170
+ * @since 1.0.0
171
+ */
172
+ export const Log = Schema.Struct({
173
+ version: Schema.Literal(1),
174
+ level: Schema.Literals(["All", "Fatal", "Error", "Warn", "Info", "Debug", "Trace", "None"]),
175
+ message: Schema.Unknown,
176
+ annotations: Schema.Record(Schema.String, Schema.Unknown),
177
+ cause: LogCause,
178
+ fiberId: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
179
+ traceId: Schema.optionalKey(Schema.String),
180
+ spanId: Schema.optionalKey(Schema.String),
181
+ timestamp: Schema.String
182
+ })
183
+
184
+ /**
185
+ * Versioned log record payload written to the journal.
186
+ *
187
+ * @category models
188
+ * @since 1.0.0
189
+ */
190
+ export type Log = typeof Log.Type
191
+
192
+ /**
193
+ * How one {@link snapshot} is bounded, attributed and redacted.
194
+ *
195
+ * @category models
196
+ * @since 1.0.0
197
+ */
198
+ export interface SnapshotOptions {
199
+ /**
200
+ * Largest encoded payload, in UTF-8 bytes of its JSON, capped at
201
+ * {@link maximumSnapshotBytes}; a value that is not finite takes that cap.
202
+ * Given, the record's envelope is reserved first, so the message, annotations
203
+ * and cause share what remains and a long message is cut. Omitted, the values
204
+ * share {@link maximumSnapshotBytes} and a record whose envelope pushes it
205
+ * over degrades. A record that cannot fit either way keeps its level, time
206
+ * and {@link SnapshotOptions.annotations} and loses its message.
207
+ */
208
+ readonly maximumBytes?: number | undefined
209
+ /**
210
+ * Annotations copied ahead of the fiber's, winning over a fiber annotation
211
+ * of the same name and kept by every fallback record. For attribution the
212
+ * producer controls, such as run and step ids; never a value.
213
+ */
214
+ readonly annotations?: Readonly<Record<string, unknown>> | undefined
215
+ /**
216
+ * The redaction rules. Defaults to `Redaction.defaultRules`, the journal's
217
+ * write rules; a diagnostic producer passes `Redaction.diagnosticRules`.
218
+ */
219
+ readonly rules?: ReadonlyArray<Redaction.Rule> | undefined
220
+ }
221
+
222
+ interface SnapshotBudget {
223
+ readonly text: typeof operations
224
+ bytes: number
225
+ members: number
226
+ /** The configured ceiling: no text longer than this many units is measured whole. */
227
+ readonly limit: number
228
+ }
229
+
230
+ const reserve = (budget: SnapshotBudget, bytes: number): boolean => {
231
+ if (bytes > budget.bytes) return false
232
+ budget.bytes -= bytes
233
+ return true
234
+ }
235
+
236
+ const textBytes = (value: string, text: typeof operations): number => text.encode(JSON.stringify(value)).byteLength
237
+
238
+ const shortEscapes = new Set([0x08, 0x09, 0x0a, 0x0c, 0x0d])
239
+
240
+ /** Bytes one non-surrogate code unit occupies inside a JSON string body. */
241
+ const unitBytes = (code: number): number => {
242
+ if (code === 0x22 || code === 0x5c) return 2
243
+ if (code < 0x20) return shortEscapes.has(code) ? 2 : 6
244
+ if (code < 0x80) return 1
245
+ if (code < 0x800) return 2
246
+ return 3
247
+ }
248
+
249
+ const isLowSurrogate = (code: number): boolean => code >= 0xdc00 && code <= 0xdfff
250
+
251
+ /** Code units that occupy exactly one byte inside a JSON string body. */
252
+ const plainRun = /[\x20\x21\x23-\x5b\x5d-\x7f]*/y
253
+
254
+ /** One-byte units read one at a time before the rest of their run is matched natively. */
255
+ const plainStreak = 16
256
+
257
+ /**
258
+ * The longest prefix whose JSON string body fits `limit` bytes, measured in one
259
+ * forward pass. A surrogate pair is admitted or refused whole, so the retained
260
+ * text is well formed whenever the input is.
261
+ *
262
+ * Plain text is one byte per unit, so once a streak of it starts, the rest of
263
+ * the run is matched natively instead of unit by unit. The match reads a window
264
+ * one unit past the bytes still free, never the tail the cut drops.
265
+ */
266
+ const boundedPrefix = (
267
+ value: string,
268
+ limit: number,
269
+ text: typeof operations
270
+ ): { readonly text: string; readonly bytes: number } => {
271
+ let bytes = 0
272
+ let index = 0
273
+ let streak = 0
274
+ while (index < value.length) {
275
+ if (streak >= plainStreak) {
276
+ plainRun.lastIndex = 0
277
+ plainRun.test(value.slice(index, index + limit - bytes + 1))
278
+ const run = plainRun.lastIndex
279
+ const admitted = Math.min(run, limit - bytes)
280
+ bytes += admitted
281
+ index += admitted
282
+ if (admitted < run) break
283
+ streak = 0
284
+ continue
285
+ }
286
+ const code = text.charCodeAt(value, index)
287
+ let width = 1
288
+ let cost: number
289
+ if (code >= 0xd800 && code <= 0xdbff && isLowSurrogate(text.charCodeAt(value, index + 1))) {
290
+ width = 2
291
+ cost = 4
292
+ } else if (code >= 0xd800 && code <= 0xdfff) {
293
+ cost = 6
294
+ } else {
295
+ cost = unitBytes(code)
296
+ }
297
+ if (bytes + cost > limit) break
298
+ bytes += cost
299
+ index += width
300
+ streak = cost === 1 ? streak + 1 : 0
301
+ }
302
+ return { text: value.slice(0, index), bytes }
303
+ }
304
+
305
+ const boundedText = (value: string, budget: SnapshotBudget): string => {
306
+ if (value.length <= budget.limit && reserve(budget, textBytes(value, budget.text))) return value
307
+ const markerBytes = textBytes(truncatedMarker, budget.text)
308
+ const prefix = boundedPrefix(value, Math.max(0, budget.bytes - markerBytes), budget.text)
309
+ budget.bytes = Math.max(0, budget.bytes - prefix.bytes - markerBytes)
310
+ return `${prefix.text}${truncatedMarker}`
311
+ }
312
+
313
+ /**
314
+ * Error fields read through the prototype chain, in the order the snapshot
315
+ * projects them before any own data property the error added.
316
+ */
317
+ const standardErrorKeys = ["name", "message", "stack", "cause"] as const
318
+
319
+ /** Reads inherited data fields without invoking accessors or walking forever. */
320
+ const errorField = (value: object, key: string): unknown => {
321
+ let current: object | null = value
322
+ for (let depth = 0; current !== null && depth <= maximumSnapshotDepth; depth++) {
323
+ const descriptor = Object.getOwnPropertyDescriptor(current, key)
324
+ if (descriptor !== undefined) return "value" in descriptor ? descriptor.value : unrenderableMarker
325
+ current = Object.getPrototypeOf(current)
326
+ }
327
+ return current === null ? undefined : truncatedMarker
328
+ }
329
+
330
+ const snapshotValue = (
331
+ value: unknown,
332
+ budget: SnapshotBudget,
333
+ ancestors: WeakSet<object>,
334
+ depth = 0
335
+ ): unknown => {
336
+ if (budget.bytes <= 0) return truncatedMarker
337
+ if (depth > maximumSnapshotDepth) return Redaction.depthMarker
338
+ if (typeof value === "string") return boundedText(value, budget)
339
+ if (typeof value === "number") {
340
+ const projected = Number.isFinite(value) ? value : String(value)
341
+ reserve(budget, String(projected).length)
342
+ return projected
343
+ }
344
+ if (typeof value === "boolean" || value === null) {
345
+ reserve(budget, value === null ? 4 : value ? 4 : 5)
346
+ return value
347
+ }
348
+ if (typeof value === "bigint") return boundedText(`${value}n`, budget)
349
+ if (value === undefined) return boundedText("[Undefined]", budget)
350
+ if (typeof value === "function") return boundedText(Redaction.functionMarker, budget)
351
+ if (typeof value === "symbol") return boundedText(Redaction.symbolMarker, budget)
352
+ try {
353
+ if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
354
+ return boundedText(Redaction.binaryMarker, budget)
355
+ }
356
+ } catch {
357
+ return boundedText(unrenderableMarker, budget)
358
+ }
359
+ if (ancestors.has(value)) return boundedText("[Circular]", budget)
360
+ ancestors.add(value)
361
+ try {
362
+ // Effect keeps a `Redacted` value off the wrapper, so its own members show
363
+ // nothing; it is named instead, without running the wrapper's `toString`.
364
+ if (Redacted.isRedacted(value)) return boundedText(redactedMarker, budget)
365
+ if (value instanceof Date) {
366
+ try {
367
+ return boundedText(Date.prototype.toISOString.call(value), budget)
368
+ } catch {
369
+ return boundedText(unrenderableMarker, budget)
370
+ }
371
+ }
372
+ if (value instanceof Error) {
373
+ const record: Record<string, unknown> = Object.create(null)
374
+ for (const key of standardErrorKeys.slice(0, budget.members)) {
375
+ budget.members--
376
+ try {
377
+ record[key] = snapshotValue(errorField(value, key), budget, ancestors, depth + 1)
378
+ } catch {
379
+ record[key] = unrenderableMarker
380
+ }
381
+ }
382
+ // Tagged failures (`_tag`, domain fields) and system errors (`code`,
383
+ // `path`, `syscall`) keep their diagnostics as own data properties, so
384
+ // the walk that projects plain records runs over the remaining keys.
385
+ let names: ReadonlyArray<string>
386
+ try {
387
+ names = Object.getOwnPropertyNames(value).filter((key) =>
388
+ !(standardErrorKeys as ReadonlyArray<string>).includes(key)
389
+ )
390
+ } catch {
391
+ return record
392
+ }
393
+ let projected = 0
394
+ let collided = false
395
+ for (; projected < names.length && budget.members > 0; projected++) {
396
+ budget.members--
397
+ const key = names[projected]!
398
+ const boundedKey = boundedText(key, budget)
399
+ if (Object.hasOwn(record, boundedKey)) {
400
+ collided = true
401
+ continue
402
+ }
403
+ const descriptor = Object.getOwnPropertyDescriptor(value, key)
404
+ record[boundedKey] = descriptor !== undefined && "value" in descriptor
405
+ ? snapshotValue(descriptor.value, budget, ancestors, depth + 1)
406
+ : unrenderableMarker
407
+ }
408
+ if (collided || projected < names.length) record[truncatedMarker] = truncatedMarker
409
+ return record
410
+ }
411
+ if (Array.isArray(value)) {
412
+ const output: Array<unknown> = []
413
+ const length = value.length
414
+ for (let index = 0; index < length && budget.members > 0; index++) {
415
+ budget.members--
416
+ const descriptor = Object.getOwnPropertyDescriptor(value, String(index))
417
+ output.push(
418
+ descriptor === undefined || !("value" in descriptor)
419
+ ? unrenderableMarker
420
+ : snapshotValue(descriptor.value, budget, ancestors, depth + 1)
421
+ )
422
+ }
423
+ if (output.length < length) output.push(truncatedMarker)
424
+ return output
425
+ }
426
+ const record: Record<string, unknown> = Object.create(null)
427
+ const names = Object.getOwnPropertyNames(value)
428
+ for (let index = 0; index < names.length && budget.members > 0; index++) {
429
+ budget.members--
430
+ const key = names[index]!
431
+ const descriptor = Object.getOwnPropertyDescriptor(value, key)
432
+ const boundedKey = boundedText(key, budget)
433
+ // A key truncated to fit the budget can read exactly like one already
434
+ // copied. The first member keeps its slot; the later one is dropped and
435
+ // the record is marked truncated below rather than silently overwritten.
436
+ if (Object.hasOwn(record, boundedKey)) continue
437
+ record[boundedKey] = descriptor !== undefined && "value" in descriptor
438
+ ? snapshotValue(descriptor.value, budget, ancestors, depth + 1)
439
+ : unrenderableMarker
440
+ }
441
+ if (Object.keys(record).length < names.length) record[truncatedMarker] = truncatedMarker
442
+ return record
443
+ } catch {
444
+ return boundedText(unrenderableMarker, budget)
445
+ } finally {
446
+ ancestors.delete(value)
447
+ }
448
+ }
449
+
450
+ const snapshotCause = (cause: Cause.Cause<unknown>, budget: SnapshotBudget): LogCause => ({
451
+ version: 1,
452
+ reasons: cause.reasons.slice(0, maximumSnapshotMembers).map((reason): CauseReason => {
453
+ switch (reason._tag) {
454
+ case "Fail":
455
+ return { _tag: "Fail", error: snapshotValue(reason.error, budget, new WeakSet()) }
456
+ case "Die":
457
+ return { _tag: "Die", defect: snapshotValue(reason.defect, budget, new WeakSet()) }
458
+ case "Interrupt":
459
+ return { _tag: "Interrupt", fiberId: reason.fiberId ?? null }
460
+ }
461
+ })
462
+ })
463
+
464
+ const isLog = Schema.is(Log)
465
+
466
+ /**
467
+ * Annotations are a container in the durable schema, so a snapshot that spent
468
+ * the budget names the loss inside a record instead of replacing the record
469
+ * with a scalar the schema refuses.
470
+ */
471
+ const snapshotAnnotations = (value: unknown, budget: SnapshotBudget): Readonly<Record<string, unknown>> => {
472
+ const snapshot = snapshotValue(value, budget, new WeakSet())
473
+ return typeof snapshot === "object" && snapshot !== null && !Array.isArray(snapshot)
474
+ ? snapshot as Readonly<Record<string, unknown>>
475
+ : { [truncatedMarker]: truncatedMarker }
476
+ }
477
+
478
+ /**
479
+ * The fiber's annotations without the producer's names, which the producer's
480
+ * own values replace. An unusable reference contributes nothing beside them.
481
+ */
482
+ const others = (
483
+ fiberAnnotations: unknown,
484
+ own: Readonly<Record<string, unknown>>
485
+ ): Readonly<Record<string, unknown>> => {
486
+ if (typeof fiberAnnotations !== "object" || fiberAnnotations === null || Array.isArray(fiberAnnotations)) return {}
487
+ const copy: Record<string, unknown> = { ...fiberAnnotations }
488
+ for (const key of Object.keys(own)) delete copy[key]
489
+ return copy
490
+ }
491
+
492
+ /** The fiber's other annotations, copied only when there are any. */
493
+ const rest = (values: Readonly<Record<string, unknown>>, budget: SnapshotBudget): Readonly<Record<string, unknown>> =>
494
+ Object.keys(values).length === 0 ? {} : snapshotAnnotations(values, budget)
495
+
496
+ /**
497
+ * Snapshots one Effect log event into a bounded, redacted, decodable
498
+ * {@link Log}.
499
+ *
500
+ * Call it from inside a logger: it is synchronous and total. The returned
501
+ * value shares nothing with the logged one, so it can be queued for a later
502
+ * journal write. A projection that is too large or fails {@link Log} degrades
503
+ * to a record with a {@link truncatedMarker} message, and a projection that
504
+ * throws degrades to one with an {@link unrenderableMarker} message; both keep
505
+ * the level, timestamp and {@link SnapshotOptions.annotations}.
506
+ *
507
+ * @category constructors
508
+ * @since 1.0.0
509
+ */
510
+ export const snapshot = (options: Logger.Options<unknown>, settings: SnapshotOptions = {}): Log => {
511
+ const requested = settings.maximumBytes ?? maximumSnapshotBytes
512
+ const limit = Number.isFinite(requested)
513
+ ? Math.max(0, Math.min(maximumSnapshotBytes, Math.floor(requested)))
514
+ : maximumSnapshotBytes
515
+ const bounded = settings.maximumBytes !== undefined
516
+ const kept = settings.annotations ?? {}
517
+ try {
518
+ const text = Context.get(options.fiber.context, TelemetryText)
519
+ const span = Option.getOrUndefined(Context.getOption(options.fiber.context, Tracer.ParentSpan))
520
+ const ids = span === undefined ? {} : { traceId: span.traceId, spanId: span.spanId }
521
+ // An explicit bound is a bound on the whole record, so the envelope around
522
+ // the values is reserved first, with room for the marker that names
523
+ // annotations a spent budget dropped, and a long message is cut rather
524
+ // than costing the record its message.
525
+ const envelope = bounded
526
+ ? text.encode(JSON.stringify({
527
+ version: 1,
528
+ level: options.logLevel,
529
+ message: "",
530
+ annotations: { [truncatedMarker]: truncatedMarker },
531
+ cause: { version: 1, reasons: [] },
532
+ fiberId: options.fiber.id,
533
+ ...ids,
534
+ timestamp: options.date.toISOString()
535
+ })).byteLength
536
+ : 0
537
+ const project = (room: number) => {
538
+ const budget: SnapshotBudget = {
539
+ text,
540
+ bytes: Math.max(0, room - envelope),
541
+ members: maximumSnapshotMembers,
542
+ limit
543
+ }
544
+ // The producer's annotations are copied before anything the caller
545
+ // logged, so no message can spend the budget their attribution needs.
546
+ const own = settings.annotations === undefined ? undefined : snapshotAnnotations(settings.annotations, budget)
547
+ const message = typeof options.message === "string" ? "" : snapshotValue(options.message, budget, new WeakSet())
548
+ const fiberAnnotations = options.fiber.getRef(References.CurrentLogAnnotations)
549
+ let candidate: Log = {
550
+ version: 1,
551
+ level: options.logLevel,
552
+ message,
553
+ annotations: own === undefined
554
+ ? snapshotAnnotations(fiberAnnotations, budget)
555
+ : { ...own, ...rest(others(fiberAnnotations, own), budget), ...own },
556
+ cause: snapshotCause(options.cause, budget),
557
+ fiberId: options.fiber.id,
558
+ ...ids,
559
+ timestamp: options.date.toISOString()
560
+ }
561
+ // A scalar message can spend the whole value budget. Reserve the actual
562
+ // record envelope first so the final size check does not discard its prefix.
563
+ if (typeof options.message === "string") {
564
+ budget.bytes = Math.max(0, room - text.encode(JSON.stringify(candidate)).byteLength + 2)
565
+ candidate = { ...candidate, message: boundedText(options.message, budget) }
566
+ }
567
+ const redacted = Redaction.redact(candidate, { onTooDeep: "name", rules: settings.rules }) as Log
568
+ return { candidate, redacted, bytes: text.encode(JSON.stringify(redacted)).byteLength }
569
+ }
570
+ let projected = project(limit)
571
+ // The budget counts values, not the JSON punctuation between them, so a
572
+ // record under an explicit bound that still overflows is projected once
573
+ // more with the overflow taken off; the default bound keeps one pass.
574
+ if (bounded && projected.bytes > limit) projected = project(limit - (projected.bytes - limit) - 64)
575
+ // The durable row is only useful if the exported schema decodes it, so an
576
+ // oversized or schema-invalid projection degrades to the total record
577
+ // rather than to a payload every consumer throws on.
578
+ return projected.bytes <= limit && isLog(projected.redacted)
579
+ ? projected.redacted
580
+ : {
581
+ ...projected.candidate,
582
+ message: truncatedMarker,
583
+ annotations: kept,
584
+ cause: { version: 1, reasons: [] }
585
+ }
586
+ } catch {
587
+ return {
588
+ version: 1,
589
+ level: options.logLevel,
590
+ message: unrenderableMarker,
591
+ annotations: kept,
592
+ cause: { version: 1, reasons: [] },
593
+ fiberId: options.fiber.id,
594
+ timestamp: options.date.toISOString()
595
+ }
596
+ }
597
+ }
package/src/index.ts CHANGED
@@ -90,6 +90,12 @@ export * as Redaction from "./Redaction.ts"
90
90
  */
91
91
  export * as RedactedLogger from "./RedactedLogger.ts"
92
92
 
93
+ /**
94
+ * @category redaction
95
+ * @since 1.0.0
96
+ */
97
+ export * as TelemetryLog from "./TelemetryLog.ts"
98
+
93
99
  /**
94
100
  * @category projections
95
101
  * @since 0.1.0
@@ -0,0 +1,39 @@
1
+ /**
2
+ * The open `JournalMetrics.tally` scopes of the current fiber.
3
+ *
4
+ * @since 1.0.0
5
+ */
6
+
7
+ import { Context, Effect } from "effect"
8
+
9
+ /**
10
+ * One open tally: the entries committed inside it so far.
11
+ *
12
+ * @category internal
13
+ * @since 1.0.0
14
+ */
15
+ export interface Accumulator {
16
+ events: number
17
+ }
18
+
19
+ /**
20
+ * Every tally the current fiber runs inside, innermost last. A fiber forked
21
+ * inside a tally inherits it, so its entries count too.
22
+ *
23
+ * @category internal
24
+ * @since 1.0.0
25
+ */
26
+ export const Current = Context.Reference<ReadonlyArray<Accumulator>>("@smthrs/journal/EventTally", {
27
+ defaultValue: () => []
28
+ })
29
+
30
+ /**
31
+ * Adds `events` committed entries to every open tally.
32
+ *
33
+ * @category internal
34
+ * @since 1.0.0
35
+ */
36
+ export const record = (events: number): Effect.Effect<void> =>
37
+ Effect.gen(function*() {
38
+ for (const accumulator of yield* Current) accumulator.events += events
39
+ })
@@ -0,0 +1,30 @@
1
+ /**
2
+ * The fingerprint digest dependency, injectable for failure-path tests.
3
+ *
4
+ * @since 1.0.0
5
+ */
6
+
7
+ import * as Context from "effect/Context"
8
+ import * as Effect from "effect/Effect"
9
+
10
+ /**
11
+ * Hashes the canonical journal content with SHA-256.
12
+ *
13
+ * @category internal
14
+ * @since 1.0.0
15
+ */
16
+ export const digest = (bytes: Uint8Array<ArrayBuffer>): Effect.Effect<ArrayBuffer, unknown> =>
17
+ Effect.tryPromise({
18
+ try: () => crypto.subtle.digest("SHA-256", bytes),
19
+ catch: (cause) => cause
20
+ })
21
+
22
+ /**
23
+ * Defaults to the real digest; a faulty service can refuse a fingerprint.
24
+ *
25
+ * @category internal
26
+ * @since 1.0.0
27
+ */
28
+ export const JournalDigest = Context.Reference<{ readonly digest: typeof digest }>("@smthrs/journal/JournalDigest", {
29
+ defaultValue: () => ({ digest })
30
+ })