@intellectual-frontiers/ergonex 0.2.6 → 0.3.1
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/README.md +2 -0
- package/dist/desired.d.ts +27 -0
- package/dist/diff.d.ts +12 -0
- package/dist/doctor.d.ts +79 -0
- package/dist/findings.d.ts +85 -0
- package/dist/layout.d.ts +83 -0
- package/dist/manifest.d.ts +84 -0
- package/dist/mod.d.ts +29 -0
- package/dist/mod.js +3927 -0
- package/dist/modules/external.d.ts +31 -0
- package/dist/modules/mod.d.ts +10 -0
- package/dist/modules/name.d.ts +32 -0
- package/dist/modules/registry.d.ts +51 -0
- package/dist/modules/types.d.ts +178 -0
- package/dist/places.d.ts +35 -0
- package/dist/plan.d.ts +176 -0
- package/dist/platform/k-args.d.ts +7 -0
- package/dist/policy.d.ts +39 -0
- package/dist/portable.d.ts +111 -0
- package/dist/render.d.ts +95 -0
- package/dist/setup/evidence.d.ts +58 -0
- package/dist/shell/block.d.ts +45 -0
- package/dist/shell/mod.d.ts +8 -0
- package/dist/shell/snippet.d.ts +43 -0
- package/dist/state-record.d.ts +59 -0
- package/dist/state.d.ts +64 -0
- package/dist/templates/data.d.ts +25 -0
- package/dist/templates/hooks.d.ts +13 -0
- package/dist/templates/mod.d.ts +16 -0
- package/dist/tools/catalog.d.ts +70 -0
- package/dist/types.d.ts +51 -0
- package/dist/vendor/ts/githost/capabilities.d.ts +18 -0
- package/dist/vendor/ts/githost/git.d.ts +16 -0
- package/dist/vendor/ts/githost/github.d.ts +15 -0
- package/dist/vendor/ts/githost/gitlab.d.ts +15 -0
- package/dist/vendor/ts/githost/mod.d.ts +29 -0
- package/dist/vendor/ts/githost/remote.d.ts +59 -0
- package/dist/vendor/ts/githost/types.d.ts +101 -0
- package/dist/vendor/ts/kernel/archive.d.ts +147 -0
- package/dist/vendor/ts/kernel/assess.d.ts +247 -0
- package/dist/vendor/ts/kernel/attest.d.ts +164 -0
- package/dist/vendor/ts/kernel/base64.d.ts +24 -0
- package/dist/vendor/ts/kernel/cbor.d.ts +39 -0
- package/dist/vendor/ts/kernel/cms.d.ts +106 -0
- package/dist/vendor/ts/kernel/cose.d.ts +34 -0
- package/dist/vendor/ts/kernel/crypt.d.ts +30 -0
- package/dist/vendor/ts/kernel/csv.d.ts +38 -0
- package/dist/vendor/ts/kernel/der.d.ts +67 -0
- package/dist/vendor/ts/kernel/documentation.d.ts +118 -0
- package/dist/vendor/ts/kernel/dsse.d.ts +137 -0
- package/dist/vendor/ts/kernel/evidence.d.ts +212 -0
- package/dist/vendor/ts/kernel/glob.d.ts +64 -0
- package/dist/vendor/ts/kernel/grc.d.ts +356 -0
- package/dist/vendor/ts/kernel/http.d.ts +46 -0
- package/dist/vendor/ts/kernel/json5.d.ts +46 -0
- package/dist/vendor/ts/kernel/layers.d.ts +35 -0
- package/dist/vendor/ts/kernel/md5.d.ts +19 -0
- package/dist/vendor/ts/kernel/media-types.d.ts +28 -0
- package/dist/vendor/ts/kernel/mod.d.ts +89 -0
- package/dist/vendor/ts/kernel/ocsf-types.auto.d.ts +4374 -0
- package/dist/vendor/ts/kernel/ocsf.d.ts +160 -0
- package/dist/vendor/ts/kernel/oscal.d.ts +356 -0
- package/dist/vendor/ts/kernel/otel.d.ts +365 -0
- package/dist/vendor/ts/kernel/otlp.d.ts +83 -0
- package/dist/vendor/ts/kernel/png.d.ts +124 -0
- package/dist/vendor/ts/kernel/render.d.ts +111 -0
- package/dist/vendor/ts/kernel/schedule.d.ts +207 -0
- package/dist/vendor/ts/kernel/semver.d.ts +94 -0
- package/dist/vendor/ts/kernel/sha256.d.ts +29 -0
- package/dist/vendor/ts/kernel/signals.d.ts +371 -0
- package/dist/vendor/ts/kernel/sigv4.d.ts +67 -0
- package/dist/vendor/ts/kernel/test-record.d.ts +222 -0
- package/dist/vendor/ts/kernel/test-report.d.ts +294 -0
- package/dist/vendor/ts/kernel/toml.d.ts +51 -0
- package/dist/vendor/ts/kernel/trace.d.ts +169 -0
- package/dist/vendor/ts/kernel/ts-literal.d.ts +62 -0
- package/dist/vendor/ts/kernel/uuid.d.ts +53 -0
- package/dist/vendor/ts/kernel/webauthn.d.ts +212 -0
- package/dist/vendor/ts/kernel/xml.d.ts +73 -0
- package/dist/vendor/ts/kernel/yaml.d.ts +44 -0
- package/dist/vendor/ts/runtime/http-client.d.ts +149 -0
- package/ergonex.mjs +3480 -3765
- package/package.json +19 -5
|
@@ -0,0 +1,371 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Typed signals and the pipeline they go through (commons 0006-signals FR-009 to FR-013). `defineSignals` declares each kind of signal
|
|
3
|
+
* once (a span, a log event, or a counter, up-down counter, gauge or histogram), with its attributes and their types, a log event's
|
|
4
|
+
* severity, a metric's unit and bounds, the attributes that are secret, and its presentation role; emitting a kind that is not declared,
|
|
5
|
+
* an attribute of the wrong type or a missing required attribute does not compile. `createTelemetry` makes the tracer, logger and meter of
|
|
6
|
+
* one resource and scope from what the caller gives (a clock, a source of random bytes, a context manager, a parent), so a span tree is
|
|
7
|
+
* the same every run; it redacts (FR-006), applies the limits (FR-007) and samples (FR-008), and hands every signal, in the order it was
|
|
8
|
+
* made, to its processors: the in-memory one, the simple one and the batch one, whose `forceFlush` and `shutdown` resolve within their
|
|
9
|
+
* time whatever an exporter does.
|
|
10
|
+
*
|
|
11
|
+
* @example
|
|
12
|
+
* ```ts
|
|
13
|
+
* import { createTelemetry, defineSignals, memoryProcessor } from "./signals.js";
|
|
14
|
+
* import { ok } from "@intellectual-frontiers/core";
|
|
15
|
+
* const registry = defineSignals({
|
|
16
|
+
* "build.step": { signal: "span", role: "step", attributes: { target: "string", "jobs?": "int" } },
|
|
17
|
+
* "build.files": { signal: "counter", role: "none", unit: "{file}", attributes: { target: "string" } },
|
|
18
|
+
* });
|
|
19
|
+
* const memory = memoryProcessor();
|
|
20
|
+
* let t = 0n;
|
|
21
|
+
* const telemetry = createTelemetry({
|
|
22
|
+
* registry, resource: { attributes: { "service.name": "build" } }, scope: { name: "build" },
|
|
23
|
+
* clock: () => t++, random: (n) => new Uint8Array(n).fill(7), processors: [memory],
|
|
24
|
+
* });
|
|
25
|
+
* telemetry.span("build.step", { target: "site" }, () => {
|
|
26
|
+
* telemetry.add("build.files", 3, { target: "site" });
|
|
27
|
+
* return ok("built");
|
|
28
|
+
* });
|
|
29
|
+
* memory.spans[0]?.status; // { kind: "ok" }
|
|
30
|
+
* ```
|
|
31
|
+
*
|
|
32
|
+
* @module
|
|
33
|
+
*/
|
|
34
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
35
|
+
import { type AnyValue, type Attributes, type Limits, type LogRecord, type Metric, type Resource, type Sampler, type Scope, type SeverityNumber, type SignalName, type SpanContext, type SpanData, type SpanEvent, type SpanId, type SpanKind, type TraceId, type TraceState } from "./otel.js";
|
|
36
|
+
import { type LogBatch, type MetricBatch, type TraceBatch } from "./otlp.js";
|
|
37
|
+
/** The type of a declared attribute. `int` takes a `number` (cut to an integer) or a `bigint`, and is written as an OTLP integer. */
|
|
38
|
+
export type AttributeType = "string" | "boolean" | "int" | "double" | "bytes" | "string[]" | "boolean[]" | "int[]" | "double[]";
|
|
39
|
+
/** The attributes a kind declares: a name (ending in `?` where it is optional) to its type. */
|
|
40
|
+
export type AttributeSchema = Readonly<Record<string, AttributeType>>;
|
|
41
|
+
/** The value an attribute of a type takes. */
|
|
42
|
+
export type AttributeValueOf = {
|
|
43
|
+
readonly string: string;
|
|
44
|
+
readonly boolean: boolean;
|
|
45
|
+
readonly int: number | bigint;
|
|
46
|
+
readonly double: number;
|
|
47
|
+
readonly bytes: Uint8Array;
|
|
48
|
+
readonly "string[]": readonly string[];
|
|
49
|
+
readonly "boolean[]": readonly boolean[];
|
|
50
|
+
readonly "int[]": readonly (number | bigint)[];
|
|
51
|
+
readonly "double[]": readonly number[];
|
|
52
|
+
};
|
|
53
|
+
type Simplify<T> = {
|
|
54
|
+
[K in keyof T]: T[K];
|
|
55
|
+
} & {};
|
|
56
|
+
/** The attributes object a schema asks for: its required names, and its optional ones (declared with `?`) without the `?`. */
|
|
57
|
+
export type AttributesFor<S extends AttributeSchema> = Simplify<{
|
|
58
|
+
readonly [K in keyof S & string as K extends `${string}?` ? never : K]: AttributeValueOf[S[K]];
|
|
59
|
+
} & {
|
|
60
|
+
readonly [K in keyof S & string as K extends `${infer N}?` ? N : never]?: AttributeValueOf[S[K]];
|
|
61
|
+
}>;
|
|
62
|
+
/**
|
|
63
|
+
* How a kind is presented to a person: the renderer shows every role but `none`. `pending` (⏳, not set up yet) and `action` (⚡, a step
|
|
64
|
+
* that is the person's to take) are neither warnings nor errors (FR-027).
|
|
65
|
+
*/
|
|
66
|
+
export type Role = "step" | "detail" | "progress" | "result" | "hint" | "warning" | "error" | "pending" | "action" | "none";
|
|
67
|
+
type Common = {
|
|
68
|
+
/** The kind's attributes and their types. */
|
|
69
|
+
readonly attributes: AttributeSchema;
|
|
70
|
+
/** How a renderer presents it. */
|
|
71
|
+
readonly role: Role;
|
|
72
|
+
/** What the kind is, for a reader of the registry. */
|
|
73
|
+
readonly description?: string;
|
|
74
|
+
/** Attributes that are secret: never written anywhere (FR-006). */
|
|
75
|
+
readonly secret?: readonly string[];
|
|
76
|
+
};
|
|
77
|
+
/** A kind of span; its span kind is `internal` unless said. */
|
|
78
|
+
export type SpanDeclaration = Common & {
|
|
79
|
+
readonly signal: "span";
|
|
80
|
+
readonly spanKind?: SpanKind;
|
|
81
|
+
};
|
|
82
|
+
/** A kind of log event, with its severity. */
|
|
83
|
+
export type LogDeclaration = Common & {
|
|
84
|
+
readonly signal: "log";
|
|
85
|
+
readonly severity: SeverityNumber;
|
|
86
|
+
};
|
|
87
|
+
/** A kind of counter (monotonic), up-down counter or gauge, with its unit (UCUM, as `ms`, `By`, `{file}`). */
|
|
88
|
+
export type InstrumentDeclaration = Common & {
|
|
89
|
+
readonly signal: "counter" | "updown" | "gauge";
|
|
90
|
+
readonly unit: string;
|
|
91
|
+
};
|
|
92
|
+
/** A kind of histogram, with its unit and, optionally, its explicit bucket bounds (OpenTelemetry's defaults otherwise). */
|
|
93
|
+
export type HistogramDeclaration = Common & {
|
|
94
|
+
readonly signal: "histogram";
|
|
95
|
+
readonly unit: string;
|
|
96
|
+
readonly bounds?: readonly number[];
|
|
97
|
+
};
|
|
98
|
+
/** The declaration of one kind of signal. */
|
|
99
|
+
export type SignalDeclaration = SpanDeclaration | LogDeclaration | InstrumentDeclaration | HistogramDeclaration;
|
|
100
|
+
/** What a declaration declares: `span`, `log`, `counter`, `updown`, `gauge` or `histogram`. */
|
|
101
|
+
export type SignalType = SignalDeclaration["signal"];
|
|
102
|
+
/** The declarations of a registry, by kind name. */
|
|
103
|
+
export type Declarations = Readonly<Record<string, SignalDeclaration>>;
|
|
104
|
+
/** A registry of signal kinds, made by `defineSignals`. */
|
|
105
|
+
export type Registry<R extends Declarations> = {
|
|
106
|
+
readonly kinds: R;
|
|
107
|
+
};
|
|
108
|
+
/** The names of the kinds of a registry's declarations that declare one of the signal types `S`. */
|
|
109
|
+
export type KindOf<R extends Declarations, S extends SignalType> = {
|
|
110
|
+
[K in keyof R & string]: R[K]["signal"] extends S ? K : never;
|
|
111
|
+
}[keyof R & string];
|
|
112
|
+
/** The attributes object a kind asks for. */
|
|
113
|
+
export type AttributesOf<R extends Declarations, K extends keyof R> = AttributesFor<R[K]["attributes"]>;
|
|
114
|
+
/**
|
|
115
|
+
* A registry of signal kinds (FR-009). The declarations are checked once here, and a mistake in them is a programming error that throws:
|
|
116
|
+
* an attribute type that does not exist, a secret attribute that is not declared, histogram bounds that do not increase.
|
|
117
|
+
*/
|
|
118
|
+
export declare function defineSignals<const R extends Declarations>(kinds: R): Registry<R>;
|
|
119
|
+
/** The presentation role of a kind, by its name (a span's name, a log record's `eventName`, a metric's name); undefined where not declared. */
|
|
120
|
+
export declare function roleOf(registry: Registry<Declarations>, name: string): Role | undefined;
|
|
121
|
+
/** The declaration of a kind, by its name; undefined where not declared. */
|
|
122
|
+
export declare function declarationOf(registry: Registry<Declarations>, name: string): SignalDeclaration | undefined;
|
|
123
|
+
/** Where the current span's context is kept: a synchronous stack here, `AsyncLocalStorage` in the runtime. */
|
|
124
|
+
export interface ContextManager {
|
|
125
|
+
/** The current context, if any. */
|
|
126
|
+
active(): SpanContext | undefined;
|
|
127
|
+
/** Runs `fn` with `context` current, and restores the previous one after it returns or throws. */
|
|
128
|
+
with<T>(context: SpanContext | undefined, fn: () => T): T;
|
|
129
|
+
}
|
|
130
|
+
/**
|
|
131
|
+
* A context manager on a synchronous stack: correct for synchronous code and up to the first `await` of an asynchronous function. Past it,
|
|
132
|
+
* use the span handle's own `span` and `log`, which name their parent, or the runtime's `AsyncLocalStorage` manager.
|
|
133
|
+
*/
|
|
134
|
+
export declare function stackContextManager(): ContextManager;
|
|
135
|
+
/** The resource and scope a signal came from; one object per telemetry, so a processor may group by it. */
|
|
136
|
+
export type Source = {
|
|
137
|
+
readonly resource: Resource;
|
|
138
|
+
readonly scope: Scope;
|
|
139
|
+
};
|
|
140
|
+
/** A span as it starts: what a renderer needs to show it in progress. */
|
|
141
|
+
export type SpanStart = {
|
|
142
|
+
readonly name: string;
|
|
143
|
+
readonly context: SpanContext;
|
|
144
|
+
readonly parentSpanId?: SpanId;
|
|
145
|
+
readonly kind: SpanKind;
|
|
146
|
+
readonly startTime: bigint;
|
|
147
|
+
readonly attributes: Attributes;
|
|
148
|
+
};
|
|
149
|
+
/** How a flush or a shutdown ended: everything handed on, or the time given ran out. */
|
|
150
|
+
export type FlushResult = {
|
|
151
|
+
readonly kind: "done";
|
|
152
|
+
} | {
|
|
153
|
+
readonly kind: "timeout";
|
|
154
|
+
};
|
|
155
|
+
/** What a pipeline hands its signals to, in the order they were made. */
|
|
156
|
+
export interface Processor {
|
|
157
|
+
/** A span started. */
|
|
158
|
+
onStart?(span: SpanStart, source: Source): void;
|
|
159
|
+
/** A span in progress recorded an event (`progress` among them). */
|
|
160
|
+
onEvent?(span: SpanStart, event: SpanEvent, source: Source): void;
|
|
161
|
+
/** A span ended. */
|
|
162
|
+
onEnd?(span: SpanData, source: Source): void;
|
|
163
|
+
/** A log record was emitted. */
|
|
164
|
+
onLog?(record: LogRecord, source: Source): void;
|
|
165
|
+
/** Metrics were collected. */
|
|
166
|
+
onMetrics?(metrics: readonly Metric[], source: Source): void;
|
|
167
|
+
/** Hands on everything held, within `timeoutMs`. */
|
|
168
|
+
forceFlush(timeoutMs: number): Promise<FlushResult>;
|
|
169
|
+
/** Hands on everything held and stops, within `timeoutMs`. */
|
|
170
|
+
shutdown(timeoutMs: number): Promise<FlushResult>;
|
|
171
|
+
}
|
|
172
|
+
/** How an export went. `partial`: the receiver rejected some signals. */
|
|
173
|
+
export type ExportResult = {
|
|
174
|
+
readonly kind: "success";
|
|
175
|
+
} | {
|
|
176
|
+
readonly kind: "partial";
|
|
177
|
+
readonly rejected: number;
|
|
178
|
+
readonly message: string;
|
|
179
|
+
} | {
|
|
180
|
+
readonly kind: "failure";
|
|
181
|
+
readonly message: string;
|
|
182
|
+
};
|
|
183
|
+
/** What sends batches somewhere (the runtime's OTLP/HTTP exporter, a test's fake). It may be slow, fail or never answer. */
|
|
184
|
+
export interface Exporter {
|
|
185
|
+
/** Sends trace batches. */
|
|
186
|
+
exportTraces(batches: readonly TraceBatch[]): Promise<ExportResult>;
|
|
187
|
+
/** Sends log batches. */
|
|
188
|
+
exportLogs(batches: readonly LogBatch[]): Promise<ExportResult>;
|
|
189
|
+
/** Sends metric batches. */
|
|
190
|
+
exportMetrics(batches: readonly MetricBatch[]): Promise<ExportResult>;
|
|
191
|
+
/** Stops, within `timeoutMs`. */
|
|
192
|
+
shutdown(timeoutMs: number): Promise<void>;
|
|
193
|
+
}
|
|
194
|
+
/** What a processor did with one signal: spans, log records or metric data points exported, failed, rejected by a partial success, or dropped. */
|
|
195
|
+
export type SignalStats = {
|
|
196
|
+
readonly exported: number;
|
|
197
|
+
readonly failed: number;
|
|
198
|
+
readonly rejected: number;
|
|
199
|
+
readonly dropped: number;
|
|
200
|
+
readonly lastError?: string;
|
|
201
|
+
};
|
|
202
|
+
/** What an exporting processor did, by signal. */
|
|
203
|
+
export type ProcessorStats = {
|
|
204
|
+
readonly [S in SignalName]: SignalStats;
|
|
205
|
+
};
|
|
206
|
+
/** A processor that exports, and says what it did. */
|
|
207
|
+
export type ExportingProcessor = Processor & {
|
|
208
|
+
stats(): ProcessorStats;
|
|
209
|
+
};
|
|
210
|
+
/** A recorded signal, in the order the memory processor received it. */
|
|
211
|
+
export type MemoryEntry = {
|
|
212
|
+
readonly kind: "start";
|
|
213
|
+
readonly span: SpanStart;
|
|
214
|
+
readonly source: Source;
|
|
215
|
+
} | {
|
|
216
|
+
readonly kind: "event";
|
|
217
|
+
readonly span: SpanStart;
|
|
218
|
+
readonly event: SpanEvent;
|
|
219
|
+
readonly source: Source;
|
|
220
|
+
} | {
|
|
221
|
+
readonly kind: "end";
|
|
222
|
+
readonly span: SpanData;
|
|
223
|
+
readonly source: Source;
|
|
224
|
+
} | {
|
|
225
|
+
readonly kind: "log";
|
|
226
|
+
readonly record: LogRecord;
|
|
227
|
+
readonly source: Source;
|
|
228
|
+
} | {
|
|
229
|
+
readonly kind: "metrics";
|
|
230
|
+
readonly metrics: readonly Metric[];
|
|
231
|
+
readonly source: Source;
|
|
232
|
+
};
|
|
233
|
+
/** A processor that keeps everything, for tests and the renderer. */
|
|
234
|
+
export type MemoryProcessor = Processor & {
|
|
235
|
+
/** Every signal, in order. */
|
|
236
|
+
readonly entries: readonly MemoryEntry[];
|
|
237
|
+
/** The finished spans, in the order they ended. */
|
|
238
|
+
readonly spans: readonly SpanData[];
|
|
239
|
+
/** The log records, in order. */
|
|
240
|
+
readonly logs: readonly LogRecord[];
|
|
241
|
+
/** The metric collections, in order. */
|
|
242
|
+
readonly metrics: readonly (readonly Metric[])[];
|
|
243
|
+
/** Forgets everything kept. */
|
|
244
|
+
clear(): void;
|
|
245
|
+
};
|
|
246
|
+
/** A processor that keeps every signal it receives (FR-012). */
|
|
247
|
+
export declare function memoryProcessor(): MemoryProcessor;
|
|
248
|
+
/** A timer, so that a batch processor's schedule can be driven by a test. */
|
|
249
|
+
export type Timer = {
|
|
250
|
+
readonly set: (fn: () => void, ms: number) => unknown;
|
|
251
|
+
readonly clear: (handle: unknown) => void;
|
|
252
|
+
};
|
|
253
|
+
/** The host's timer; a scheduled export never keeps a process alive (`unref` where the host has it). */
|
|
254
|
+
export declare const systemTimer: Timer;
|
|
255
|
+
/** A processor that exports each signal as it comes, one export at a time (FR-012). */
|
|
256
|
+
export declare function simpleProcessor(exporter: Exporter, options?: {
|
|
257
|
+
readonly exportTimeoutMs?: number;
|
|
258
|
+
}): ExportingProcessor;
|
|
259
|
+
/** The settings of a batch processor, as `OTEL_BSP_*` and `OTEL_BLRP_*` give them (`BatchConfig` of `./otel.ts`), and its timer. */
|
|
260
|
+
export type BatchOptions = {
|
|
261
|
+
readonly maxQueueSize?: number;
|
|
262
|
+
readonly maxExportBatchSize?: number;
|
|
263
|
+
readonly scheduleDelayMs?: number;
|
|
264
|
+
readonly exportTimeoutMs?: number;
|
|
265
|
+
readonly timer?: Timer;
|
|
266
|
+
};
|
|
267
|
+
/**
|
|
268
|
+
* A processor that queues spans and log records (each at most `maxQueueSize`; what does not fit is dropped and counted, never blocking
|
|
269
|
+
* the caller) and exports them in batches of at most `maxExportBatchSize`: as soon as a full batch is waiting, else `scheduleDelayMs` after
|
|
270
|
+
* the first one queued. Metric collections are exported as they come. Exports run one at a time, each within `exportTimeoutMs`, and a
|
|
271
|
+
* batch leaves its queue only when it is sent (FR-012).
|
|
272
|
+
*/
|
|
273
|
+
export declare function batchProcessor(exporter: Exporter, options?: BatchOptions): ExportingProcessor;
|
|
274
|
+
/** A link a new span makes to another span's context. */
|
|
275
|
+
export type LinkInput = {
|
|
276
|
+
readonly traceId: TraceId;
|
|
277
|
+
readonly spanId: SpanId;
|
|
278
|
+
readonly traceFlags: number;
|
|
279
|
+
readonly traceState: TraceState;
|
|
280
|
+
readonly attributes?: Attributes;
|
|
281
|
+
};
|
|
282
|
+
/** How a span starts: its parent (`null` for a new trace; the current context by default) and its links. */
|
|
283
|
+
export type SpanOptions = {
|
|
284
|
+
readonly parent?: SpanContext | null;
|
|
285
|
+
readonly links?: readonly LinkInput[];
|
|
286
|
+
};
|
|
287
|
+
/** How one log record is emitted: a severity of its own instead of its kind's (a finding's, say, where one kind has many severities). */
|
|
288
|
+
export type LogOptions = {
|
|
289
|
+
readonly severity?: SeverityNumber;
|
|
290
|
+
};
|
|
291
|
+
/** A span in progress, as the function it runs sees it. */
|
|
292
|
+
export interface SpanHandle<R extends Declarations, K extends keyof R> {
|
|
293
|
+
/** The span's context. */
|
|
294
|
+
readonly context: SpanContext;
|
|
295
|
+
/** Whether the span is recorded (sampled, and the telemetry not shut down). */
|
|
296
|
+
readonly recording: boolean;
|
|
297
|
+
/** The W3C `traceparent` to give what this span calls (a child process, an HTTP request). */
|
|
298
|
+
readonly traceparent: string;
|
|
299
|
+
/** The W3C `tracestate` to give with it. */
|
|
300
|
+
readonly tracestate: string;
|
|
301
|
+
/** Sets declared attributes of the span. */
|
|
302
|
+
set(attributes: Partial<AttributesOf<R, K>>): void;
|
|
303
|
+
/** Records an event. */
|
|
304
|
+
event(name: string, attributes?: Attributes): void;
|
|
305
|
+
/** Records how far the work has come, as a `progress` event (`progress.done`, `progress.total`). */
|
|
306
|
+
progress(done: number, total?: number): void;
|
|
307
|
+
/** Runs a child span of this one. */
|
|
308
|
+
span<C extends KindOf<R, "span">, T>(kind: C, attributes: AttributesOf<R, C>, fn: (span: SpanHandle<R, C>) => T, options?: SpanOptions): T;
|
|
309
|
+
/** Emits a log record in this span; its severity is the kind's unless `options.severity` gives another. */
|
|
310
|
+
log<L extends KindOf<R, "log">>(kind: L, attributes: AttributesOf<R, L>, body?: AnyValue, options?: LogOptions): void;
|
|
311
|
+
}
|
|
312
|
+
/** The tracer, logger and meter of one resource and scope, typed by a registry. */
|
|
313
|
+
export interface Telemetry<R extends Declarations> {
|
|
314
|
+
/** The registry the kinds come from. */
|
|
315
|
+
readonly registry: Registry<R>;
|
|
316
|
+
/** The resource and scope every signal carries. */
|
|
317
|
+
readonly source: Source;
|
|
318
|
+
/** The current span's context, or the initial parent, if any. */
|
|
319
|
+
active(): SpanContext | undefined;
|
|
320
|
+
/**
|
|
321
|
+
* Runs `fn` in a new span, the child of the current one (FR-010), and returns what it returns. The span ends once: `ok` for an `Ok`
|
|
322
|
+
* result, `error` with the error's description for an `Err`, unset for any other value (a promise is waited for); a function that
|
|
323
|
+
* throws ends it with an `exception` event and `error`, and the exception is thrown on.
|
|
324
|
+
*/
|
|
325
|
+
span<K extends KindOf<R, "span">, T>(kind: K, attributes: AttributesOf<R, K>, fn: (span: SpanHandle<R, K>) => T, options?: SpanOptions): T;
|
|
326
|
+
/** Emits a log record of a kind, in the current span; its `eventName` is the kind, its severity the kind's unless `options.severity` gives another. */
|
|
327
|
+
log<K extends KindOf<R, "log">>(kind: K, attributes: AttributesOf<R, K>, body?: AnyValue, options?: LogOptions): void;
|
|
328
|
+
/** Adds to a counter (a negative or non-finite increment is refused) or an up-down counter. */
|
|
329
|
+
add<K extends KindOf<R, "counter" | "updown">>(kind: K, value: number, attributes: AttributesOf<R, K>): Result<void, string>;
|
|
330
|
+
/** Sets a gauge. */
|
|
331
|
+
set<K extends KindOf<R, "gauge">>(kind: K, value: number, attributes: AttributesOf<R, K>): Result<void, string>;
|
|
332
|
+
/** Records a value in a histogram. */
|
|
333
|
+
record<K extends KindOf<R, "histogram">>(kind: K, value: number, attributes: AttributesOf<R, K>): Result<void, string>;
|
|
334
|
+
/** The metrics as they stand, cumulative since each series began (FR-013), also handed to every processor. */
|
|
335
|
+
collect(): readonly Metric[];
|
|
336
|
+
/** Collects the metrics and flushes every processor, within `timeoutMs`. */
|
|
337
|
+
forceFlush(timeoutMs: number): Promise<FlushResult>;
|
|
338
|
+
/** Ends every open span as `error`, collects the metrics and shuts every processor down, within `timeoutMs`; nothing is recorded after. */
|
|
339
|
+
shutdown(timeoutMs: number): Promise<FlushResult>;
|
|
340
|
+
}
|
|
341
|
+
/** What a telemetry is made from (FR-011): everything that varies is the caller's. */
|
|
342
|
+
export type TelemetryOptions<R extends Declarations> = {
|
|
343
|
+
readonly registry: Registry<R>;
|
|
344
|
+
readonly resource: Resource;
|
|
345
|
+
readonly scope: Scope;
|
|
346
|
+
/** Nanoseconds since the Unix epoch. */
|
|
347
|
+
readonly clock: () => bigint;
|
|
348
|
+
/** `n` random bytes. */
|
|
349
|
+
readonly random: (n: number) => Uint8Array;
|
|
350
|
+
readonly processors: readonly Processor[];
|
|
351
|
+
/** A stack by default; the runtime gives `AsyncLocalStorage`. */
|
|
352
|
+
readonly context?: ContextManager;
|
|
353
|
+
/** The parent of a span started with no current span (from `TRACEPARENT`, say). */
|
|
354
|
+
readonly parent?: SpanContext;
|
|
355
|
+
readonly sampler?: Sampler;
|
|
356
|
+
readonly limits?: Limits;
|
|
357
|
+
/** What a processor threw; processors never break the program. */
|
|
358
|
+
readonly onError?: (error: unknown) => void;
|
|
359
|
+
};
|
|
360
|
+
/** The description of an error for a span's status: a string as it is, an `Error`'s message, an object's `message`, else its JSON. */
|
|
361
|
+
export declare function describeError(error: unknown): string;
|
|
362
|
+
/** Typed attributes as OpenTelemetry attributes, by the schema: an `int` as a `bigint`; an undeclared or absent attribute left out. */
|
|
363
|
+
export declare function toAttributes(schema: AttributeSchema, attributes: object): Attributes;
|
|
364
|
+
/** A canonical key of attributes, the same for equal sets in any order: one metric series for each (FR-013). */
|
|
365
|
+
export declare function attributesKey(attributes: Attributes): string;
|
|
366
|
+
/**
|
|
367
|
+
* The tracer, logger and meter of one resource and scope (FR-010 to FR-013). Every signal is redacted (the kind's secret attributes left
|
|
368
|
+
* out, credentials replaced), limited and handed to each processor in the order it was made. Ids come from `random`, times from `clock`.
|
|
369
|
+
*/
|
|
370
|
+
export declare function createTelemetry<const R extends Declarations>(options: TelemetryOptions<R>): Telemetry<R>;
|
|
371
|
+
export {};
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/** An access key: its id, its secret, and a session token where the key is temporary. */
|
|
2
|
+
export type AwsCredentials = {
|
|
3
|
+
readonly accessKeyId: string;
|
|
4
|
+
readonly secretAccessKey: string;
|
|
5
|
+
readonly sessionToken?: string;
|
|
6
|
+
};
|
|
7
|
+
/** How to sign. */
|
|
8
|
+
export type SigV4Options = {
|
|
9
|
+
readonly credentials: AwsCredentials;
|
|
10
|
+
/** The region of the credential scope (`us-east-1`). */
|
|
11
|
+
readonly region: string;
|
|
12
|
+
/** The service of the credential scope (`iam`, `sts`, `s3`, `ec2`). */
|
|
13
|
+
readonly service: string;
|
|
14
|
+
/** The time of signing, which becomes `x-amz-date` (the kernel reads no clock). */
|
|
15
|
+
readonly date: Date;
|
|
16
|
+
/** Sign `UNSIGNED-PAYLOAD` instead of the body's SHA-256 (S3 allows it). */
|
|
17
|
+
readonly unsignedPayload?: boolean;
|
|
18
|
+
/** Also send the payload's hash as `x-amz-content-sha256` (always for S3, which requires it). */
|
|
19
|
+
readonly contentSha256Header?: boolean;
|
|
20
|
+
};
|
|
21
|
+
/** A request to sign, by its parts. */
|
|
22
|
+
export type SigV4Request = {
|
|
23
|
+
readonly method: string;
|
|
24
|
+
/** The whole URL, as text (its path is signed as written there, before any normalization a URL parser would make). */
|
|
25
|
+
readonly url: string;
|
|
26
|
+
/** The headers to send; each is signed, but for those a transport may change (`user-agent`, `traceparent`, ...). */
|
|
27
|
+
readonly headers: Readonly<Record<string, string>>;
|
|
28
|
+
readonly body?: string | Uint8Array;
|
|
29
|
+
};
|
|
30
|
+
/** A signed request: the headers to send and, for whoever must check them, what was signed. */
|
|
31
|
+
export type Signed = {
|
|
32
|
+
/**
|
|
33
|
+
* The request's headers with `x-amz-date`, `x-amz-security-token` and `x-amz-content-sha256` where they apply, and `authorization`;
|
|
34
|
+
* never `host`, which the transport sets from the URL.
|
|
35
|
+
*/
|
|
36
|
+
readonly headers: Readonly<Record<string, string>>;
|
|
37
|
+
readonly canonicalRequest: string;
|
|
38
|
+
readonly stringToSign: string;
|
|
39
|
+
/** The signature, 64 lower-case hexadecimal digits. */
|
|
40
|
+
readonly signature: string;
|
|
41
|
+
/** The value of the `Authorization` header. */
|
|
42
|
+
readonly authorization: string;
|
|
43
|
+
};
|
|
44
|
+
/** The algorithm's name, as the string to sign and the `Authorization` header begin. */
|
|
45
|
+
export declare const ALGORITHM = "AWS4-HMAC-SHA256";
|
|
46
|
+
/** What is signed in place of a body's hash where the payload is not signed. */
|
|
47
|
+
export declare const UNSIGNED_PAYLOAD = "UNSIGNED-PAYLOAD";
|
|
48
|
+
/** RFC 3986 percent-encoding, as SigV4 wants it: everything but `A-Z a-z 0-9 - _ . ~` encoded, in upper-case hexadecimal. */
|
|
49
|
+
export declare function uriEncode(text: string): string;
|
|
50
|
+
/** `20150830T123600Z`: the time as `x-amz-date` writes it. */
|
|
51
|
+
export declare function amzDate(date: Date): string;
|
|
52
|
+
/**
|
|
53
|
+
* The path as SigV4 signs it. For a service other than S3: `.` and `..` segments resolved and empty segments dropped, each segment
|
|
54
|
+
* decoded and encoded twice (RFC 3986). For S3: the path as given, each segment decoded and encoded once.
|
|
55
|
+
*/
|
|
56
|
+
export declare function canonicalPath(path: string, service: string): string;
|
|
57
|
+
/** The query as SigV4 signs it: each name and value decoded and encoded by RFC 3986, a name without `=` given an empty value, sorted. */
|
|
58
|
+
export declare function canonicalQuery(query: string): string;
|
|
59
|
+
/** The signing key: HMAC-SHA256 of `AWS4` and the secret through the day (`YYYYMMDD`), the region, the service and `aws4_request`. */
|
|
60
|
+
export declare function signingKey(secretAccessKey: string, day: string, region: string, service: string): Promise<Uint8Array>;
|
|
61
|
+
/** A request signed by Signature Version 4 (FR-068): the headers to send, and the canonical request, string to sign and signature. */
|
|
62
|
+
export declare function sign(request: SigV4Request, options: SigV4Options): Promise<Signed>;
|
|
63
|
+
/**
|
|
64
|
+
* A web `Request` signed by Signature Version 4 (FR-068): a new `Request` with the same method, URL and body and the signed headers. Its
|
|
65
|
+
* body is read once (from a clone) to be hashed. The URL is the one the `Request` holds, which a URL parser has already normalized.
|
|
66
|
+
*/
|
|
67
|
+
export declare function signRequest(request: Request, options: SigV4Options): Promise<Request>;
|
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The capture half of test evidence (commons 0008-test-evidence FR-001 to FR-004), kept apart from the reports so that every test process
|
|
3
|
+
* loads only this: the model of a test case and of an installation, a test case as its `test` span and log record with the `test.*`
|
|
4
|
+
* conventions and the `ifc.test.*` attributes (`testCaseSpan`, `testCaseLog`), the mark a test leaves as it starts (`testStartLog`), so
|
|
5
|
+
* that one that never ends is closed as `cancelled` (`closeOrphans`), the installation record as a resource (`installationFromEnv`,
|
|
6
|
+
* which refuses a role that names a person, and `isPersonAttribute`), and the OTLP JSON lines a test process appends to
|
|
7
|
+
* `IFC_TEST_RECORD` (`recordLine`, `decodeLines`). `./test-report.ts` reads a run's record and renders it. A test's steps (commons
|
|
8
|
+
* 0005-typescript-runtime FR-060) are its `steps`, named by its span's `ifc.test.steps`, each a `test step` span whose parent is the
|
|
9
|
+
* test's span or the step it is in (`testStepSpan`).
|
|
10
|
+
*
|
|
11
|
+
* @example
|
|
12
|
+
* ```ts
|
|
13
|
+
* import { installationFromEnv, installationResource, recordLine, testCaseSpan } from "./test-record.js";
|
|
14
|
+
* const { installation } = installationFromEnv({ runtime: "node", runtimeVersion: "26.0.0", os: "linux", arch: "x86_64" }, { CI: "true" });
|
|
15
|
+
* // recordLine(installationResource(installation), { spans: [testCaseSpan(test, context)] }) is one line of IFC_TEST_RECORD
|
|
16
|
+
* ```
|
|
17
|
+
*
|
|
18
|
+
* @module
|
|
19
|
+
*/
|
|
20
|
+
import { type DecodeError, type Result } from "@intellectual-frontiers/core";
|
|
21
|
+
import { type Attributes, type LogRecord, type Resource, type Scope, type SpanData, type SpanId, type TraceId } from "./otel.js";
|
|
22
|
+
import { type LogBatch, type TraceBatch } from "./otlp.js";
|
|
23
|
+
import { type Sha256 } from "./sha256.js";
|
|
24
|
+
/** What became of a test (FR-001). */
|
|
25
|
+
export type Outcome = "pass" | "fail" | "skip" | "todo" | "cancelled";
|
|
26
|
+
/** Every outcome, in the order reports list them. */
|
|
27
|
+
export declare const OUTCOMES: readonly Outcome[];
|
|
28
|
+
/** A test's risk, after the Computer Software Assurance guidance's high process risk: `high` or `not-high` (FR-001). */
|
|
29
|
+
export type Risk = "high" | "not-high";
|
|
30
|
+
/** Whether a text is an outcome. */
|
|
31
|
+
export declare function isOutcome(text: string): text is Outcome;
|
|
32
|
+
/** Whether a text is a risk. */
|
|
33
|
+
export declare function isRisk(text: string): text is Risk;
|
|
34
|
+
/** What became of a step (0005-typescript-runtime FR-060): it passed, it failed, or its runner did not run it. */
|
|
35
|
+
export type StepOutcome = "pass" | "fail" | "skip";
|
|
36
|
+
/** Whether a text is a step's outcome. */
|
|
37
|
+
export declare function isStepOutcome(text: string): text is StepOutcome;
|
|
38
|
+
/** One step of a test as it ran (0005-typescript-runtime FR-060): its name, times, outcome, a failure's message, and its own steps. */
|
|
39
|
+
export type TestStep = {
|
|
40
|
+
readonly name: string;
|
|
41
|
+
readonly start: bigint;
|
|
42
|
+
readonly end: bigint;
|
|
43
|
+
readonly outcome: StepOutcome;
|
|
44
|
+
readonly message?: string;
|
|
45
|
+
readonly steps?: readonly TestStep[];
|
|
46
|
+
};
|
|
47
|
+
/** One test as it ran once (FR-001): times in nanoseconds since the Unix epoch; text already redacted and cut. */
|
|
48
|
+
export type TestCase = {
|
|
49
|
+
/** The SHA-256 of its file, a NUL and its name. */
|
|
50
|
+
readonly id: string;
|
|
51
|
+
/** Its file, relative to the working folder, with `/`. */
|
|
52
|
+
readonly file: string;
|
|
53
|
+
readonly name: string;
|
|
54
|
+
readonly requirements: readonly string[];
|
|
55
|
+
readonly risk: Risk;
|
|
56
|
+
/** The quality characteristic it proves, in the words of ISO/IEC 25010 (`ifc.test.characteristic`, 0021-ifqs FR-012); absent where it names none. */
|
|
57
|
+
readonly characteristic?: string;
|
|
58
|
+
readonly start: bigint;
|
|
59
|
+
readonly end: bigint;
|
|
60
|
+
readonly outcome: Outcome;
|
|
61
|
+
/** A skip's or a todo's reason, or why it was cancelled. */
|
|
62
|
+
readonly reason?: string;
|
|
63
|
+
readonly message?: string;
|
|
64
|
+
readonly expected?: string;
|
|
65
|
+
readonly actual?: string;
|
|
66
|
+
/** From 1. */
|
|
67
|
+
readonly attempt: number;
|
|
68
|
+
/** Its steps, in the order they ended; absent where it has none (0005-typescript-runtime FR-060). */
|
|
69
|
+
readonly steps?: readonly TestStep[];
|
|
70
|
+
};
|
|
71
|
+
/** The installation record: the resource of a test process or of the run (FR-003). */
|
|
72
|
+
export type Installation = {
|
|
73
|
+
readonly runtime: string;
|
|
74
|
+
readonly runtimeVersion: string;
|
|
75
|
+
readonly os: string;
|
|
76
|
+
readonly arch: string;
|
|
77
|
+
readonly revision?: string;
|
|
78
|
+
readonly lockfileSha256?: string;
|
|
79
|
+
readonly pinsSha256?: string;
|
|
80
|
+
readonly role: string;
|
|
81
|
+
};
|
|
82
|
+
/** A requirement declared proven by review rather than by a test, with the reason. */
|
|
83
|
+
export type Review = {
|
|
84
|
+
readonly requirement: string;
|
|
85
|
+
readonly reason: string;
|
|
86
|
+
};
|
|
87
|
+
/** What one runner did: the runtime, its exit status, or that it is not installed. */
|
|
88
|
+
export type RunnerOutcome = {
|
|
89
|
+
readonly kind: "exited";
|
|
90
|
+
readonly runtime: string;
|
|
91
|
+
readonly code: number;
|
|
92
|
+
} | {
|
|
93
|
+
readonly kind: "missing";
|
|
94
|
+
readonly runtime: string;
|
|
95
|
+
};
|
|
96
|
+
/** The instrumentation scope of test records. */
|
|
97
|
+
export declare const TEST_SCOPE: Scope;
|
|
98
|
+
/** The name of a test's span. */
|
|
99
|
+
export declare const TEST_SPAN = "test";
|
|
100
|
+
/** The name of a step's span, a child of its test's span or of the step it is in (0005-typescript-runtime FR-060). */
|
|
101
|
+
export declare const STEP_SPAN = "test step";
|
|
102
|
+
/** The name of a run's span. */
|
|
103
|
+
export declare const RUN_SPAN = "test run";
|
|
104
|
+
/** The event names of the log records of a test record. */
|
|
105
|
+
export declare const EVENTS: {
|
|
106
|
+
readonly case: "ifc.test.case";
|
|
107
|
+
readonly start: "ifc.test.start";
|
|
108
|
+
readonly review: "ifc.test.review";
|
|
109
|
+
readonly runner: "ifc.test.runner";
|
|
110
|
+
readonly warning: "ifc.test.warning";
|
|
111
|
+
};
|
|
112
|
+
/** The most characters a message, an expected or an actual value keeps (FR-001). */
|
|
113
|
+
export declare const TEXT_LIMIT = 4096;
|
|
114
|
+
/** A text cut to `TEXT_LIMIT` characters (without splitting a surrogate pair). */
|
|
115
|
+
export declare function cut(text: string): string;
|
|
116
|
+
/** A test's id: the SHA-256 of its file, a NUL and its name (FR-001). */
|
|
117
|
+
export declare function testId(file: string, name: string): Promise<Sha256>;
|
|
118
|
+
/** A file path as a record names it: `\` as `/`, without a leading `./`. */
|
|
119
|
+
export declare function recordPath(path: string): string;
|
|
120
|
+
/** Whether a resource attribute names a person or a machine of one, and is refused (FR-003): `user.*`, `enduser.*`, `host.name`. */
|
|
121
|
+
export declare function isPersonAttribute(key: string): boolean;
|
|
122
|
+
/** A machine's architecture as OpenTelemetry's `host.arch` names it (`amd64`, `arm64`, ...). */
|
|
123
|
+
export declare function hostArch(arch: string): string;
|
|
124
|
+
/**
|
|
125
|
+
* The installation record of a process, from what the runtime says of itself and the environment given as a record (the kernel reads no
|
|
126
|
+
* environment): `IFC_TEST_REVISION` or `GITHUB_SHA`, `IFC_TEST_LOCKFILE_SHA256`, `IFC_TEST_PINS_SHA256`, and `IFC_TEST_ROLE` (`ci` where
|
|
127
|
+
* `CI` is set, else `developer`). A role that is not a role (an e-mail address, a name with capitals or spaces) is refused with a
|
|
128
|
+
* warning and the default used, and so is a digest that is not a SHA-256.
|
|
129
|
+
*/
|
|
130
|
+
export declare function installationFromEnv(self: {
|
|
131
|
+
readonly runtime: string;
|
|
132
|
+
readonly runtimeVersion: string;
|
|
133
|
+
readonly os: string;
|
|
134
|
+
readonly arch: string;
|
|
135
|
+
}, env: Readonly<Record<string, string | undefined>>): {
|
|
136
|
+
readonly installation: Installation;
|
|
137
|
+
readonly warnings: readonly string[];
|
|
138
|
+
};
|
|
139
|
+
/** The resource of an installation record (FR-003). */
|
|
140
|
+
export declare function installationResource(i: Installation): Resource;
|
|
141
|
+
/** An attribute's value where it is a string. */
|
|
142
|
+
export declare function attributeText(a: Attributes, key: string): string | undefined;
|
|
143
|
+
/** An attribute's value where it is an array of strings, else none. */
|
|
144
|
+
export declare function attributeTexts(a: Attributes, key: string): readonly string[];
|
|
145
|
+
/** An attribute's value where it is an integer. */
|
|
146
|
+
export declare function attributeInteger(a: Attributes, key: string): number | undefined;
|
|
147
|
+
/** The installation record a resource holds; unknown fields are `unknown`. */
|
|
148
|
+
export declare function installationOf(r: Resource): Installation;
|
|
149
|
+
/** Where a test's signals belong: the trace, the test's own span id, and the run's span as its parent where there is one. */
|
|
150
|
+
export type TestContext = {
|
|
151
|
+
readonly traceId: TraceId;
|
|
152
|
+
readonly spanId: SpanId;
|
|
153
|
+
readonly parentSpanId?: SpanId;
|
|
154
|
+
};
|
|
155
|
+
/** The steps of a test, each by its path (a step within another is `outer > inner`), in their order with each step's own steps first. */
|
|
156
|
+
export declare function stepPaths(steps: readonly TestStep[], within?: readonly string[]): string[];
|
|
157
|
+
/**
|
|
158
|
+
* A step as its `test step` span (0005-typescript-runtime FR-060): a child of `ctx.parentSpanId` (its test's span or the step it is in),
|
|
159
|
+
* with its test's id and file, its name, outcome and a failure's message, and an error status where it failed.
|
|
160
|
+
*/
|
|
161
|
+
export declare function testStepSpan(step: TestStep, test: Pick<TestCase, "id" | "file" | "name">, ctx: TestContext): SpanData;
|
|
162
|
+
/** A test as its `test` span (FR-002): the conventions, the `ifc.test.*` attributes, and an error status where it failed or was cancelled. */
|
|
163
|
+
export declare function testCaseSpan(c: TestCase, ctx: TestContext): SpanData;
|
|
164
|
+
/** A test as its log record (FR-002): the same attributes, the name as its body, at ERROR where it failed or was cancelled. */
|
|
165
|
+
export declare function testCaseLog(c: TestCase, ctx: TestContext): LogRecord;
|
|
166
|
+
/** The mark a test leaves as it starts (FR-004): its span id, so that a test whose span never comes is closed as cancelled. */
|
|
167
|
+
export declare function testStartLog(c: Omit<TestCase, "end" | "outcome">, ctx: TestContext): LogRecord;
|
|
168
|
+
/** A review declared in a test file or a list (`ifc.test.review`). */
|
|
169
|
+
export declare function reviewLog(r: Review, time: bigint, traceId?: TraceId): LogRecord;
|
|
170
|
+
/** A warning of a test process or a run (`ifc.test.warning`), such as a role refused. */
|
|
171
|
+
export declare function warningLog(message: string, time: bigint): LogRecord;
|
|
172
|
+
/** What one runner did (`ifc.test.runner`). */
|
|
173
|
+
export declare function runnerLog(r: RunnerOutcome, time: bigint): LogRecord;
|
|
174
|
+
/** One line of `IFC_TEST_RECORD`: an OTLP JSON traces or logs export request of one resource, without a line feed (FR-004). */
|
|
175
|
+
export declare function recordLine(resource: Resource, signal: {
|
|
176
|
+
readonly spans: readonly SpanData[];
|
|
177
|
+
} | {
|
|
178
|
+
readonly records: readonly LogRecord[];
|
|
179
|
+
}): string;
|
|
180
|
+
/** Why the lines of a test record or a run's record could not be read. */
|
|
181
|
+
export type RecordError = {
|
|
182
|
+
readonly kind: "json";
|
|
183
|
+
readonly line: number;
|
|
184
|
+
readonly reason: string;
|
|
185
|
+
} | {
|
|
186
|
+
readonly kind: "otlp";
|
|
187
|
+
readonly line: number;
|
|
188
|
+
readonly error: DecodeError;
|
|
189
|
+
} | {
|
|
190
|
+
readonly kind: "person";
|
|
191
|
+
readonly key: string;
|
|
192
|
+
} | {
|
|
193
|
+
readonly kind: "test";
|
|
194
|
+
readonly spanId: string;
|
|
195
|
+
readonly reason: string;
|
|
196
|
+
} | {
|
|
197
|
+
readonly kind: "no-run";
|
|
198
|
+
readonly reason: string;
|
|
199
|
+
};
|
|
200
|
+
/** A record error as one sentence. */
|
|
201
|
+
export declare function formatRecordError(e: RecordError): string;
|
|
202
|
+
/** The signals of one or more export requests. */
|
|
203
|
+
export type Signals = {
|
|
204
|
+
readonly traces: readonly TraceBatch[];
|
|
205
|
+
readonly logs: readonly LogBatch[];
|
|
206
|
+
};
|
|
207
|
+
/** The traces and logs of one OTLP JSON document (an export request, or a run's record holding both), as line `line`. */
|
|
208
|
+
export declare function decodeRecordDocument(value: unknown, line: number): Result<Signals, RecordError>;
|
|
209
|
+
/**
|
|
210
|
+
* The signals of `IFC_TEST_RECORD`'s lines, each an OTLP JSON export request (FR-004). A last line cut short (a process killed while it
|
|
211
|
+
* wrote) is left out with a warning; any other line that is not one is an error.
|
|
212
|
+
*/
|
|
213
|
+
export declare function decodeLines(input: string): Result<Signals & {
|
|
214
|
+
readonly warnings: readonly string[];
|
|
215
|
+
}, RecordError>;
|
|
216
|
+
/** Batches of one resource and scope joined into one, in the order they first came. */
|
|
217
|
+
export declare function mergeBatches(signals: Signals): Signals;
|
|
218
|
+
/**
|
|
219
|
+
* The traces with a `cancelled` test span for each test that started and has no span (FR-004): its process died, or exited, before the
|
|
220
|
+
* test ended. Its end is `at`, the time the run saw its process end.
|
|
221
|
+
*/
|
|
222
|
+
export declare function closeOrphans(signals: Signals, at: bigint): Signals;
|