@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.
- package/CHANGELOG.md +20 -0
- package/README.md +26 -8
- package/dist/cjs/CallFact.d.ts +8 -8
- package/dist/cjs/Consensus.d.ts +26 -6
- package/dist/cjs/Consensus.d.ts.map +1 -1
- package/dist/cjs/Consensus.js +63 -22
- package/dist/cjs/Consensus.js.map +2 -2
- package/dist/cjs/EngineEvent.d.ts +23 -23
- package/dist/cjs/EngineEvent.d.ts.map +1 -1
- package/dist/cjs/EngineEvent.js +3 -2
- package/dist/cjs/EngineEvent.js.map +2 -2
- package/dist/cjs/ExecutionFact.d.ts +5 -5
- package/dist/cjs/Journal.d.ts +77 -2
- package/dist/cjs/Journal.d.ts.map +1 -1
- package/dist/cjs/Journal.js +1 -0
- package/dist/cjs/Journal.js.map +2 -2
- package/dist/cjs/JournalGeneration.d.ts +1 -1
- package/dist/cjs/JournalGeneration.d.ts.map +1 -1
- package/dist/cjs/JournalGeneration.js +10 -1
- package/dist/cjs/JournalGeneration.js.map +2 -2
- package/dist/cjs/JournalMetrics.d.ts +41 -5
- package/dist/cjs/JournalMetrics.d.ts.map +1 -1
- package/dist/cjs/JournalMetrics.js +10 -1
- package/dist/cjs/JournalMetrics.js.map +2 -2
- package/dist/cjs/RedactedLogger.d.ts.map +1 -1
- package/dist/cjs/RedactedLogger.js +5 -3
- package/dist/cjs/RedactedLogger.js.map +2 -2
- package/dist/cjs/Redaction.d.ts +18 -1
- package/dist/cjs/Redaction.d.ts.map +1 -1
- package/dist/cjs/Redaction.js +142 -12
- package/dist/cjs/Redaction.js.map +3 -3
- package/dist/cjs/SqlConsensus.d.ts +4 -3
- package/dist/cjs/SqlConsensus.d.ts.map +1 -1
- package/dist/cjs/SqlConsensus.js +92 -59
- package/dist/cjs/SqlConsensus.js.map +2 -2
- package/dist/cjs/SqlJournal.d.ts.map +1 -1
- package/dist/cjs/SqlJournal.js +370 -131
- package/dist/cjs/SqlJournal.js.map +3 -3
- package/dist/cjs/StepFact.d.ts +1 -1
- package/dist/cjs/TelemetryLog.d.ts +241 -0
- package/dist/cjs/TelemetryLog.d.ts.map +1 -0
- package/dist/cjs/TelemetryLog.js +349 -0
- package/dist/cjs/TelemetryLog.js.map +7 -0
- package/dist/cjs/index.d.ts +5 -0
- package/dist/cjs/index.d.ts.map +1 -1
- package/dist/cjs/index.js +3 -1
- package/dist/cjs/index.js.map +2 -2
- package/dist/cjs/internal/EventTally.d.ts +31 -0
- package/dist/cjs/internal/EventTally.d.ts.map +1 -0
- package/dist/cjs/internal/EventTally.js +32 -0
- package/dist/cjs/internal/EventTally.js.map +7 -0
- package/dist/cjs/internal/JournalDigest.d.ts +24 -0
- package/dist/cjs/internal/JournalDigest.d.ts.map +1 -0
- package/dist/cjs/internal/JournalDigest.js +44 -0
- package/dist/cjs/internal/JournalDigest.js.map +7 -0
- package/dist/cjs/internal/JournalTestObserver.d.ts +41 -0
- package/dist/cjs/internal/JournalTestObserver.d.ts.map +1 -0
- package/dist/cjs/internal/JournalTestObserver.js +38 -0
- package/dist/cjs/internal/JournalTestObserver.js.map +7 -0
- package/dist/cjs/internal/TelemetryText.d.ts +28 -0
- package/dist/cjs/internal/TelemetryText.d.ts.map +1 -0
- package/dist/cjs/internal/TelemetryText.js +44 -0
- package/dist/cjs/internal/TelemetryText.js.map +7 -0
- package/dist/esm/CallFact.d.ts +8 -8
- package/dist/esm/Consensus.d.ts +26 -6
- package/dist/esm/Consensus.d.ts.map +1 -1
- package/dist/esm/Consensus.js +102 -21
- package/dist/esm/Consensus.js.map +1 -1
- package/dist/esm/EngineEvent.d.ts +23 -23
- package/dist/esm/EngineEvent.d.ts.map +1 -1
- package/dist/esm/EngineEvent.js +4 -2
- package/dist/esm/EngineEvent.js.map +1 -1
- package/dist/esm/ExecutionFact.d.ts +5 -5
- package/dist/esm/Journal.d.ts +77 -2
- package/dist/esm/Journal.d.ts.map +1 -1
- package/dist/esm/Journal.js +4 -1
- package/dist/esm/Journal.js.map +1 -1
- package/dist/esm/JournalGeneration.d.ts +1 -1
- package/dist/esm/JournalGeneration.d.ts.map +1 -1
- package/dist/esm/JournalGeneration.js +9 -1
- package/dist/esm/JournalGeneration.js.map +1 -1
- package/dist/esm/JournalMetrics.d.ts +41 -5
- package/dist/esm/JournalMetrics.d.ts.map +1 -1
- package/dist/esm/JournalMetrics.js +38 -6
- package/dist/esm/JournalMetrics.js.map +1 -1
- package/dist/esm/RedactedLogger.d.ts.map +1 -1
- package/dist/esm/RedactedLogger.js +9 -5
- package/dist/esm/RedactedLogger.js.map +1 -1
- package/dist/esm/Redaction.d.ts +18 -1
- package/dist/esm/Redaction.d.ts.map +1 -1
- package/dist/esm/Redaction.js +199 -16
- package/dist/esm/Redaction.js.map +1 -1
- package/dist/esm/SqlConsensus.d.ts +4 -3
- package/dist/esm/SqlConsensus.d.ts.map +1 -1
- package/dist/esm/SqlConsensus.js +34 -22
- package/dist/esm/SqlConsensus.js.map +1 -1
- package/dist/esm/SqlJournal.d.ts.map +1 -1
- package/dist/esm/SqlJournal.js +410 -108
- package/dist/esm/SqlJournal.js.map +1 -1
- package/dist/esm/StepFact.d.ts +1 -1
- package/dist/esm/TelemetryLog.d.ts +241 -0
- package/dist/esm/TelemetryLog.d.ts.map +1 -0
- package/dist/esm/TelemetryLog.js +519 -0
- package/dist/esm/TelemetryLog.js.map +1 -0
- package/dist/esm/index.d.ts +5 -0
- package/dist/esm/index.d.ts.map +1 -1
- package/dist/esm/index.js +5 -0
- package/dist/esm/index.js.map +1 -1
- package/dist/esm/internal/EventTally.d.ts +31 -0
- package/dist/esm/internal/EventTally.d.ts.map +1 -0
- package/dist/esm/internal/EventTally.js +27 -0
- package/dist/esm/internal/EventTally.js.map +1 -0
- package/dist/esm/internal/JournalDigest.d.ts +24 -0
- package/dist/esm/internal/JournalDigest.d.ts.map +1 -0
- package/dist/esm/internal/JournalDigest.js +27 -0
- package/dist/esm/internal/JournalDigest.js.map +1 -0
- package/dist/esm/internal/JournalTestObserver.d.ts +41 -0
- package/dist/esm/internal/JournalTestObserver.d.ts.map +1 -0
- package/dist/esm/internal/JournalTestObserver.js +17 -0
- package/dist/esm/internal/JournalTestObserver.js.map +1 -0
- package/dist/esm/internal/TelemetryText.d.ts +28 -0
- package/dist/esm/internal/TelemetryText.d.ts.map +1 -0
- package/dist/esm/internal/TelemetryText.js +28 -0
- package/dist/esm/internal/TelemetryText.js.map +1 -0
- package/docs/README.md +6 -5
- package/docs/api.md +244 -49
- package/docs/concepts/owner-fence.md +4 -1
- package/docs/concepts/redaction.md +45 -2
- package/docs/concepts/state-event-authority.md +5 -4
- package/docs/concepts/two-channels.md +3 -2
- package/docs/guides/read-a-run.md +8 -6
- package/docs/guides/redact-log-output.md +4 -2
- package/docs/guides/testing.md +4 -2
- package/docs/installation.md +23 -9
- package/docs/quickstart.md +58 -3
- package/docs/troubleshooting.md +4 -2
- package/package.json +21 -9
- package/src/Consensus.ts +118 -28
- package/src/EngineEvent.ts +6 -2
- package/src/Journal.ts +85 -2
- package/src/JournalGeneration.ts +13 -1
- package/src/JournalMetrics.ts +53 -6
- package/src/RedactedLogger.ts +10 -4
- package/src/Redaction.ts +252 -16
- package/src/SqlConsensus.ts +135 -83
- package/src/SqlJournal.ts +604 -179
- package/src/TelemetryLog.ts +597 -0
- package/src/index.ts +6 -0
- package/src/internal/EventTally.ts +39 -0
- package/src/internal/JournalDigest.ts +30 -0
- package/src/internal/JournalTestObserver.ts +48 -0
- 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
|
+
})
|