@intellectual-frontiers/telemetry 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +8 -2
- package/dist/host/console.d.ts +80 -0
- package/dist/host/console.js +188 -0
- package/dist/host/mod.d.ts +15 -0
- package/dist/host/mod.js +16 -0
- package/dist/host/otel.d.ts +280 -0
- package/dist/host/otel.js +848 -0
- package/dist/mod.d.ts +17 -0
- package/dist/mod.js +18 -0
- package/dist/otel.d.ts +365 -0
- package/dist/otel.js +686 -0
- package/dist/otlp.d.ts +83 -0
- package/dist/otlp.js +634 -0
- package/dist/render.d.ts +111 -0
- package/dist/render.js +368 -0
- package/dist/signals.d.ts +371 -0
- package/dist/signals.js +800 -0
- package/package.json +76 -4
- package/src/host/console.ts +253 -0
- package/src/host/mod.ts +16 -0
- package/src/host/otel.ts +1068 -0
- package/src/mod.ts +18 -0
- package/src/otel.ts +919 -0
- package/src/otlp.ts +721 -0
- package/src/render.ts +489 -0
- package/src/signals.ts +1175 -0
package/dist/mod.d.ts
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Telemetry, OpenTelemetry-native signals as one typed library (its specification 0001-telemetry): the data model, W3C Trace Context and the configuration from the environment (as `otel`), OTLP/HTTP JSON
|
|
3
|
+
* (as `otlp`), typed signals declared once with spans, log events and metrics (as `signals`), and the pure reducer that renders them for a terminal (as `render`). This entry is pure: it names no host global,
|
|
4
|
+
* reads no environment and writes nothing. The code that exports, journals and shows signals is `@intellectual-frontiers/telemetry/host`.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { signals } from "@intellectual-frontiers/telemetry";
|
|
9
|
+
* const registry = signals.defineSignals({ "build": { kind: "span", attributes: {} } });
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
export * as otel from "./otel.js";
|
|
15
|
+
export * as otlp from "./otlp.js";
|
|
16
|
+
export * as render from "./render.js";
|
|
17
|
+
export * as signals from "./signals.js";
|
package/dist/mod.js
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
// Spec: 0001-telemetry FR-026
|
|
2
|
+
/**
|
|
3
|
+
* Telemetry, OpenTelemetry-native signals as one typed library (its specification 0001-telemetry): the data model, W3C Trace Context and the configuration from the environment (as `otel`), OTLP/HTTP JSON
|
|
4
|
+
* (as `otlp`), typed signals declared once with spans, log events and metrics (as `signals`), and the pure reducer that renders them for a terminal (as `render`). This entry is pure: it names no host global,
|
|
5
|
+
* reads no environment and writes nothing. The code that exports, journals and shows signals is `@intellectual-frontiers/telemetry/host`.
|
|
6
|
+
*
|
|
7
|
+
* @example
|
|
8
|
+
* ```ts
|
|
9
|
+
* import { signals } from "@intellectual-frontiers/telemetry";
|
|
10
|
+
* const registry = signals.defineSignals({ "build": { kind: "span", attributes: {} } });
|
|
11
|
+
* ```
|
|
12
|
+
*
|
|
13
|
+
* @module
|
|
14
|
+
*/
|
|
15
|
+
export * as otel from "./otel.js";
|
|
16
|
+
export * as otlp from "./otlp.js";
|
|
17
|
+
export * as render from "./render.js";
|
|
18
|
+
export * as signals from "./signals.js";
|
package/dist/otel.d.ts
ADDED
|
@@ -0,0 +1,365 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The OpenTelemetry data model, written from the OpenTelemetry specification itself (commons 0001-telemetry FR-001 to FR-008): attribute
|
|
3
|
+
* values and log bodies, trace and span ids as brands made only from bytes the caller gives (the kernel has no randomness of its own), W3C
|
|
4
|
+
* Trace Context Level 2 `traceparent` and `tracestate`, resources, scopes, finished spans, log records and metric points, the
|
|
5
|
+
* configuration read from the `OTEL_*` environment variables (given as a record: the kernel reads no environment), redaction of what must
|
|
6
|
+
* never leave a process, the attribute, event and link limits, and the samplers OpenTelemetry names.
|
|
7
|
+
*
|
|
8
|
+
* @example
|
|
9
|
+
* ```ts
|
|
10
|
+
* import { formatTraceparent, parseTraceparent, redactUrl, resolveConfig } from "./otel.js";
|
|
11
|
+
* const parent = parseTraceparent("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01");
|
|
12
|
+
* if (parent.kind === "ok") formatTraceparent(parent.value); // the same header back
|
|
13
|
+
* redactUrl("https://user:pw@host/x?token=abc&page=2"); // "https://REDACTED:REDACTED@host/x?token=REDACTED&page=2"
|
|
14
|
+
* resolveConfig({ OTEL_SERVICE_NAME: "build" }).config.resource; // { "service.name": "build" }
|
|
15
|
+
* ```
|
|
16
|
+
*
|
|
17
|
+
* @module
|
|
18
|
+
*/
|
|
19
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
20
|
+
import type { Brand } from "@intellectual-frontiers/core";
|
|
21
|
+
/**
|
|
22
|
+
* An attribute's value: a string, a boolean, an integer (`bigint`, OTLP's int64), a double (`number`), bytes, or a homogeneous array of
|
|
23
|
+
* one of the primitive types. Nothing else is representable (FR-001).
|
|
24
|
+
*/
|
|
25
|
+
export type AttributeValue = string | boolean | bigint | number | Uint8Array | readonly string[] | readonly boolean[] | readonly bigint[] | readonly number[];
|
|
26
|
+
/** A set of attributes: names to values. */
|
|
27
|
+
export type Attributes = Readonly<Record<string, AttributeValue>>;
|
|
28
|
+
/** A log body, as OTLP's `AnyValue`: what an attribute may be, and also a map or an array of mixed values (FR-001). */
|
|
29
|
+
export type AnyValue = AttributeValue | readonly AnyValue[] | AnyMap;
|
|
30
|
+
/** A map of `AnyValue`s, as OTLP's `KeyValueList`. */
|
|
31
|
+
export type AnyMap = {
|
|
32
|
+
readonly [key: string]: AnyValue;
|
|
33
|
+
};
|
|
34
|
+
/** A trace id: 32 lower-case hexadecimal digits, not all zeros (FR-002). */
|
|
35
|
+
export type TraceId = Brand<string, "TraceId">;
|
|
36
|
+
/** A span id: 16 lower-case hexadecimal digits, not all zeros (FR-002). */
|
|
37
|
+
export type SpanId = Brand<string, "SpanId">;
|
|
38
|
+
/** A trace id from 16 bytes a caller gives (`traceIdFrom(random(16))`); other lengths and all zeros are refused (FR-002). */
|
|
39
|
+
export declare function traceIdFrom(bytes: Uint8Array): Result<TraceId, string>;
|
|
40
|
+
/** A span id from 8 bytes a caller gives (`spanIdFrom(random(8))`); other lengths and all zeros are refused (FR-002). */
|
|
41
|
+
export declare function spanIdFrom(bytes: Uint8Array): Result<SpanId, string>;
|
|
42
|
+
/** A trace id from its text: 32 lower-case hexadecimal digits, not all zeros. */
|
|
43
|
+
export declare function parseTraceId(text: string): Result<TraceId, string>;
|
|
44
|
+
/** A span id from its text: 16 lower-case hexadecimal digits, not all zeros. */
|
|
45
|
+
export declare function parseSpanId(text: string): Result<SpanId, string>;
|
|
46
|
+
/** One `tracestate` member. */
|
|
47
|
+
export type TraceStateMember = {
|
|
48
|
+
readonly key: string;
|
|
49
|
+
readonly value: string;
|
|
50
|
+
};
|
|
51
|
+
/** A `tracestate`: its members, newest first, at most 32, each key once. */
|
|
52
|
+
export type TraceState = readonly TraceStateMember[];
|
|
53
|
+
/** The `sampled` trace flag. */
|
|
54
|
+
export declare const SAMPLED = 1;
|
|
55
|
+
/** The `random` trace flag of Level 2: the trace id's right-most 7 bytes are random. */
|
|
56
|
+
export declare const RANDOM = 2;
|
|
57
|
+
/** The most members a `tracestate` keeps. */
|
|
58
|
+
export declare const TRACESTATE_MAX_MEMBERS = 32;
|
|
59
|
+
/** What propagates: the ids, the flags, the trace state, and whether it came from another process. */
|
|
60
|
+
export type SpanContext = {
|
|
61
|
+
readonly traceId: TraceId;
|
|
62
|
+
readonly spanId: SpanId;
|
|
63
|
+
readonly traceFlags: number;
|
|
64
|
+
readonly traceState: TraceState;
|
|
65
|
+
readonly isRemote: boolean;
|
|
66
|
+
};
|
|
67
|
+
/** Whether a context's `sampled` flag is set. */
|
|
68
|
+
export declare function isSampled(context: {
|
|
69
|
+
readonly traceFlags: number;
|
|
70
|
+
}): boolean;
|
|
71
|
+
/**
|
|
72
|
+
* A `traceparent` header read (FR-003): version `00` exactly as written (55 characters, lower-case hexadecimal, ids not all zeros),
|
|
73
|
+
* version `ff` refused, a later version read by its first four fields. The context is remote and its trace state empty; the flags this
|
|
74
|
+
* version does not define are dropped.
|
|
75
|
+
*/
|
|
76
|
+
export declare function parseTraceparent(header: string): Result<SpanContext, string>;
|
|
77
|
+
/** A `traceparent` header (version `00`) for a context. */
|
|
78
|
+
export declare function formatTraceparent(context: {
|
|
79
|
+
readonly traceId: TraceId;
|
|
80
|
+
readonly spanId: SpanId;
|
|
81
|
+
readonly traceFlags: number;
|
|
82
|
+
}): string;
|
|
83
|
+
/** Whether a key is a `tracestate` key of the grammar. */
|
|
84
|
+
export declare function isTraceStateKey(key: string): boolean;
|
|
85
|
+
/** Whether a value is a `tracestate` value of the grammar. */
|
|
86
|
+
export declare function isTraceStateValue(value: string): boolean;
|
|
87
|
+
/**
|
|
88
|
+
* A `tracestate` header read (FR-003): members split on commas with optional white space, a member that breaks the grammar or repeats a
|
|
89
|
+
* key dropped (never the header), at most 32 members kept. Several header fields are read joined with commas.
|
|
90
|
+
*/
|
|
91
|
+
export declare function parseTracestate(header: string): TraceState;
|
|
92
|
+
/** A `tracestate` header: the members newest first, as they are held. */
|
|
93
|
+
export declare function formatTracestate(state: TraceState): string;
|
|
94
|
+
/** The value of a key in a trace state. */
|
|
95
|
+
export declare function traceStateGet(state: TraceState, key: string): string | undefined;
|
|
96
|
+
/** A trace state with a key set: the member moved to the front (newest), the oldest dropped beyond 32; a key or value of no grammar refused. */
|
|
97
|
+
export declare function traceStateSet(state: TraceState, key: string, value: string): Result<TraceState, string>;
|
|
98
|
+
/** A trace state without a key. */
|
|
99
|
+
export declare function traceStateDelete(state: TraceState, key: string): TraceState;
|
|
100
|
+
/**
|
|
101
|
+
* The context carried by a `traceparent` and a `tracestate` (an HTTP request's headers, or the `TRACEPARENT` and `TRACESTATE` of the
|
|
102
|
+
* environment): undefined when there is no valid `traceparent`, whose `tracestate` is then ignored too.
|
|
103
|
+
*/
|
|
104
|
+
export declare function extractContext(traceparent: string | undefined, tracestate: string | undefined): SpanContext | undefined;
|
|
105
|
+
/** The entity that makes the signals: `service.name` and the others. */
|
|
106
|
+
export type Resource = {
|
|
107
|
+
readonly attributes: Attributes;
|
|
108
|
+
};
|
|
109
|
+
/** The instrumentation scope: the library or harness that makes the signals. */
|
|
110
|
+
export type Scope = {
|
|
111
|
+
readonly name: string;
|
|
112
|
+
readonly version?: string;
|
|
113
|
+
readonly attributes?: Attributes;
|
|
114
|
+
};
|
|
115
|
+
/** A span's kind. */
|
|
116
|
+
export type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";
|
|
117
|
+
/** A span's status: unset, ok, or an error with its description. */
|
|
118
|
+
export type SpanStatus = {
|
|
119
|
+
readonly kind: "unset";
|
|
120
|
+
} | {
|
|
121
|
+
readonly kind: "ok";
|
|
122
|
+
} | {
|
|
123
|
+
readonly kind: "error";
|
|
124
|
+
readonly message: string;
|
|
125
|
+
};
|
|
126
|
+
/** Something that happened at a time during a span. */
|
|
127
|
+
export type SpanEvent = {
|
|
128
|
+
readonly name: string;
|
|
129
|
+
readonly time: bigint;
|
|
130
|
+
readonly attributes: Attributes;
|
|
131
|
+
readonly droppedAttributesCount: number;
|
|
132
|
+
};
|
|
133
|
+
/** A span's link to another span's context. */
|
|
134
|
+
export type SpanLink = {
|
|
135
|
+
readonly traceId: TraceId;
|
|
136
|
+
readonly spanId: SpanId;
|
|
137
|
+
readonly traceState: TraceState;
|
|
138
|
+
readonly traceFlags: number;
|
|
139
|
+
readonly attributes: Attributes;
|
|
140
|
+
readonly droppedAttributesCount: number;
|
|
141
|
+
};
|
|
142
|
+
/** A finished span. Times are nanoseconds since the Unix epoch. */
|
|
143
|
+
export type SpanData = {
|
|
144
|
+
readonly name: string;
|
|
145
|
+
readonly context: SpanContext;
|
|
146
|
+
readonly parentSpanId?: SpanId;
|
|
147
|
+
readonly kind: SpanKind;
|
|
148
|
+
readonly startTime: bigint;
|
|
149
|
+
readonly endTime: bigint;
|
|
150
|
+
readonly attributes: Attributes;
|
|
151
|
+
readonly events: readonly SpanEvent[];
|
|
152
|
+
readonly links: readonly SpanLink[];
|
|
153
|
+
readonly status: SpanStatus;
|
|
154
|
+
readonly droppedAttributesCount: number;
|
|
155
|
+
readonly droppedEventsCount: number;
|
|
156
|
+
readonly droppedLinksCount: number;
|
|
157
|
+
};
|
|
158
|
+
/** A severity number of the log data model, 1 (TRACE) to 24 (FATAL4). */
|
|
159
|
+
export type SeverityNumber = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24;
|
|
160
|
+
/** The first severity number of each range of the log data model. */
|
|
161
|
+
export declare const SEVERITY: {
|
|
162
|
+
readonly TRACE: 1;
|
|
163
|
+
readonly DEBUG: 5;
|
|
164
|
+
readonly INFO: 9;
|
|
165
|
+
readonly WARN: 13;
|
|
166
|
+
readonly ERROR: 17;
|
|
167
|
+
readonly FATAL: 21;
|
|
168
|
+
};
|
|
169
|
+
/** Whether a number is a severity number (an integer from 1 to 24). */
|
|
170
|
+
export declare function isSeverityNumber(n: number): n is SeverityNumber;
|
|
171
|
+
/** The short name the log data model gives a severity number: `INFO`, `INFO2`, ... `FATAL4`. */
|
|
172
|
+
export declare function severityText(n: SeverityNumber): string;
|
|
173
|
+
/** A log record. Times are nanoseconds since the Unix epoch. */
|
|
174
|
+
export type LogRecord = {
|
|
175
|
+
readonly time: bigint;
|
|
176
|
+
readonly observedTime: bigint;
|
|
177
|
+
readonly severityNumber: SeverityNumber;
|
|
178
|
+
readonly severityText: string;
|
|
179
|
+
readonly body?: AnyValue;
|
|
180
|
+
readonly attributes: Attributes;
|
|
181
|
+
readonly droppedAttributesCount: number;
|
|
182
|
+
readonly eventName?: string;
|
|
183
|
+
readonly traceId?: TraceId;
|
|
184
|
+
readonly spanId?: SpanId;
|
|
185
|
+
readonly traceFlags?: number;
|
|
186
|
+
};
|
|
187
|
+
/** How a sum or a histogram accumulates: since the last collection, or since the series began. */
|
|
188
|
+
export type Temporality = "delta" | "cumulative";
|
|
189
|
+
/** A point of a sum or a gauge: an integer (`bigint`) or a double. */
|
|
190
|
+
export type NumberPoint = {
|
|
191
|
+
readonly attributes: Attributes;
|
|
192
|
+
readonly startTime: bigint;
|
|
193
|
+
readonly time: bigint;
|
|
194
|
+
readonly value: bigint | number;
|
|
195
|
+
};
|
|
196
|
+
/** A point of an explicit-bucket histogram: `bucketCounts` has one more element than `bounds`, bucket `i` holding (bounds[i-1], bounds[i]]. */
|
|
197
|
+
export type HistogramPoint = {
|
|
198
|
+
readonly attributes: Attributes;
|
|
199
|
+
readonly startTime: bigint;
|
|
200
|
+
readonly time: bigint;
|
|
201
|
+
readonly count: number;
|
|
202
|
+
readonly sum?: number;
|
|
203
|
+
readonly min?: number;
|
|
204
|
+
readonly max?: number;
|
|
205
|
+
readonly bounds: readonly number[];
|
|
206
|
+
readonly bucketCounts: readonly number[];
|
|
207
|
+
};
|
|
208
|
+
/** The data of a metric: a sum (monotonic or not), a gauge, or a histogram. */
|
|
209
|
+
export type MetricData = {
|
|
210
|
+
readonly kind: "sum";
|
|
211
|
+
readonly temporality: Temporality;
|
|
212
|
+
readonly monotonic: boolean;
|
|
213
|
+
readonly points: readonly NumberPoint[];
|
|
214
|
+
} | {
|
|
215
|
+
readonly kind: "gauge";
|
|
216
|
+
readonly points: readonly NumberPoint[];
|
|
217
|
+
} | {
|
|
218
|
+
readonly kind: "histogram";
|
|
219
|
+
readonly temporality: Temporality;
|
|
220
|
+
readonly points: readonly HistogramPoint[];
|
|
221
|
+
};
|
|
222
|
+
/** A metric: its name, description, unit and data. */
|
|
223
|
+
export type Metric = {
|
|
224
|
+
readonly name: string;
|
|
225
|
+
readonly description: string;
|
|
226
|
+
readonly unit: string;
|
|
227
|
+
readonly data: MetricData;
|
|
228
|
+
};
|
|
229
|
+
/** OpenTelemetry's default explicit bucket bounds for a histogram (FR-013). */
|
|
230
|
+
export declare const DEFAULT_HISTOGRAM_BOUNDS: readonly number[];
|
|
231
|
+
/** The limits of FR-005, applied by FR-007. `attributeValueLength` is `Infinity` where there is none. */
|
|
232
|
+
export type Limits = {
|
|
233
|
+
readonly attributeValueLength: number;
|
|
234
|
+
readonly attributeCount: number;
|
|
235
|
+
readonly eventCount: number;
|
|
236
|
+
readonly linkCount: number;
|
|
237
|
+
};
|
|
238
|
+
/** OpenTelemetry's default limits: no value length limit, 128 attributes, events and links. */
|
|
239
|
+
export declare const DEFAULT_LIMITS: Limits;
|
|
240
|
+
/** A value cut to the value length limit: a string, or each string of an array of strings; other values unchanged. */
|
|
241
|
+
export declare function truncateValue(value: AttributeValue, length: number): AttributeValue;
|
|
242
|
+
/**
|
|
243
|
+
* Attributes added to others under the limits (FR-007): a value cut to the length limit, an existing key replaced, a new key beyond the
|
|
244
|
+
* count dropped and counted.
|
|
245
|
+
*/
|
|
246
|
+
export declare function mergeAttributes(current: Attributes, added: Attributes, limits: Pick<Limits, "attributeValueLength" | "attributeCount">): {
|
|
247
|
+
readonly attributes: Attributes;
|
|
248
|
+
readonly dropped: number;
|
|
249
|
+
};
|
|
250
|
+
/** Attributes under the limits: what `mergeAttributes` gives from none. */
|
|
251
|
+
export declare function limitAttributes(attributes: Attributes, limits: Pick<Limits, "attributeValueLength" | "attributeCount">): {
|
|
252
|
+
readonly attributes: Attributes;
|
|
253
|
+
readonly dropped: number;
|
|
254
|
+
};
|
|
255
|
+
/** A sampler for a span with no parent. */
|
|
256
|
+
export type RootSampler = {
|
|
257
|
+
readonly kind: "always_on";
|
|
258
|
+
} | {
|
|
259
|
+
readonly kind: "always_off";
|
|
260
|
+
} | {
|
|
261
|
+
readonly kind: "traceidratio";
|
|
262
|
+
readonly ratio: number;
|
|
263
|
+
};
|
|
264
|
+
/** A sampler: a root sampler, or `parentbased` (the parent's `sampled` flag where there is a parent, `root` where there is none). */
|
|
265
|
+
export type Sampler = RootSampler | {
|
|
266
|
+
readonly kind: "parentbased";
|
|
267
|
+
readonly root: RootSampler;
|
|
268
|
+
};
|
|
269
|
+
/** OpenTelemetry's default sampler: `parentbased_always_on`. */
|
|
270
|
+
export declare const DEFAULT_SAMPLER: Sampler;
|
|
271
|
+
/**
|
|
272
|
+
* The rejection threshold of `TraceIdRatioBased` for a ratio: a trace is sampled where its trace id's right-most 56 bits, read as an
|
|
273
|
+
* unsigned integer, are at least the threshold (`(1 - ratio) * 2^56`). Every process of a trace decides alike from the id alone.
|
|
274
|
+
*/
|
|
275
|
+
export declare function ratioThreshold(ratio: number): bigint;
|
|
276
|
+
/** Whether a sampler samples a new span of a trace, given its parent (FR-008). */
|
|
277
|
+
export declare function shouldSample(sampler: Sampler, traceId: TraceId, parent: SpanContext | undefined): boolean;
|
|
278
|
+
/** What a redacted secret is written as. */
|
|
279
|
+
export declare const REDACTED = "REDACTED";
|
|
280
|
+
/** Whether a query parameter's or a field's name says it holds a credential (`token`, `key`, `secret`, `password`, `signature`, `code`, ...). */
|
|
281
|
+
export declare function isCredentialName(name: string): boolean;
|
|
282
|
+
/**
|
|
283
|
+
* A URL with its secrets replaced (FR-006): the user and password of its authority, and the value of each query parameter whose name says
|
|
284
|
+
* it is a credential, become `REDACTED`. The rest of the text is kept as written.
|
|
285
|
+
*/
|
|
286
|
+
export declare function redactUrl(url: string): string;
|
|
287
|
+
/**
|
|
288
|
+
* Whether a field's name in text says its value is a secret (FR-006): it ends in `token`, `secret`, `password`, `passwd`, `passphrase`,
|
|
289
|
+
* `apikey`, `accesskey`, `secretkey`, `privatekey`, `credential` or `signature`, with case, `-`, `_` and `.` ignored (`api_token`,
|
|
290
|
+
* `AWS_SECRET_ACCESS_KEY`, `X-Amz-Signature`, `clientSecret`), but not `max_tokens` or `token_type`. Narrower than
|
|
291
|
+
* {@link isCredentialName}, which judges a URL's query parameters, because prose is full of `code=` and `key:`.
|
|
292
|
+
*/
|
|
293
|
+
export declare function isSecretFieldName(name: string): boolean;
|
|
294
|
+
/**
|
|
295
|
+
* Text with its secrets replaced (FR-006), the one redaction for signals and for what a harness mails: each exact secret named in
|
|
296
|
+
* `secrets` (four characters or more; a shorter one would garble the text and hide nothing), a private key block, each URL as
|
|
297
|
+
* `redactUrl` writes it, a bearer token, a basic credential (base64 of `user:pass`), the credential of an `Authorization` header with any
|
|
298
|
+
* scheme, the value of a `name=value` or `name: value` pair whose name {@link isSecretFieldName} judges secret (quoted or bare, in prose,
|
|
299
|
+
* JSON, YAML or an environment file), and the token formats that announce themselves (GitHub, GitLab, Slack, Google, Cloudflare,
|
|
300
|
+
* Anthropic, OpenAI, Stripe, npm, DigitalOcean, Docker, Hugging Face, Linear, Atlassian, JSON Web Tokens) and crypt password hashes
|
|
301
|
+
* become `REDACTED`.
|
|
302
|
+
*/
|
|
303
|
+
export declare function redactText(text: string, secrets?: Iterable<string>): string;
|
|
304
|
+
/** An attribute value with its secrets replaced: `redactText` on a string and on each string of an array. */
|
|
305
|
+
export declare function redactValue(value: AttributeValue): AttributeValue;
|
|
306
|
+
/** A log body with its secrets replaced, at every depth. */
|
|
307
|
+
export declare function redactAnyValue(value: AnyValue): AnyValue;
|
|
308
|
+
/** Attributes with the secret ones left out (never written, FR-006) and every other string redacted by `redactText`. */
|
|
309
|
+
export declare function redactAttributes(attributes: Attributes, secretKeys?: Iterable<string>): Attributes;
|
|
310
|
+
/**
|
|
311
|
+
* A command line as it may be recorded (FR-006): the program's name (its last path segment) and the names of its options alone, never a
|
|
312
|
+
* value, an operand or a subcommand. `--opt=value` is kept as `--opt`, a short option as its first letter (`-pSECRET` as `-p`), and
|
|
313
|
+
* nothing after `--`.
|
|
314
|
+
*/
|
|
315
|
+
export declare function commandShape(argv: readonly string[]): readonly string[];
|
|
316
|
+
/** The three signals. */
|
|
317
|
+
export type SignalName = "traces" | "logs" | "metrics";
|
|
318
|
+
/** Where and how one signal is exported. `endpoint` is undefined where none is configured (the runtime then probes the default). */
|
|
319
|
+
export type ExporterConfig = {
|
|
320
|
+
readonly enabled: boolean;
|
|
321
|
+
readonly endpoint: string | undefined;
|
|
322
|
+
readonly headers: Readonly<Record<string, string>>;
|
|
323
|
+
readonly timeoutMs: number;
|
|
324
|
+
};
|
|
325
|
+
/** The settings of a batch processor (`OTEL_BSP_*`, `OTEL_BLRP_*`). */
|
|
326
|
+
export type BatchConfig = {
|
|
327
|
+
readonly scheduleDelayMs: number;
|
|
328
|
+
readonly exportTimeoutMs: number;
|
|
329
|
+
readonly maxQueueSize: number;
|
|
330
|
+
readonly maxExportBatchSize: number;
|
|
331
|
+
};
|
|
332
|
+
/** The SDK's own log level (`OTEL_LOG_LEVEL`). */
|
|
333
|
+
export type LogLevel = "none" | "error" | "warn" | "info" | "debug" | "verbose" | "all";
|
|
334
|
+
/** The configuration the `OTEL_*` variables give. */
|
|
335
|
+
export type OtelConfig = {
|
|
336
|
+
readonly disabled: boolean;
|
|
337
|
+
readonly resource: Attributes;
|
|
338
|
+
readonly exporters: {
|
|
339
|
+
readonly [S in SignalName]: ExporterConfig;
|
|
340
|
+
};
|
|
341
|
+
readonly sampler: Sampler;
|
|
342
|
+
readonly spanBatch: BatchConfig;
|
|
343
|
+
readonly logBatch: BatchConfig;
|
|
344
|
+
readonly metricExportIntervalMs: number;
|
|
345
|
+
readonly metricExportTimeoutMs: number;
|
|
346
|
+
readonly limits: Limits;
|
|
347
|
+
readonly logLevel: LogLevel;
|
|
348
|
+
};
|
|
349
|
+
/** The endpoint an OTLP/HTTP exporter uses where none is configured. */
|
|
350
|
+
export declare const DEFAULT_OTLP_ENDPOINT = "http://localhost:4318";
|
|
351
|
+
/** The path of each signal under a base endpoint. */
|
|
352
|
+
export declare const SIGNAL_PATHS: {
|
|
353
|
+
readonly [S in SignalName]: string;
|
|
354
|
+
};
|
|
355
|
+
/** A base endpoint with a signal's path appended, with one `/` between them. */
|
|
356
|
+
export declare function signalEndpoint(base: string, signal: SignalName): string;
|
|
357
|
+
/**
|
|
358
|
+
* The configuration of the OpenTelemetry environment variables, from a record of them (FR-005): the kernel reads no environment. A value
|
|
359
|
+
* that is not valid is a warning and its default is used; an empty value counts as unset; no vendor's variable is read. A protocol other
|
|
360
|
+
* than `http/json` is a warning and disables the export of that signal.
|
|
361
|
+
*/
|
|
362
|
+
export declare function resolveConfig(env: Readonly<Record<string, string | undefined>>): {
|
|
363
|
+
readonly config: OtelConfig;
|
|
364
|
+
readonly warnings: readonly string[];
|
|
365
|
+
};
|