Telemetry

Source: packages/core/src/core/monitoring/telemetry.ts

Telemetry provides per-second performance snapshots during generation runs. Enabled via RunOptions.debug: true.

TelemetryCollector

Internal class that captures timing, throughput, and user progress data. Created automatically when debug: true is set in RunOptions.

class TelemetryCollector {
  constructor(lanes: number);
  start(): void;
  stop(): void;
  recordEvent(): void;
  recordUserStarted(): void;
  recordUserCompleted(): void;
  recordValidationSummary(summary: ValidationSummary): void;
  getReport(): TelemetryReport;
  async saveReport(filePath: string): Promise<void>;
}

• start() begins a 1-second interval timer for snapshot capture
• stop() clears the timer and captures a final snapshot
• saveReport() writes the report as pretty-printed JSON to disk

import { generate, InMemoryAdapter } from '@synode/core';

await generate(journey, {
  users: 5000,
  lanes: 4,
  adapter: new InMemoryAdapter(),
  debug: true,
  telemetryPath: './perf-report.json',
});
// Telemetry saved automatically to ./perf-report.json

TelemetryReport

Complete report for a generation run.

interface TelemetryReport {
  startTime: string; // ISO 8601
  endTime: string; // ISO 8601
  durationMs: number;
  totalUsers: number;
  totalEvents: number;
  lanes: number;
  averageEventsPerSecond: number;
  activeUsers: number;
  completedUsers: number;
  eventsValidated: number;
  eventsValid: number;
  eventsInvalid: number;
  validationErrors: TelemetryValidationError[];
  snapshots: TelemetrySnapshot[];
}

TelemetrySnapshot

Per-second data point captured during generation.

interface TelemetrySnapshot {
  timestamp: string; // ISO 8601
  elapsedMs: number;
  eventsPerSecond: number;
  totalEvents: number;
  activeUsers: number;
  completedUsers: number;
  lanes: number;
}

TelemetryValidationError

A single validation error entry recorded in the telemetry report.

interface TelemetryValidationError {
  eventName: string;
  path: string;
  message: string;
}

Validation errors are capped at 50 entries per report. Errors are merged from ValidationSummary via recordValidationSummary().