@mastra/observability 1.2.1 → 1.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +38 -0
- package/LICENSE.md +15 -0
- package/README.md +62 -1
- package/dist/bus/base.d.ts +43 -0
- package/dist/bus/base.d.ts.map +1 -0
- package/dist/bus/index.d.ts +7 -0
- package/dist/bus/index.d.ts.map +1 -0
- package/dist/bus/observability-bus.d.ts +97 -0
- package/dist/bus/observability-bus.d.ts.map +1 -0
- package/dist/bus/route-event.d.ts +31 -0
- package/dist/bus/route-event.d.ts.map +1 -0
- package/dist/context/index.d.ts +6 -0
- package/dist/context/index.d.ts.map +1 -0
- package/dist/context/logger.d.ts +45 -0
- package/dist/context/logger.d.ts.map +1 -0
- package/dist/context/metrics.d.ts +47 -0
- package/dist/context/metrics.d.ts.map +1 -0
- package/dist/exporters/base.d.ts +11 -0
- package/dist/exporters/base.d.ts.map +1 -1
- package/dist/exporters/index.d.ts +0 -1
- package/dist/exporters/index.d.ts.map +1 -1
- package/dist/exporters/test.d.ts +538 -3
- package/dist/exporters/test.d.ts.map +1 -1
- package/dist/index.cjs +1165 -104
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +3 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1155 -101
- package/dist/index.js.map +1 -1
- package/dist/instances/base.d.ts +77 -10
- package/dist/instances/base.d.ts.map +1 -1
- package/dist/metrics/auto-extract.d.ts +47 -0
- package/dist/metrics/auto-extract.d.ts.map +1 -0
- package/dist/metrics/cardinality.d.ts +24 -0
- package/dist/metrics/cardinality.d.ts.map +1 -0
- package/dist/metrics/index.d.ts +6 -0
- package/dist/metrics/index.d.ts.map +1 -0
- package/package.json +6 -6
- package/dist/exporters/json.d.ts +0 -386
- package/dist/exporters/json.d.ts.map +0 -1
package/dist/exporters/test.d.ts
CHANGED
|
@@ -1,13 +1,548 @@
|
|
|
1
|
-
|
|
1
|
+
/**
|
|
2
|
+
* Test Exporter for Observability
|
|
3
|
+
*
|
|
4
|
+
* A full-featured exporter primarily designed for testing purposes that provides:
|
|
5
|
+
* - In-memory event collection for ALL signals (Traces, Metrics, Logs, Scores, Feedback)
|
|
6
|
+
* - File output support
|
|
7
|
+
* - Span lifecycle tracking and validation
|
|
8
|
+
* - Query methods for filtering spans by type, trace ID, span ID, etc.
|
|
9
|
+
* - Query methods for filtering logs, metrics, scores, and feedback
|
|
10
|
+
* - Statistics and analytics on all collected signals
|
|
11
|
+
* - Internal metrics collection with summary on flush()
|
|
12
|
+
*/
|
|
13
|
+
import type { TracingEvent, TracingEventType, AnyExportedSpan, ExportedSpan, SpanType, LogEvent, MetricEvent, ScoreEvent, FeedbackEvent, ExportedLog, ExportedMetric, ExportedScore, ExportedFeedback, LogLevel, MetricType } from '@mastra/core/observability';
|
|
2
14
|
import { BaseExporter } from './base.js';
|
|
3
15
|
import type { BaseExporterConfig } from './base.js';
|
|
16
|
+
/**
|
|
17
|
+
* Span state tracking for lifecycle validation
|
|
18
|
+
*/
|
|
19
|
+
interface SpanState {
|
|
20
|
+
/** Whether SPAN_STARTED was received */
|
|
21
|
+
hasStart: boolean;
|
|
22
|
+
/** Whether SPAN_ENDED was received */
|
|
23
|
+
hasEnd: boolean;
|
|
24
|
+
/** Whether SPAN_UPDATED was received */
|
|
25
|
+
hasUpdate: boolean;
|
|
26
|
+
/** All events for this span in order */
|
|
27
|
+
events: TracingEvent[];
|
|
28
|
+
/** Whether this is an event span (zero duration) */
|
|
29
|
+
isEventSpan?: boolean;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Statistics about all collected signals
|
|
33
|
+
*/
|
|
34
|
+
export interface TestExporterStats {
|
|
35
|
+
/** Total number of tracing events collected */
|
|
36
|
+
totalTracingEvents: number;
|
|
37
|
+
/** Number of unique spans */
|
|
38
|
+
totalSpans: number;
|
|
39
|
+
/** Number of unique traces */
|
|
40
|
+
totalTraces: number;
|
|
41
|
+
/** Number of completed spans */
|
|
42
|
+
completedSpans: number;
|
|
43
|
+
/** Number of incomplete spans (started but not ended) */
|
|
44
|
+
incompleteSpans: number;
|
|
45
|
+
/** Breakdown by tracing event type */
|
|
46
|
+
byEventType: {
|
|
47
|
+
started: number;
|
|
48
|
+
updated: number;
|
|
49
|
+
ended: number;
|
|
50
|
+
};
|
|
51
|
+
/** Breakdown by span type */
|
|
52
|
+
bySpanType: Record<string, number>;
|
|
53
|
+
/** Total number of log events collected */
|
|
54
|
+
totalLogs: number;
|
|
55
|
+
/** Breakdown of logs by level */
|
|
56
|
+
logsByLevel: Record<string, number>;
|
|
57
|
+
/** Total number of metric events collected */
|
|
58
|
+
totalMetrics: number;
|
|
59
|
+
/** Breakdown of metrics by type */
|
|
60
|
+
metricsByType: Record<string, number>;
|
|
61
|
+
/** Breakdown of metrics by name */
|
|
62
|
+
metricsByName: Record<string, number>;
|
|
63
|
+
/** Total number of score events collected */
|
|
64
|
+
totalScores: number;
|
|
65
|
+
/** Breakdown of scores by scorer name */
|
|
66
|
+
scoresByScorer: Record<string, number>;
|
|
67
|
+
/** Total number of feedback events collected */
|
|
68
|
+
totalFeedback: number;
|
|
69
|
+
/** Breakdown of feedback by type */
|
|
70
|
+
feedbackByType: Record<string, number>;
|
|
71
|
+
/** @deprecated Use totalTracingEvents instead */
|
|
72
|
+
totalEvents: number;
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Internal metrics collected by the TestExporter while running.
|
|
76
|
+
* Dumped as a summary on flush().
|
|
77
|
+
*/
|
|
78
|
+
export interface TestExporterInternalMetrics {
|
|
79
|
+
/** Timestamp when the exporter was created */
|
|
80
|
+
startedAt: Date;
|
|
81
|
+
/** Timestamp of the last event received */
|
|
82
|
+
lastEventAt: Date | null;
|
|
83
|
+
/** Total events received across all signal types */
|
|
84
|
+
totalEventsReceived: number;
|
|
85
|
+
/** Breakdown by signal type */
|
|
86
|
+
bySignal: {
|
|
87
|
+
tracing: number;
|
|
88
|
+
log: number;
|
|
89
|
+
metric: number;
|
|
90
|
+
score: number;
|
|
91
|
+
feedback: number;
|
|
92
|
+
};
|
|
93
|
+
/** Number of flush() calls */
|
|
94
|
+
flushCount: number;
|
|
95
|
+
/** Total bytes of JSON output produced (estimated from toJSON) */
|
|
96
|
+
estimatedJsonBytes: number;
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* Span node in a tree structure with nested children
|
|
100
|
+
*/
|
|
101
|
+
export interface SpanTreeNode {
|
|
102
|
+
/** The span data */
|
|
103
|
+
span: AnyExportedSpan;
|
|
104
|
+
/** Child spans nested under this span */
|
|
105
|
+
children: SpanTreeNode[];
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* Normalized span data for snapshot testing.
|
|
109
|
+
* Dynamic fields (IDs, timestamps) are replaced with stable values.
|
|
110
|
+
*/
|
|
111
|
+
export interface NormalizedSpan {
|
|
112
|
+
/** Stable ID like <span-1>, <span-2> */
|
|
113
|
+
id: string;
|
|
114
|
+
/** Normalized trace ID like <trace-1>, <trace-2> */
|
|
115
|
+
traceId: string;
|
|
116
|
+
/** Normalized parent ID, or undefined for root */
|
|
117
|
+
parentId?: string;
|
|
118
|
+
/** Span name */
|
|
119
|
+
name: string;
|
|
120
|
+
/** Span type */
|
|
121
|
+
type: string;
|
|
122
|
+
/** Entity type */
|
|
123
|
+
entityType?: string;
|
|
124
|
+
/** Entity ID */
|
|
125
|
+
entityId?: string;
|
|
126
|
+
/** Whether the span completed (had an endTime) */
|
|
127
|
+
completed: boolean;
|
|
128
|
+
/** Span attributes */
|
|
129
|
+
attributes?: Record<string, unknown>;
|
|
130
|
+
/** Span metadata */
|
|
131
|
+
metadata?: Record<string, unknown>;
|
|
132
|
+
/** Input data */
|
|
133
|
+
input?: unknown;
|
|
134
|
+
/** Output data */
|
|
135
|
+
output?: unknown;
|
|
136
|
+
/** Error info if span failed */
|
|
137
|
+
errorInfo?: unknown;
|
|
138
|
+
/** Is an event span */
|
|
139
|
+
isEvent: boolean;
|
|
140
|
+
/** Is root span */
|
|
141
|
+
isRootSpan: boolean;
|
|
142
|
+
/** Tags */
|
|
143
|
+
tags?: string[];
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* Normalized tree node for snapshot testing
|
|
147
|
+
*/
|
|
148
|
+
export interface NormalizedTreeNode {
|
|
149
|
+
/** Normalized span data */
|
|
150
|
+
span: NormalizedSpan;
|
|
151
|
+
/** Child nodes (omitted if empty) */
|
|
152
|
+
children?: NormalizedTreeNode[];
|
|
153
|
+
}
|
|
154
|
+
/**
|
|
155
|
+
* Incomplete span information for debugging
|
|
156
|
+
*/
|
|
157
|
+
export interface IncompleteSpanInfo {
|
|
158
|
+
spanId: string;
|
|
159
|
+
span: AnyExportedSpan | undefined;
|
|
160
|
+
state: {
|
|
161
|
+
hasStart: boolean;
|
|
162
|
+
hasUpdate: boolean;
|
|
163
|
+
hasEnd: boolean;
|
|
164
|
+
};
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* Configuration for TestExporter
|
|
168
|
+
*/
|
|
169
|
+
export interface TestExporterConfig extends BaseExporterConfig {
|
|
170
|
+
/**
|
|
171
|
+
* Whether to validate span lifecycles in real-time.
|
|
172
|
+
* When true, will log warnings for lifecycle violations.
|
|
173
|
+
* @default true
|
|
174
|
+
*/
|
|
175
|
+
validateLifecycle?: boolean;
|
|
176
|
+
/**
|
|
177
|
+
* Whether to store verbose logs for debugging.
|
|
178
|
+
* @default true
|
|
179
|
+
*/
|
|
180
|
+
storeLogs?: boolean;
|
|
181
|
+
/**
|
|
182
|
+
* Indentation for JSON output (number of spaces, or undefined for compact).
|
|
183
|
+
* @default 2
|
|
184
|
+
*/
|
|
185
|
+
jsonIndent?: number;
|
|
186
|
+
/**
|
|
187
|
+
* Whether to log a summary of internal metrics on flush().
|
|
188
|
+
* @default true
|
|
189
|
+
*/
|
|
190
|
+
logMetricsOnFlush?: boolean;
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* Test Exporter for observability testing and debugging.
|
|
194
|
+
*
|
|
195
|
+
* Provides comprehensive in-memory event collection, querying, and JSON output
|
|
196
|
+
* capabilities designed primarily for testing purposes but useful for debugging as well.
|
|
197
|
+
*
|
|
198
|
+
* @example
|
|
199
|
+
* ```typescript
|
|
200
|
+
* const exporter = new TestExporter();
|
|
201
|
+
*
|
|
202
|
+
* // Use with Mastra
|
|
203
|
+
* const mastra = new Mastra({
|
|
204
|
+
* observability: {
|
|
205
|
+
* configs: {
|
|
206
|
+
* test: {
|
|
207
|
+
* serviceName: 'test',
|
|
208
|
+
* exporters: [exporter],
|
|
209
|
+
* },
|
|
210
|
+
* },
|
|
211
|
+
* },
|
|
212
|
+
* });
|
|
213
|
+
*
|
|
214
|
+
* // Run some operations...
|
|
215
|
+
*
|
|
216
|
+
* // Query spans
|
|
217
|
+
* const agentSpans = exporter.getSpansByType('agent_run');
|
|
218
|
+
* const traceSpans = exporter.getByTraceId('abc123');
|
|
219
|
+
*
|
|
220
|
+
* // Get statistics
|
|
221
|
+
* const stats = exporter.getStatistics();
|
|
222
|
+
*
|
|
223
|
+
* // Export to JSON
|
|
224
|
+
* await exporter.writeToFile('./traces.json');
|
|
225
|
+
* const jsonString = exporter.toJSON();
|
|
226
|
+
* ```
|
|
227
|
+
*/
|
|
4
228
|
export declare class TestExporter extends BaseExporter {
|
|
5
229
|
#private;
|
|
6
230
|
name: string;
|
|
7
|
-
constructor(config?:
|
|
231
|
+
constructor(config?: TestExporterConfig);
|
|
232
|
+
/**
|
|
233
|
+
* Process incoming tracing events with lifecycle tracking
|
|
234
|
+
*/
|
|
8
235
|
protected _exportTracingEvent(event: TracingEvent): Promise<void>;
|
|
9
|
-
|
|
236
|
+
/**
|
|
237
|
+
* Process incoming log events
|
|
238
|
+
*/
|
|
239
|
+
onLogEvent(event: LogEvent): Promise<void>;
|
|
240
|
+
/**
|
|
241
|
+
* Process incoming metric events
|
|
242
|
+
*/
|
|
243
|
+
onMetricEvent(event: MetricEvent): Promise<void>;
|
|
244
|
+
/**
|
|
245
|
+
* Process incoming score events
|
|
246
|
+
*/
|
|
247
|
+
onScoreEvent(event: ScoreEvent): Promise<void>;
|
|
248
|
+
/**
|
|
249
|
+
* Process incoming feedback events
|
|
250
|
+
*/
|
|
251
|
+
onFeedbackEvent(event: FeedbackEvent): Promise<void>;
|
|
252
|
+
/**
|
|
253
|
+
* Get all collected tracing events
|
|
254
|
+
*/
|
|
10
255
|
get events(): TracingEvent[];
|
|
256
|
+
/**
|
|
257
|
+
* Get completed spans by SpanType (e.g., 'agent_run', 'tool_call')
|
|
258
|
+
*
|
|
259
|
+
* @param type - The SpanType to filter by
|
|
260
|
+
* @returns Array of completed exported spans of the specified type
|
|
261
|
+
*/
|
|
262
|
+
getSpansByType<T extends SpanType>(type: T): ExportedSpan<T>[];
|
|
263
|
+
/**
|
|
264
|
+
* Get events by TracingEventType (SPAN_STARTED, SPAN_UPDATED, SPAN_ENDED)
|
|
265
|
+
*
|
|
266
|
+
* @param type - The TracingEventType to filter by
|
|
267
|
+
* @returns Array of events of the specified type
|
|
268
|
+
*/
|
|
269
|
+
getByEventType(type: TracingEventType): TracingEvent[];
|
|
270
|
+
/**
|
|
271
|
+
* Get all events and spans for a specific trace
|
|
272
|
+
*
|
|
273
|
+
* @param traceId - The trace ID to filter by
|
|
274
|
+
* @returns Object containing tracing events, final spans, plus logs/scores/feedback for the trace
|
|
275
|
+
*/
|
|
276
|
+
getByTraceId(traceId: string): {
|
|
277
|
+
events: TracingEvent[];
|
|
278
|
+
spans: AnyExportedSpan[];
|
|
279
|
+
logs: ExportedLog[];
|
|
280
|
+
scores: ExportedScore[];
|
|
281
|
+
feedback: ExportedFeedback[];
|
|
282
|
+
};
|
|
283
|
+
/**
|
|
284
|
+
* Get all events for a specific span
|
|
285
|
+
*
|
|
286
|
+
* @param spanId - The span ID to filter by
|
|
287
|
+
* @returns Object containing events and final span state
|
|
288
|
+
*/
|
|
289
|
+
getBySpanId(spanId: string): {
|
|
290
|
+
events: TracingEvent[];
|
|
291
|
+
span: AnyExportedSpan | undefined;
|
|
292
|
+
state: SpanState | undefined;
|
|
293
|
+
};
|
|
294
|
+
/**
|
|
295
|
+
* Get all unique spans (returns the final state of each span)
|
|
296
|
+
*/
|
|
297
|
+
getAllSpans(): AnyExportedSpan[];
|
|
298
|
+
/**
|
|
299
|
+
* Get only completed spans (those that have received SPAN_ENDED)
|
|
300
|
+
*/
|
|
301
|
+
getCompletedSpans(): AnyExportedSpan[];
|
|
302
|
+
/**
|
|
303
|
+
* Get root spans only (spans with no parent)
|
|
304
|
+
*/
|
|
305
|
+
getRootSpans(): AnyExportedSpan[];
|
|
306
|
+
/**
|
|
307
|
+
* Get incomplete spans (started but not yet ended)
|
|
308
|
+
*/
|
|
309
|
+
getIncompleteSpans(): IncompleteSpanInfo[];
|
|
310
|
+
/**
|
|
311
|
+
* Get unique trace IDs from all collected signals
|
|
312
|
+
*/
|
|
313
|
+
getTraceIds(): string[];
|
|
314
|
+
/**
|
|
315
|
+
* Get all collected log events
|
|
316
|
+
*/
|
|
317
|
+
getLogEvents(): LogEvent[];
|
|
318
|
+
/**
|
|
319
|
+
* Get all collected logs (unwrapped from events)
|
|
320
|
+
*/
|
|
321
|
+
getAllLogs(): ExportedLog[];
|
|
322
|
+
/**
|
|
323
|
+
* Get logs filtered by level
|
|
324
|
+
*/
|
|
325
|
+
getLogsByLevel(level: LogLevel): ExportedLog[];
|
|
326
|
+
/**
|
|
327
|
+
* Get logs for a specific trace
|
|
328
|
+
*/
|
|
329
|
+
getLogsByTraceId(traceId: string): ExportedLog[];
|
|
330
|
+
/**
|
|
331
|
+
* Get all collected metric events
|
|
332
|
+
*/
|
|
333
|
+
getMetricEvents(): MetricEvent[];
|
|
334
|
+
/**
|
|
335
|
+
* Get all collected metrics (unwrapped from events)
|
|
336
|
+
*/
|
|
337
|
+
getAllMetrics(): ExportedMetric[];
|
|
338
|
+
/**
|
|
339
|
+
* Get metrics filtered by name
|
|
340
|
+
*/
|
|
341
|
+
getMetricsByName(name: string): ExportedMetric[];
|
|
342
|
+
/**
|
|
343
|
+
* Get metrics filtered by type
|
|
344
|
+
*/
|
|
345
|
+
getMetricsByType(metricType: MetricType): ExportedMetric[];
|
|
346
|
+
/**
|
|
347
|
+
* Get all collected score events
|
|
348
|
+
*/
|
|
349
|
+
getScoreEvents(): ScoreEvent[];
|
|
350
|
+
/**
|
|
351
|
+
* Get all collected scores (unwrapped from events)
|
|
352
|
+
*/
|
|
353
|
+
getAllScores(): ExportedScore[];
|
|
354
|
+
/**
|
|
355
|
+
* Get scores filtered by scorer name
|
|
356
|
+
*/
|
|
357
|
+
getScoresByScorer(scorerName: string): ExportedScore[];
|
|
358
|
+
/**
|
|
359
|
+
* Get scores for a specific trace
|
|
360
|
+
*/
|
|
361
|
+
getScoresByTraceId(traceId: string): ExportedScore[];
|
|
362
|
+
/**
|
|
363
|
+
* Get all collected feedback events
|
|
364
|
+
*/
|
|
365
|
+
getFeedbackEvents(): FeedbackEvent[];
|
|
366
|
+
/**
|
|
367
|
+
* Get all collected feedback (unwrapped from events)
|
|
368
|
+
*/
|
|
369
|
+
getAllFeedback(): ExportedFeedback[];
|
|
370
|
+
/**
|
|
371
|
+
* Get feedback filtered by type
|
|
372
|
+
*/
|
|
373
|
+
getFeedbackByType(feedbackType: string): ExportedFeedback[];
|
|
374
|
+
/**
|
|
375
|
+
* Get feedback for a specific trace
|
|
376
|
+
*/
|
|
377
|
+
getFeedbackByTraceId(traceId: string): ExportedFeedback[];
|
|
378
|
+
/**
|
|
379
|
+
* Get comprehensive statistics about all collected signals
|
|
380
|
+
*/
|
|
381
|
+
getStatistics(): TestExporterStats;
|
|
382
|
+
/**
|
|
383
|
+
* Serialize all collected data to JSON string
|
|
384
|
+
*
|
|
385
|
+
* @param options - Serialization options
|
|
386
|
+
* @returns JSON string of all collected data
|
|
387
|
+
*/
|
|
388
|
+
toJSON(options?: {
|
|
389
|
+
indent?: number;
|
|
390
|
+
includeEvents?: boolean;
|
|
391
|
+
includeStats?: boolean;
|
|
392
|
+
}): string;
|
|
393
|
+
/**
|
|
394
|
+
* Build a tree structure from spans, nesting children under their parents
|
|
395
|
+
*
|
|
396
|
+
* @returns Array of root span tree nodes (spans with no parent)
|
|
397
|
+
*/
|
|
398
|
+
buildSpanTree(): SpanTreeNode[];
|
|
399
|
+
/**
|
|
400
|
+
* Serialize spans as a tree structure to JSON string
|
|
401
|
+
*
|
|
402
|
+
* @param options - Serialization options
|
|
403
|
+
* @returns JSON string with spans nested in tree format
|
|
404
|
+
*/
|
|
405
|
+
toTreeJSON(options?: {
|
|
406
|
+
indent?: number;
|
|
407
|
+
includeStats?: boolean;
|
|
408
|
+
}): string;
|
|
409
|
+
/**
|
|
410
|
+
* Build a normalized tree structure suitable for snapshot testing.
|
|
411
|
+
*
|
|
412
|
+
* Normalizations applied:
|
|
413
|
+
* - Span IDs replaced with stable placeholders (<span-1>, <span-2>, etc.)
|
|
414
|
+
* - Trace IDs replaced with stable placeholders (<trace-1>, <trace-2>, etc.)
|
|
415
|
+
* - parentSpanId replaced with normalized parent ID
|
|
416
|
+
* - Timestamps replaced with durationMs (or null if not ended)
|
|
417
|
+
* - Empty children arrays are omitted
|
|
418
|
+
*
|
|
419
|
+
* @returns Array of normalized root tree nodes
|
|
420
|
+
*/
|
|
421
|
+
buildNormalizedTree(): NormalizedTreeNode[];
|
|
422
|
+
/**
|
|
423
|
+
* Generate an ASCII tree structure graph for debugging.
|
|
424
|
+
* Shows span type and name in a hierarchical format.
|
|
425
|
+
*
|
|
426
|
+
* @param nodes - Normalized tree nodes (defaults to current normalized tree)
|
|
427
|
+
* @returns Array of strings representing the tree structure
|
|
428
|
+
*
|
|
429
|
+
* @example
|
|
430
|
+
* ```
|
|
431
|
+
* agent_run: "agent run: 'test-agent'"
|
|
432
|
+
* ├── processor_run: "input processor: validator"
|
|
433
|
+
* │ └── agent_run: "agent run: 'validator-agent'"
|
|
434
|
+
* └── model_generation: "llm: 'mock-model-id'"
|
|
435
|
+
* ```
|
|
436
|
+
*/
|
|
437
|
+
generateStructureGraph(nodes?: NormalizedTreeNode[]): string[];
|
|
438
|
+
/**
|
|
439
|
+
* Serialize spans as a normalized tree structure for snapshot testing.
|
|
440
|
+
* Includes a __structure__ field with an ASCII tree graph for readability.
|
|
441
|
+
*
|
|
442
|
+
* @param options - Serialization options
|
|
443
|
+
* @returns JSON string with normalized spans in tree format
|
|
444
|
+
*/
|
|
445
|
+
toNormalizedTreeJSON(options?: {
|
|
446
|
+
indent?: number;
|
|
447
|
+
includeStructure?: boolean;
|
|
448
|
+
}): string;
|
|
449
|
+
/**
|
|
450
|
+
* Write collected data to a JSON file
|
|
451
|
+
*
|
|
452
|
+
* @param filePath - Path to write the JSON file
|
|
453
|
+
* @param options - Serialization options
|
|
454
|
+
*/
|
|
455
|
+
writeToFile(filePath: string, options?: {
|
|
456
|
+
indent?: number;
|
|
457
|
+
includeEvents?: boolean;
|
|
458
|
+
includeStats?: boolean;
|
|
459
|
+
format?: 'flat' | 'tree' | 'normalized';
|
|
460
|
+
}): Promise<void>;
|
|
461
|
+
/**
|
|
462
|
+
* Assert that the current normalized tree matches a snapshot file.
|
|
463
|
+
* Throws an error with a diff if they don't match.
|
|
464
|
+
*
|
|
465
|
+
* The snapshot format includes:
|
|
466
|
+
* - `__structure__`: ASCII tree graph (compared first for quick validation)
|
|
467
|
+
* - `spans`: The normalized span tree (detailed comparison)
|
|
468
|
+
*
|
|
469
|
+
* Supports special markers in the snapshot:
|
|
470
|
+
* - `{"__or__": ["value1", "value2"]}` - matches if actual equals any listed value
|
|
471
|
+
* - `{"__any__": "string"}` - matches any string value
|
|
472
|
+
* - `{"__any__": "number"}` - matches any number value
|
|
473
|
+
* - `{"__any__": "boolean"}` - matches any boolean value
|
|
474
|
+
* - `{"__any__": "object"}` - matches any object value
|
|
475
|
+
* - `{"__any__": "array"}` - matches any array value
|
|
476
|
+
* - `{"__any__": true}` - matches any non-null/undefined value
|
|
477
|
+
*
|
|
478
|
+
* Environment variables:
|
|
479
|
+
* Use `{ updateSnapshot: true }` option to update the snapshot instead of comparing
|
|
480
|
+
*
|
|
481
|
+
* @param snapshotName - Name of the snapshot file (resolved relative to __snapshots__ directory)
|
|
482
|
+
* @param options - Options for snapshot comparison
|
|
483
|
+
* @param options.updateSnapshot - If true, update the snapshot file instead of comparing
|
|
484
|
+
* @throws Error if the snapshot doesn't match (and updateSnapshot is false)
|
|
485
|
+
*/
|
|
486
|
+
assertMatchesSnapshot(snapshotName: string, options?: {
|
|
487
|
+
updateSnapshot?: boolean;
|
|
488
|
+
}): Promise<void>;
|
|
489
|
+
/**
|
|
490
|
+
* Get all stored debug logs (internal exporter logging, not signal logs)
|
|
491
|
+
*/
|
|
492
|
+
getLogs(): string[];
|
|
493
|
+
/**
|
|
494
|
+
* Dump debug logs to console for debugging (uses console.error for visibility in test output)
|
|
495
|
+
*/
|
|
496
|
+
dumpLogs(): void;
|
|
497
|
+
/**
|
|
498
|
+
* Validate final state - useful for test assertions
|
|
499
|
+
*
|
|
500
|
+
* @returns Object with validation results
|
|
501
|
+
*/
|
|
502
|
+
validateFinalState(): {
|
|
503
|
+
valid: boolean;
|
|
504
|
+
singleTraceId: boolean;
|
|
505
|
+
allSpansComplete: boolean;
|
|
506
|
+
traceIds: string[];
|
|
507
|
+
incompleteSpans: IncompleteSpanInfo[];
|
|
508
|
+
};
|
|
509
|
+
/**
|
|
510
|
+
* Clear all collected events and state across all signals
|
|
511
|
+
*/
|
|
512
|
+
clearEvents(): void;
|
|
513
|
+
/**
|
|
514
|
+
* Alias for clearEvents (compatibility with TestExporter)
|
|
515
|
+
*/
|
|
516
|
+
reset(): void;
|
|
517
|
+
/**
|
|
518
|
+
* Get internal metrics about the exporter's own activity.
|
|
519
|
+
*/
|
|
520
|
+
getInternalMetrics(): TestExporterInternalMetrics;
|
|
521
|
+
/**
|
|
522
|
+
* Flush buffered data and log internal metrics summary.
|
|
523
|
+
*/
|
|
524
|
+
flush(): Promise<void>;
|
|
11
525
|
shutdown(): Promise<void>;
|
|
12
526
|
}
|
|
527
|
+
/**
|
|
528
|
+
* @deprecated Use `TestExporter` instead. This alias will be removed in a future version.
|
|
529
|
+
*/
|
|
530
|
+
export declare const JsonExporter: typeof TestExporter;
|
|
531
|
+
/**
|
|
532
|
+
* @deprecated Use `TestExporter` instead. This is a type alias for backward compatibility.
|
|
533
|
+
*/
|
|
534
|
+
export type JsonExporter = TestExporter;
|
|
535
|
+
/**
|
|
536
|
+
* @deprecated Use `TestExporterConfig` instead.
|
|
537
|
+
*/
|
|
538
|
+
export type JsonExporterConfig = TestExporterConfig;
|
|
539
|
+
/**
|
|
540
|
+
* @deprecated Use `TestExporterStats` instead.
|
|
541
|
+
*/
|
|
542
|
+
export type JsonExporterStats = TestExporterStats;
|
|
543
|
+
/**
|
|
544
|
+
* @deprecated Use `TestExporterInternalMetrics` instead.
|
|
545
|
+
*/
|
|
546
|
+
export type JsonExporterInternalMetrics = TestExporterInternalMetrics;
|
|
547
|
+
export {};
|
|
13
548
|
//# sourceMappingURL=test.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"test.d.ts","sourceRoot":"","sources":["../../src/exporters/test.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,
|
|
1
|
+
{"version":3,"file":"test.d.ts","sourceRoot":"","sources":["../../src/exporters/test.ts"],"names":[],"mappings":"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"}
|