@observertc/observer-js 1.3.0-rc.5 → 1.3.0-rc.6

package/README.md

@@ -1975,6 +1975,7 @@ its id — refuse writes after it, and emit `close` / `error` for its destinatio
 | Export | Notes |
 |--------|-------|
 | `JsonlFileSink<T = ClientSample>` / `createJsonlFileSink<T>({ path, serializeSample? })` | appends one JSON line per record; wraps `fs.WriteStream` and re-emits its events; exposes `readonly path`. The directory **must exist** |
+| `RollingJsonlFileSink<T>` | JSONL over a sequence of files for long-lived owners: rolls on `maxBytes`, `maxAgeMs` or `roll()`; `file-closed` per finished file. See [Rolling files](#rolling-files) |
 | `InMemorySink` / `createInMemorySink(samples?)` | collects client samples into `.samples`; emits `close` on `end()` |
 
 ### Client samples
@@ -2101,6 +2102,43 @@ and the extension stats' sinks are ended. The owner's other sinks end with its `
 usual. `extensionStats.close()` can also be called directly; it ends only the extension stats'
 sinks.
 
+### Rolling files
+
+`JsonlFileSink` writes one file for the sink's whole life — right for calls and clients, which come
+and go. An owner that lives for days or months, such as the observer itself, needs its records cut
+into several files. `RollingJsonlFileSink` does that: it writes JSONL to a sequence of files, closing
+the current one and opening the next (*rolling*) before a write that would exceed `maxBytes`, once
+the current file has been open for `maxAgeMs`, or when `roll()` is called.
+
+```ts
+const sink = new RollingJsonlFileSink({
+  id: 'sfu-cpu',
+  path: ({ index, openedAt }) => `./stats/sfu-cpu-${openedAt}-${index}.jsonl`,
+  maxBytes: 100 * 1024 * 1024,
+  maxAgeMs: 60 * 60 * 1000,
+});
+
+sink.on('file-closed', (path, index) => uploadFile(path));   // flushed & fd closed → ready
+
+observer.createExtensionStats({ id: 'sfu-cpu', sink });
+setInterval(async () => observer.acceptExtensionStats('sfu-cpu', await readCpu()), 5_000).unref();
+```
+
+| Option / member | Meaning |
+|-----------------|---------|
+| `path({ index, openedAt })` | the path of each file, called when it is opened (`index` 0, 1, 2, …; `openedAt` = `Date.now()`). Must give a new path per `index` |
+| `maxBytes?`, `maxAgeMs?` | roll before a write that would make the file larger than `maxBytes`, or once it has been open for `maxAgeMs` |
+| `serializeSample?` | custom serializer; defaults to `JSON.stringify` |
+| `roll()` | close the current file and continue in a new one |
+| `path`, `index` | the file currently written to |
+
+- Nothing is dropped: each record goes to exactly one file.
+- The limits are checked on `write`, so the sink runs no timers: a file is not rolled while nothing
+  is written to it, and an empty file is never rolled (`roll()` on one is a no-op).
+- `file-closed` (`path`, `index`) fires for every finished file, in index order, the last one
+  included. `close` fires once, after `end()` has closed every file. The owner ends the sink as
+  usual — here when the observer closes.
+
 ### Other records: e.g. mediasoup pipe transport stats
 
 ```ts

package/dist/index.d.mts

@@ -7236,6 +7236,74 @@ declare class JsonlFileSink<T = ClientSample> extends EventEmitter implements Si
 /** Build a JSONL file sink for a single path. */
 declare function createJsonlFileSink<T = ClientSample>(options: JsonlFileSinkOptions<T>): JsonlFileSink<T>;
 
+/** The file a `RollingJsonlFileSink` is about to open: the sequence number and when it opens. */
+type RollingJsonlFileInfo = {
+    /** 0 for the first file, then 1, 2, … */
+    index: number;
+    /** `Date.now()` when the file is opened. */
+    openedAt: number;
+};
+type RollingJsonlFileSinkOptions<T = unknown> = Partial<SinkSettings> & {
+    /** The path of each file, called when it is opened. Must give a new path per `index`. */
+    path: (file: RollingJsonlFileInfo) => string;
+    /** Roll before a write that would make the current file larger than this, in bytes. */
+    maxBytes?: number;
+    /** Roll before a write once the current file has been open for this long, in ms. */
+    maxAgeMs?: number;
+    /** Optional custom serializer; defaults to `JSON.stringify`. */
+    serializeSample?: (record: T) => string;
+};
+type RollingJsonlFileSinkEvents = {
+    ended: SinkEvents['ended'];
+    close: SinkEvents['close'];
+    error: SinkEvents['error'];
+    finish: SinkEvents['finish'];
+    drain: SinkEvents['drain'];
+    /** A file is complete: flushed and its descriptor closed. Fires for every file, the last one included. */
+    'file-closed': [path: string, index: number];
+};
+declare interface RollingJsonlFileSink {
+    on<E extends keyof RollingJsonlFileSinkEvents>(event: E, listener: (...args: RollingJsonlFileSinkEvents[E]) => void): this;
+    once<E extends keyof RollingJsonlFileSinkEvents>(event: E, listener: (...args: RollingJsonlFileSinkEvents[E]) => void): this;
+    off<E extends keyof RollingJsonlFileSinkEvents>(event: E, listener: (...args: RollingJsonlFileSinkEvents[E]) => void): this;
+    emit<E extends keyof RollingJsonlFileSinkEvents>(event: E, ...args: RollingJsonlFileSinkEvents[E]): boolean;
+}
+/**
+ * A JSONL file sink for long-lived owners (e.g. an observer's extension stats over days): it writes
+ * to a sequence of files, closing the current one and opening the next — *rolling* — when it would
+ * exceed `maxBytes`, when it has been open for `maxAgeMs`, or when `roll()` is called. Nothing is
+ * dropped: each record goes to exactly one file.
+ *
+ * The limits are checked on `write`, so a file is never rolled while nothing is written to it, and
+ * an empty file is never rolled. `file-closed` announces each finished file (ready to upload or
+ * move), in index order; `close` fires once, after every file is closed by `end()`.
+ */
+declare class RollingJsonlFileSink<T = unknown> extends EventEmitter implements Sink<T> {
+    readonly id: string;
+    private readonly _options;
+    private readonly _serializeSample;
+    private _stream;
+    private _path;
+    private _index;
+    private _openedAt;
+    private _bytes;
+    private _ended;
+    private _closing;
+    constructor(options: RollingJsonlFileSinkOptions<T>);
+    /** The file currently written to. */
+    get path(): string;
+    /** The index of the file currently written to. */
+    get index(): number;
+    get ended(): boolean;
+    write(record: T): boolean;
+    /** Close the current file and continue in a new one. A no-op on an empty file or an ended sink. */
+    roll(): void;
+    /** No more writes: emits `ended`, closes the current file (`file-closed`), then emits `close`. */
+    end(): void;
+    private _open;
+    private _closeCurrent;
+}
+
 declare interface InMemorySink {
     on<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
     once<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
@@ -7262,4 +7330,4 @@ declare function createInMemorySink(samples?: ClientSample[]): InMemorySink;
 declare function createDefaultMediasoupRemoteTrackResolverFactory(): RemoteTrackResolverFactory;
 declare function createP2pRemoteTrackResolverFactory(): RemoteTrackResolverFactory;
 
-export { type AcceptContext, type AcceptMiddleware, type AcceptMiddlewarePayload, type ActiveClientIssue, type ActiveIssueTracker, ActiveIssuesRegistry, AudioEchoDetector, type AudioEchoDetectorConfig, AudioEchoTypes, type AudioInputDevice, type AvailableCallScopeDetectorsConfigs, type AvailableDetectorsConfigs, type AvailableObserverScopeDetectorsConfigs, type AvailableValidatorConfigs, CODEC_MISMATCH_ISSUE, type CalculatedScore, type CallAppDataFactory, CallConcurrentIssueDetector, type CallConcurrentIssueDetectorConfig, type CallConcurrentIssueGroup, CallConcurrentIssueTypes, type CallHealth, CallHealthAggregator, type CallIssue, type CallIssueSpread, type CallScopedEventName, type CallSummary, type CallSummaryClients, CallSummaryCollector, type CallSummaryConfig, type CallSummaryEnricher, type CallSummaryEnrichers, type CallSummaryScores, type CallSummarySection, type CallSummaryTruncation, type CallSummaryTurnServers, type CertificateStats, type ClientAppDataFactory, type ClientEvent, ClientEventTypes, type ClientHealth, type ClientHealthThresholds, type ClientIssue, type ClientLocation, type ClientLocationResolver, type ClientMetaData, ClientMetaTypes, type ClientPopulation, type ClientPopulationAxis, ClientPopulationIssueDetector, type ClientPopulationIssueDetectorConfig, ClientPopulationIssueTypes, type ClientSample, type ClientSampleSink, type ClientSampleSinkEvents, type ClientSinkParams, type CodecConsistencyReportPayload, CodecConsistencyValidator, type CodecConsistencyValidatorConfig, type CodecEvidence, type CodecStats, type CorroboratedPublisherFault, type CreateExtensionStatsSettings, type DataChannelStats, type Detector, Detectors, type ExtensionStat, ExtensionStatsRegistry, GEOHASH_CELL_SIZES, type IceCandidatePairStats, type IceCandidateStats, type IceTransportStats, InMemorySink, type InboundRtpStats, type InboundTrackSample, type Issue, type IssueBase, type IssueConclusion, IssueFanOutDetector, type IssueFanOutDetectorConfig, IssueFanOutTypes, type IssueFaultDomain, JsonlFileSink, type JsonlFileSinkOptions, LOWEST_COMMON_DENOMINATOR_ISSUE, type Logger, type MannKendallResult, type MediaKind, type MediaPlayoutStats, type MediaSourceStats, type MediasoupConsumerSample, type MediasoupConsumerSampleEvent, type MediasoupDataConsumerSample, type MediasoupDataProducerSample, type MediasoupDirectTransportSample, type MediasoupDirectTransportSampleEventMap, type MediasoupPipeTransportSample, type MediasoupPipeTransportSampleEventMap, type MediasoupPlainTransportSample, type MediasoupPlainTransportSampleEventMap, type MediasoupProducerSample, type MediasoupProducerSampleEvent, type MediasoupRouterSample, type MediasoupSampleEnricher, type MediasoupTransportSample, type MediasoupWebRtcTransportSample, type MediasoupWebRtcTransportSampleEventMap, type Middleware, MiddlewareProcessor, ObservedCall, type ObservedCallScope, type ObservedCallSettings, ObservedCertificate, ObservedClient, ObservedClientIssueRegistry, type ObservedClientScope, type ObservedClientSettings, ObservedCodec, ObservedDataChannel, ObservedIceCandidate, ObservedIceCandidatePair, ObservedIceTransport, ObservedInboundRtp, ObservedInboundTrack, ObservedMediaPlayout, ObservedMediaSource, ObservedMediasoupRouter, type ObservedMediasoupRouterEvents, type ObservedMediasoupRouterScope, type ObservedMediasoupRouterSettings, ObservedOutboundRtp, ObservedOutboundTrack, ObservedPeerConnection, type ObservedPeerConnectionScope, ObservedPeerConnectionTransport, ObservedRemoteInboundRtp, ObservedRemoteOutboundRtp, ObservedTURN, type ObservedTURNEventMap, ObservedTurnServer, Observer, ObserverConcurrentIssueDetector, type ObserverConcurrentIssueDetectorConfig, type ObserverConcurrentIssueGroup, ObserverConcurrentIssueTypes, type ObserverEventBase, type ObserverEvents, type ObserverIssue, type ObserverIssueSpread, type ObserverLogger, type OutboundRtpStats, type OutboundTrackSample, type PageHinkleyResult, type PeerConnectionSample, type PeerConnectionTransportStats, type PsnrSum, PublisherFaultCorroborationDetector, type PublisherFaultCorroborationDetectorConfig, PublisherFaultTypes, type QualityLimitationDurations, RESOLVED_ISSUE_SUFFIX, RTT_HISTOGRAM_BUCKET_WIDTH_IN_MS, RTT_HISTOGRAM_NUMBER_OF_BUCKETS, type RemoteInboundRtpStats, type RemoteOutboundRtpStats, type RemoteTrackLinkEvidence, RemoteTrackResolver, type RemoteTrackResolverFactory, type RemoteTrackResolverReportPayload, RemoteTrackResolverValidator, type RemoteTrackResolverValidatorConfig, type RemoteTrackResolvers, type ResolvedActiveClientIssue, type RttSummary, type RunningValidator, SCORE_HISTOGRAM_BUCKET_WIDTH, SCORE_HISTOGRAM_NUMBER_OF_BUCKETS, type SampleRejectedReason, type SaveClientSamplesConfig, type ScoreCalculator, type ScoreSummary, SfuCongestionDetector, type SfuCongestionDetectorBucket, type SfuCongestionDetectorConfig, type SfuCongestionDetectorEvaluation, type SfuCongestionDetectorReport, type SimulcastReceiverEvidence, type SimulcastReceiverReportPayload, SimulcastReceiverValidator, type SimulcastReceiverValidatorConfig, type Sink, type SinkConstructor, type SinkCreateSettings, type SinkDestination, type SinkEvents, SinkRegistry, type SinkSettings, SlidingWindow, type SlidingWindowEntry, type StatsSummary, TrackDeliveryMismatchDetector, type TrackDeliveryMismatchDetectorConfig, TrackDeliveryMismatchTypes, TrendTester, type TrendTesterConfig, type TurnServerHealth, TurnServerHealthDetector, type TurnServerHealthDetectorConfig, TurnServerHealthTypes, TurnServerOutageDetector, type TurnServerOutageDetectorConfig, TurnServerOutageTypes, UNRESOLVED_TRACK_LINKS_ISSUE, UnconsumedTrackDetector, type UnconsumedTrackDetectorConfig, UnconsumedTrackTypes, type ValidationReport, type Validator, type ValidatorName, baseIssueType, concludeCallIssue, concludeObserverIssue, correlation, counterDelta, createCallSummary, createDefaultMediasoupRemoteTrackResolverFactory, createInMemorySink, createJsonlFileSink, createLogger, createP2pRemoteTrackResolverFactory, defaultCallSummaryConfig, defaultClientHealthThresholds, geohash, isClientIssueResolutionEntry, isPublicIpAddress, issuePayloadAsString, mannKendall, mannKendallVerdict, median, medianAbsoluteDeviation, pageHinkley, percentile, percentileOfHistogram, percentileOfSorted, robustZScore, schemaVersion, setObserverLogger, summarize };
+export { type AcceptContext, type AcceptMiddleware, type AcceptMiddlewarePayload, type ActiveClientIssue, type ActiveIssueTracker, ActiveIssuesRegistry, AudioEchoDetector, type AudioEchoDetectorConfig, AudioEchoTypes, type AudioInputDevice, type AvailableCallScopeDetectorsConfigs, type AvailableDetectorsConfigs, type AvailableObserverScopeDetectorsConfigs, type AvailableValidatorConfigs, CODEC_MISMATCH_ISSUE, type CalculatedScore, type CallAppDataFactory, CallConcurrentIssueDetector, type CallConcurrentIssueDetectorConfig, type CallConcurrentIssueGroup, CallConcurrentIssueTypes, type CallHealth, CallHealthAggregator, type CallIssue, type CallIssueSpread, type CallScopedEventName, type CallSummary, type CallSummaryClients, CallSummaryCollector, type CallSummaryConfig, type CallSummaryEnricher, type CallSummaryEnrichers, type CallSummaryScores, type CallSummarySection, type CallSummaryTruncation, type CallSummaryTurnServers, type CertificateStats, type ClientAppDataFactory, type ClientEvent, ClientEventTypes, type ClientHealth, type ClientHealthThresholds, type ClientIssue, type ClientLocation, type ClientLocationResolver, type ClientMetaData, ClientMetaTypes, type ClientPopulation, type ClientPopulationAxis, ClientPopulationIssueDetector, type ClientPopulationIssueDetectorConfig, ClientPopulationIssueTypes, type ClientSample, type ClientSampleSink, type ClientSampleSinkEvents, type ClientSinkParams, type CodecConsistencyReportPayload, CodecConsistencyValidator, type CodecConsistencyValidatorConfig, type CodecEvidence, type CodecStats, type CorroboratedPublisherFault, type CreateExtensionStatsSettings, type DataChannelStats, type Detector, Detectors, type ExtensionStat, ExtensionStatsRegistry, GEOHASH_CELL_SIZES, type IceCandidatePairStats, type IceCandidateStats, type IceTransportStats, InMemorySink, type InboundRtpStats, type InboundTrackSample, type Issue, type IssueBase, type IssueConclusion, IssueFanOutDetector, type IssueFanOutDetectorConfig, IssueFanOutTypes, type IssueFaultDomain, JsonlFileSink, type JsonlFileSinkOptions, LOWEST_COMMON_DENOMINATOR_ISSUE, type Logger, type MannKendallResult, type MediaKind, type MediaPlayoutStats, type MediaSourceStats, type MediasoupConsumerSample, type MediasoupConsumerSampleEvent, type MediasoupDataConsumerSample, type MediasoupDataProducerSample, type MediasoupDirectTransportSample, type MediasoupDirectTransportSampleEventMap, type MediasoupPipeTransportSample, type MediasoupPipeTransportSampleEventMap, type MediasoupPlainTransportSample, type MediasoupPlainTransportSampleEventMap, type MediasoupProducerSample, type MediasoupProducerSampleEvent, type MediasoupRouterSample, type MediasoupSampleEnricher, type MediasoupTransportSample, type MediasoupWebRtcTransportSample, type MediasoupWebRtcTransportSampleEventMap, type Middleware, MiddlewareProcessor, ObservedCall, type ObservedCallScope, type ObservedCallSettings, ObservedCertificate, ObservedClient, ObservedClientIssueRegistry, type ObservedClientScope, type ObservedClientSettings, ObservedCodec, ObservedDataChannel, ObservedIceCandidate, ObservedIceCandidatePair, ObservedIceTransport, ObservedInboundRtp, ObservedInboundTrack, ObservedMediaPlayout, ObservedMediaSource, ObservedMediasoupRouter, type ObservedMediasoupRouterEvents, type ObservedMediasoupRouterScope, type ObservedMediasoupRouterSettings, ObservedOutboundRtp, ObservedOutboundTrack, ObservedPeerConnection, type ObservedPeerConnectionScope, ObservedPeerConnectionTransport, ObservedRemoteInboundRtp, ObservedRemoteOutboundRtp, ObservedTURN, type ObservedTURNEventMap, ObservedTurnServer, Observer, ObserverConcurrentIssueDetector, type ObserverConcurrentIssueDetectorConfig, type ObserverConcurrentIssueGroup, ObserverConcurrentIssueTypes, type ObserverEventBase, type ObserverEvents, type ObserverIssue, type ObserverIssueSpread, type ObserverLogger, type OutboundRtpStats, type OutboundTrackSample, type PageHinkleyResult, type PeerConnectionSample, type PeerConnectionTransportStats, type PsnrSum, PublisherFaultCorroborationDetector, type PublisherFaultCorroborationDetectorConfig, PublisherFaultTypes, type QualityLimitationDurations, RESOLVED_ISSUE_SUFFIX, RTT_HISTOGRAM_BUCKET_WIDTH_IN_MS, RTT_HISTOGRAM_NUMBER_OF_BUCKETS, type RemoteInboundRtpStats, type RemoteOutboundRtpStats, type RemoteTrackLinkEvidence, RemoteTrackResolver, type RemoteTrackResolverFactory, type RemoteTrackResolverReportPayload, RemoteTrackResolverValidator, type RemoteTrackResolverValidatorConfig, type RemoteTrackResolvers, type ResolvedActiveClientIssue, type RollingJsonlFileInfo, RollingJsonlFileSink, type RollingJsonlFileSinkEvents, type RollingJsonlFileSinkOptions, type RttSummary, type RunningValidator, SCORE_HISTOGRAM_BUCKET_WIDTH, SCORE_HISTOGRAM_NUMBER_OF_BUCKETS, type SampleRejectedReason, type SaveClientSamplesConfig, type ScoreCalculator, type ScoreSummary, SfuCongestionDetector, type SfuCongestionDetectorBucket, type SfuCongestionDetectorConfig, type SfuCongestionDetectorEvaluation, type SfuCongestionDetectorReport, type SimulcastReceiverEvidence, type SimulcastReceiverReportPayload, SimulcastReceiverValidator, type SimulcastReceiverValidatorConfig, type Sink, type SinkConstructor, type SinkCreateSettings, type SinkDestination, type SinkEvents, SinkRegistry, type SinkSettings, SlidingWindow, type SlidingWindowEntry, type StatsSummary, TrackDeliveryMismatchDetector, type TrackDeliveryMismatchDetectorConfig, TrackDeliveryMismatchTypes, TrendTester, type TrendTesterConfig, type TurnServerHealth, TurnServerHealthDetector, type TurnServerHealthDetectorConfig, TurnServerHealthTypes, TurnServerOutageDetector, type TurnServerOutageDetectorConfig, TurnServerOutageTypes, UNRESOLVED_TRACK_LINKS_ISSUE, UnconsumedTrackDetector, type UnconsumedTrackDetectorConfig, UnconsumedTrackTypes, type ValidationReport, type Validator, type ValidatorName, baseIssueType, concludeCallIssue, concludeObserverIssue, correlation, counterDelta, createCallSummary, createDefaultMediasoupRemoteTrackResolverFactory, createInMemorySink, createJsonlFileSink, createLogger, createP2pRemoteTrackResolverFactory, defaultCallSummaryConfig, defaultClientHealthThresholds, geohash, isClientIssueResolutionEntry, isPublicIpAddress, issuePayloadAsString, mannKendall, mannKendallVerdict, median, medianAbsoluteDeviation, pageHinkley, percentile, percentileOfHistogram, percentileOfSorted, robustZScore, schemaVersion, setObserverLogger, summarize };

package/dist/index.d.ts

@@ -7236,6 +7236,74 @@ declare class JsonlFileSink<T = ClientSample> extends EventEmitter implements Si
 /** Build a JSONL file sink for a single path. */
 declare function createJsonlFileSink<T = ClientSample>(options: JsonlFileSinkOptions<T>): JsonlFileSink<T>;
 
+/** The file a `RollingJsonlFileSink` is about to open: the sequence number and when it opens. */
+type RollingJsonlFileInfo = {
+    /** 0 for the first file, then 1, 2, … */
+    index: number;
+    /** `Date.now()` when the file is opened. */
+    openedAt: number;
+};
+type RollingJsonlFileSinkOptions<T = unknown> = Partial<SinkSettings> & {
+    /** The path of each file, called when it is opened. Must give a new path per `index`. */
+    path: (file: RollingJsonlFileInfo) => string;
+    /** Roll before a write that would make the current file larger than this, in bytes. */
+    maxBytes?: number;
+    /** Roll before a write once the current file has been open for this long, in ms. */
+    maxAgeMs?: number;
+    /** Optional custom serializer; defaults to `JSON.stringify`. */
+    serializeSample?: (record: T) => string;
+};
+type RollingJsonlFileSinkEvents = {
+    ended: SinkEvents['ended'];
+    close: SinkEvents['close'];
+    error: SinkEvents['error'];
+    finish: SinkEvents['finish'];
+    drain: SinkEvents['drain'];
+    /** A file is complete: flushed and its descriptor closed. Fires for every file, the last one included. */
+    'file-closed': [path: string, index: number];
+};
+declare interface RollingJsonlFileSink {
+    on<E extends keyof RollingJsonlFileSinkEvents>(event: E, listener: (...args: RollingJsonlFileSinkEvents[E]) => void): this;
+    once<E extends keyof RollingJsonlFileSinkEvents>(event: E, listener: (...args: RollingJsonlFileSinkEvents[E]) => void): this;
+    off<E extends keyof RollingJsonlFileSinkEvents>(event: E, listener: (...args: RollingJsonlFileSinkEvents[E]) => void): this;
+    emit<E extends keyof RollingJsonlFileSinkEvents>(event: E, ...args: RollingJsonlFileSinkEvents[E]): boolean;
+}
+/**
+ * A JSONL file sink for long-lived owners (e.g. an observer's extension stats over days): it writes
+ * to a sequence of files, closing the current one and opening the next — *rolling* — when it would
+ * exceed `maxBytes`, when it has been open for `maxAgeMs`, or when `roll()` is called. Nothing is
+ * dropped: each record goes to exactly one file.
+ *
+ * The limits are checked on `write`, so a file is never rolled while nothing is written to it, and
+ * an empty file is never rolled. `file-closed` announces each finished file (ready to upload or
+ * move), in index order; `close` fires once, after every file is closed by `end()`.
+ */
+declare class RollingJsonlFileSink<T = unknown> extends EventEmitter implements Sink<T> {
+    readonly id: string;
+    private readonly _options;
+    private readonly _serializeSample;
+    private _stream;
+    private _path;
+    private _index;
+    private _openedAt;
+    private _bytes;
+    private _ended;
+    private _closing;
+    constructor(options: RollingJsonlFileSinkOptions<T>);
+    /** The file currently written to. */
+    get path(): string;
+    /** The index of the file currently written to. */
+    get index(): number;
+    get ended(): boolean;
+    write(record: T): boolean;
+    /** Close the current file and continue in a new one. A no-op on an empty file or an ended sink. */
+    roll(): void;
+    /** No more writes: emits `ended`, closes the current file (`file-closed`), then emits `close`. */
+    end(): void;
+    private _open;
+    private _closeCurrent;
+}
+
 declare interface InMemorySink {
     on<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
     once<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
@@ -7262,4 +7330,4 @@ declare function createInMemorySink(samples?: ClientSample[]): InMemorySink;
 declare function createDefaultMediasoupRemoteTrackResolverFactory(): RemoteTrackResolverFactory;
 declare function createP2pRemoteTrackResolverFactory(): RemoteTrackResolverFactory;
 
-export { type AcceptContext, type AcceptMiddleware, type AcceptMiddlewarePayload, type ActiveClientIssue, type ActiveIssueTracker, ActiveIssuesRegistry, AudioEchoDetector, type AudioEchoDetectorConfig, AudioEchoTypes, type AudioInputDevice, type AvailableCallScopeDetectorsConfigs, type AvailableDetectorsConfigs, type AvailableObserverScopeDetectorsConfigs, type AvailableValidatorConfigs, CODEC_MISMATCH_ISSUE, type CalculatedScore, type CallAppDataFactory, CallConcurrentIssueDetector, type CallConcurrentIssueDetectorConfig, type CallConcurrentIssueGroup, CallConcurrentIssueTypes, type CallHealth, CallHealthAggregator, type CallIssue, type CallIssueSpread, type CallScopedEventName, type CallSummary, type CallSummaryClients, CallSummaryCollector, type CallSummaryConfig, type CallSummaryEnricher, type CallSummaryEnrichers, type CallSummaryScores, type CallSummarySection, type CallSummaryTruncation, type CallSummaryTurnServers, type CertificateStats, type ClientAppDataFactory, type ClientEvent, ClientEventTypes, type ClientHealth, type ClientHealthThresholds, type ClientIssue, type ClientLocation, type ClientLocationResolver, type ClientMetaData, ClientMetaTypes, type ClientPopulation, type ClientPopulationAxis, ClientPopulationIssueDetector, type ClientPopulationIssueDetectorConfig, ClientPopulationIssueTypes, type ClientSample, type ClientSampleSink, type ClientSampleSinkEvents, type ClientSinkParams, type CodecConsistencyReportPayload, CodecConsistencyValidator, type CodecConsistencyValidatorConfig, type CodecEvidence, type CodecStats, type CorroboratedPublisherFault, type CreateExtensionStatsSettings, type DataChannelStats, type Detector, Detectors, type ExtensionStat, ExtensionStatsRegistry, GEOHASH_CELL_SIZES, type IceCandidatePairStats, type IceCandidateStats, type IceTransportStats, InMemorySink, type InboundRtpStats, type InboundTrackSample, type Issue, type IssueBase, type IssueConclusion, IssueFanOutDetector, type IssueFanOutDetectorConfig, IssueFanOutTypes, type IssueFaultDomain, JsonlFileSink, type JsonlFileSinkOptions, LOWEST_COMMON_DENOMINATOR_ISSUE, type Logger, type MannKendallResult, type MediaKind, type MediaPlayoutStats, type MediaSourceStats, type MediasoupConsumerSample, type MediasoupConsumerSampleEvent, type MediasoupDataConsumerSample, type MediasoupDataProducerSample, type MediasoupDirectTransportSample, type MediasoupDirectTransportSampleEventMap, type MediasoupPipeTransportSample, type MediasoupPipeTransportSampleEventMap, type MediasoupPlainTransportSample, type MediasoupPlainTransportSampleEventMap, type MediasoupProducerSample, type MediasoupProducerSampleEvent, type MediasoupRouterSample, type MediasoupSampleEnricher, type MediasoupTransportSample, type MediasoupWebRtcTransportSample, type MediasoupWebRtcTransportSampleEventMap, type Middleware, MiddlewareProcessor, ObservedCall, type ObservedCallScope, type ObservedCallSettings, ObservedCertificate, ObservedClient, ObservedClientIssueRegistry, type ObservedClientScope, type ObservedClientSettings, ObservedCodec, ObservedDataChannel, ObservedIceCandidate, ObservedIceCandidatePair, ObservedIceTransport, ObservedInboundRtp, ObservedInboundTrack, ObservedMediaPlayout, ObservedMediaSource, ObservedMediasoupRouter, type ObservedMediasoupRouterEvents, type ObservedMediasoupRouterScope, type ObservedMediasoupRouterSettings, ObservedOutboundRtp, ObservedOutboundTrack, ObservedPeerConnection, type ObservedPeerConnectionScope, ObservedPeerConnectionTransport, ObservedRemoteInboundRtp, ObservedRemoteOutboundRtp, ObservedTURN, type ObservedTURNEventMap, ObservedTurnServer, Observer, ObserverConcurrentIssueDetector, type ObserverConcurrentIssueDetectorConfig, type ObserverConcurrentIssueGroup, ObserverConcurrentIssueTypes, type ObserverEventBase, type ObserverEvents, type ObserverIssue, type ObserverIssueSpread, type ObserverLogger, type OutboundRtpStats, type OutboundTrackSample, type PageHinkleyResult, type PeerConnectionSample, type PeerConnectionTransportStats, type PsnrSum, PublisherFaultCorroborationDetector, type PublisherFaultCorroborationDetectorConfig, PublisherFaultTypes, type QualityLimitationDurations, RESOLVED_ISSUE_SUFFIX, RTT_HISTOGRAM_BUCKET_WIDTH_IN_MS, RTT_HISTOGRAM_NUMBER_OF_BUCKETS, type RemoteInboundRtpStats, type RemoteOutboundRtpStats, type RemoteTrackLinkEvidence, RemoteTrackResolver, type RemoteTrackResolverFactory, type RemoteTrackResolverReportPayload, RemoteTrackResolverValidator, type RemoteTrackResolverValidatorConfig, type RemoteTrackResolvers, type ResolvedActiveClientIssue, type RttSummary, type RunningValidator, SCORE_HISTOGRAM_BUCKET_WIDTH, SCORE_HISTOGRAM_NUMBER_OF_BUCKETS, type SampleRejectedReason, type SaveClientSamplesConfig, type ScoreCalculator, type ScoreSummary, SfuCongestionDetector, type SfuCongestionDetectorBucket, type SfuCongestionDetectorConfig, type SfuCongestionDetectorEvaluation, type SfuCongestionDetectorReport, type SimulcastReceiverEvidence, type SimulcastReceiverReportPayload, SimulcastReceiverValidator, type SimulcastReceiverValidatorConfig, type Sink, type SinkConstructor, type SinkCreateSettings, type SinkDestination, type SinkEvents, SinkRegistry, type SinkSettings, SlidingWindow, type SlidingWindowEntry, type StatsSummary, TrackDeliveryMismatchDetector, type TrackDeliveryMismatchDetectorConfig, TrackDeliveryMismatchTypes, TrendTester, type TrendTesterConfig, type TurnServerHealth, TurnServerHealthDetector, type TurnServerHealthDetectorConfig, TurnServerHealthTypes, TurnServerOutageDetector, type TurnServerOutageDetectorConfig, TurnServerOutageTypes, UNRESOLVED_TRACK_LINKS_ISSUE, UnconsumedTrackDetector, type UnconsumedTrackDetectorConfig, UnconsumedTrackTypes, type ValidationReport, type Validator, type ValidatorName, baseIssueType, concludeCallIssue, concludeObserverIssue, correlation, counterDelta, createCallSummary, createDefaultMediasoupRemoteTrackResolverFactory, createInMemorySink, createJsonlFileSink, createLogger, createP2pRemoteTrackResolverFactory, defaultCallSummaryConfig, defaultClientHealthThresholds, geohash, isClientIssueResolutionEntry, isPublicIpAddress, issuePayloadAsString, mannKendall, mannKendallVerdict, median, medianAbsoluteDeviation, pageHinkley, percentile, percentileOfHistogram, percentileOfSorted, robustZScore, schemaVersion, setObserverLogger, summarize };
+export { type AcceptContext, type AcceptMiddleware, type AcceptMiddlewarePayload, type ActiveClientIssue, type ActiveIssueTracker, ActiveIssuesRegistry, AudioEchoDetector, type AudioEchoDetectorConfig, AudioEchoTypes, type AudioInputDevice, type AvailableCallScopeDetectorsConfigs, type AvailableDetectorsConfigs, type AvailableObserverScopeDetectorsConfigs, type AvailableValidatorConfigs, CODEC_MISMATCH_ISSUE, type CalculatedScore, type CallAppDataFactory, CallConcurrentIssueDetector, type CallConcurrentIssueDetectorConfig, type CallConcurrentIssueGroup, CallConcurrentIssueTypes, type CallHealth, CallHealthAggregator, type CallIssue, type CallIssueSpread, type CallScopedEventName, type CallSummary, type CallSummaryClients, CallSummaryCollector, type CallSummaryConfig, type CallSummaryEnricher, type CallSummaryEnrichers, type CallSummaryScores, type CallSummarySection, type CallSummaryTruncation, type CallSummaryTurnServers, type CertificateStats, type ClientAppDataFactory, type ClientEvent, ClientEventTypes, type ClientHealth, type ClientHealthThresholds, type ClientIssue, type ClientLocation, type ClientLocationResolver, type ClientMetaData, ClientMetaTypes, type ClientPopulation, type ClientPopulationAxis, ClientPopulationIssueDetector, type ClientPopulationIssueDetectorConfig, ClientPopulationIssueTypes, type ClientSample, type ClientSampleSink, type ClientSampleSinkEvents, type ClientSinkParams, type CodecConsistencyReportPayload, CodecConsistencyValidator, type CodecConsistencyValidatorConfig, type CodecEvidence, type CodecStats, type CorroboratedPublisherFault, type CreateExtensionStatsSettings, type DataChannelStats, type Detector, Detectors, type ExtensionStat, ExtensionStatsRegistry, GEOHASH_CELL_SIZES, type IceCandidatePairStats, type IceCandidateStats, type IceTransportStats, InMemorySink, type InboundRtpStats, type InboundTrackSample, type Issue, type IssueBase, type IssueConclusion, IssueFanOutDetector, type IssueFanOutDetectorConfig, IssueFanOutTypes, type IssueFaultDomain, JsonlFileSink, type JsonlFileSinkOptions, LOWEST_COMMON_DENOMINATOR_ISSUE, type Logger, type MannKendallResult, type MediaKind, type MediaPlayoutStats, type MediaSourceStats, type MediasoupConsumerSample, type MediasoupConsumerSampleEvent, type MediasoupDataConsumerSample, type MediasoupDataProducerSample, type MediasoupDirectTransportSample, type MediasoupDirectTransportSampleEventMap, type MediasoupPipeTransportSample, type MediasoupPipeTransportSampleEventMap, type MediasoupPlainTransportSample, type MediasoupPlainTransportSampleEventMap, type MediasoupProducerSample, type MediasoupProducerSampleEvent, type MediasoupRouterSample, type MediasoupSampleEnricher, type MediasoupTransportSample, type MediasoupWebRtcTransportSample, type MediasoupWebRtcTransportSampleEventMap, type Middleware, MiddlewareProcessor, ObservedCall, type ObservedCallScope, type ObservedCallSettings, ObservedCertificate, ObservedClient, ObservedClientIssueRegistry, type ObservedClientScope, type ObservedClientSettings, ObservedCodec, ObservedDataChannel, ObservedIceCandidate, ObservedIceCandidatePair, ObservedIceTransport, ObservedInboundRtp, ObservedInboundTrack, ObservedMediaPlayout, ObservedMediaSource, ObservedMediasoupRouter, type ObservedMediasoupRouterEvents, type ObservedMediasoupRouterScope, type ObservedMediasoupRouterSettings, ObservedOutboundRtp, ObservedOutboundTrack, ObservedPeerConnection, type ObservedPeerConnectionScope, ObservedPeerConnectionTransport, ObservedRemoteInboundRtp, ObservedRemoteOutboundRtp, ObservedTURN, type ObservedTURNEventMap, ObservedTurnServer, Observer, ObserverConcurrentIssueDetector, type ObserverConcurrentIssueDetectorConfig, type ObserverConcurrentIssueGroup, ObserverConcurrentIssueTypes, type ObserverEventBase, type ObserverEvents, type ObserverIssue, type ObserverIssueSpread, type ObserverLogger, type OutboundRtpStats, type OutboundTrackSample, type PageHinkleyResult, type PeerConnectionSample, type PeerConnectionTransportStats, type PsnrSum, PublisherFaultCorroborationDetector, type PublisherFaultCorroborationDetectorConfig, PublisherFaultTypes, type QualityLimitationDurations, RESOLVED_ISSUE_SUFFIX, RTT_HISTOGRAM_BUCKET_WIDTH_IN_MS, RTT_HISTOGRAM_NUMBER_OF_BUCKETS, type RemoteInboundRtpStats, type RemoteOutboundRtpStats, type RemoteTrackLinkEvidence, RemoteTrackResolver, type RemoteTrackResolverFactory, type RemoteTrackResolverReportPayload, RemoteTrackResolverValidator, type RemoteTrackResolverValidatorConfig, type RemoteTrackResolvers, type ResolvedActiveClientIssue, type RollingJsonlFileInfo, RollingJsonlFileSink, type RollingJsonlFileSinkEvents, type RollingJsonlFileSinkOptions, type RttSummary, type RunningValidator, SCORE_HISTOGRAM_BUCKET_WIDTH, SCORE_HISTOGRAM_NUMBER_OF_BUCKETS, type SampleRejectedReason, type SaveClientSamplesConfig, type ScoreCalculator, type ScoreSummary, SfuCongestionDetector, type SfuCongestionDetectorBucket, type SfuCongestionDetectorConfig, type SfuCongestionDetectorEvaluation, type SfuCongestionDetectorReport, type SimulcastReceiverEvidence, type SimulcastReceiverReportPayload, SimulcastReceiverValidator, type SimulcastReceiverValidatorConfig, type Sink, type SinkConstructor, type SinkCreateSettings, type SinkDestination, type SinkEvents, SinkRegistry, type SinkSettings, SlidingWindow, type SlidingWindowEntry, type StatsSummary, TrackDeliveryMismatchDetector, type TrackDeliveryMismatchDetectorConfig, TrackDeliveryMismatchTypes, TrendTester, type TrendTesterConfig, type TurnServerHealth, TurnServerHealthDetector, type TurnServerHealthDetectorConfig, TurnServerHealthTypes, TurnServerOutageDetector, type TurnServerOutageDetectorConfig, TurnServerOutageTypes, UNRESOLVED_TRACK_LINKS_ISSUE, UnconsumedTrackDetector, type UnconsumedTrackDetectorConfig, UnconsumedTrackTypes, type ValidationReport, type Validator, type ValidatorName, baseIssueType, concludeCallIssue, concludeObserverIssue, correlation, counterDelta, createCallSummary, createDefaultMediasoupRemoteTrackResolverFactory, createInMemorySink, createJsonlFileSink, createLogger, createP2pRemoteTrackResolverFactory, defaultCallSummaryConfig, defaultClientHealthThresholds, geohash, isClientIssueResolutionEntry, isPublicIpAddress, issuePayloadAsString, mannKendall, mannKendallVerdict, median, medianAbsoluteDeviation, pageHinkley, percentile, percentileOfHistogram, percentileOfSorted, robustZScore, schemaVersion, setObserverLogger, summarize };

package/dist/index.js

@@ -84,6 +84,7 @@ __export(src_exports, {
   RTT_HISTOGRAM_NUMBER_OF_BUCKETS: () => RTT_HISTOGRAM_NUMBER_OF_BUCKETS,
   RemoteTrackResolver: () => RemoteTrackResolver,
   RemoteTrackResolverValidator: () => RemoteTrackResolverValidator,
+  RollingJsonlFileSink: () => RollingJsonlFileSink,
   SCORE_HISTOGRAM_BUCKET_WIDTH: () => SCORE_HISTOGRAM_BUCKET_WIDTH,
   SCORE_HISTOGRAM_NUMBER_OF_BUCKETS: () => SCORE_HISTOGRAM_NUMBER_OF_BUCKETS,
   SfuCongestionDetector: () => SfuCongestionDetector,
@@ -8119,9 +8120,96 @@ var TrendTester = class {
   }
 };
 
-// src/sinks/InMemorySink.ts
+// src/sinks/RollingJsonlFileSink.ts
+var fs2 = __toESM(require("fs"));
 var import_node_events8 = require("events");
-var InMemorySink = class extends import_node_events8.EventEmitter {
+var RollingJsonlFileSink = class extends import_node_events8.EventEmitter {
+  id;
+  _options;
+  _serializeSample;
+  _stream;
+  _path;
+  _index = -1;
+  _openedAt = 0;
+  _bytes = 0;
+  _ended = false;
+  // Resolves once every file closed so far has closed and been announced, in index order: the
+  // streams close independently, so a later file could otherwise be announced before an earlier one.
+  _closing = Promise.resolve();
+  constructor(options) {
+    super();
+    this._options = options;
+    this._serializeSample = options.serializeSample ?? ((record) => JSON.stringify(record));
+    this._open();
+    this.id = options.id ?? this._path;
+  }
+  /** The file currently written to. */
+  get path() {
+    return this._path;
+  }
+  /** The index of the file currently written to. */
+  get index() {
+    return this._index;
+  }
+  get ended() {
+    return this._ended;
+  }
+  write(record) {
+    if (this._ended) return false;
+    const line = `${this._serializeSample(record)}
+`;
+    const bytes = Buffer.byteLength(line);
+    const { maxBytes, maxAgeMs } = this._options;
+    if (maxAgeMs !== void 0 && maxAgeMs <= Date.now() - this._openedAt) this.roll();
+    if (maxBytes !== void 0 && maxBytes < this._bytes + bytes) this.roll();
+    this._bytes += bytes;
+    return this._stream.write(line);
+  }
+  /** Close the current file and continue in a new one. A no-op on an empty file or an ended sink. */
+  roll() {
+    if (this._ended || this._bytes === 0) return;
+    this._closeCurrent();
+    this._open();
+  }
+  /** No more writes: emits `ended`, closes the current file (`file-closed`), then emits `close`. */
+  end() {
+    if (this._ended) return;
+    this._ended = true;
+    this.emit("ended");
+    this._closeCurrent();
+    void this._closing.then(() => {
+      this.emit("finish");
+      this.emit("close");
+    });
+  }
+  _open() {
+    ++this._index;
+    this._openedAt = Date.now();
+    this._bytes = 0;
+    this._path = this._options.path({ index: this._index, openedAt: this._openedAt });
+    const stream = fs2.createWriteStream(this._path, { flags: "a" });
+    stream.on("drain", () => this.emit("drain"));
+    stream.on("error", (err) => this.emit("error", err));
+    this._stream = stream;
+  }
+  _closeCurrent() {
+    const stream = this._stream;
+    const path = this._path;
+    const index = this._index;
+    const closed = new Promise((resolve) => {
+      stream.once("close", () => resolve());
+      stream.once("error", () => resolve());
+    });
+    this._closing = Promise.all([this._closing, closed]).then(() => {
+      this.emit("file-closed", path, index);
+    });
+    stream.end();
+  }
+};
+
+// src/sinks/InMemorySink.ts
+var import_node_events9 = require("events");
+var InMemorySink = class extends import_node_events9.EventEmitter {
   id;
   samples;
   _ended = false;
@@ -8382,6 +8470,7 @@ function createP2pRemoteTrackResolverFactory() {
   RTT_HISTOGRAM_NUMBER_OF_BUCKETS,
   RemoteTrackResolver,
   RemoteTrackResolverValidator,
+  RollingJsonlFileSink,
   SCORE_HISTOGRAM_BUCKET_WIDTH,
   SCORE_HISTOGRAM_NUMBER_OF_BUCKETS,
   SfuCongestionDetector,