@microsoft/dev-tunnels-ssh/metrics/sessionContour.d.ts

SSH library for Dev Tunnels

import { CancellationToken, Disposable } from 'vscode-jsonrpc';
import { SessionMetrics } from './sessionMetrics';
/**
 * Collects session metrics over time, producing an outline of the timing, speed,
 * and quantity of bytes sent/received during the session.
 *
 * Metrics are recorded across a number of equal time intervals. As the session time
 * increases, intervals are expanded to keep the number of intervals under the configured
 * maximum. Each expansion doubles the length of all intervals, while combining the metrics
 * within each pair of combined intervals. Therefore, a longer session has longer intervals
 * and less-granular metrics. In this way, the memory usage (and serialized size) of the
 * session contour remains roughly constant regardless of the length of the session.
 *
 * Metrics exposed via the collection properties on this class may be momentarily
 * inconsistent (but will not throw exceptions) if continued session operation causes
 * intervals to be expanded while the data is being read concurrently. To avoid any
 * inconsistency, hold a lock on the <see cref="SessionContour" /> instance while reading
 * data. (Or wait until the session ends.)
 *
 * A session contour can be exported in a compact form suitable for logging or telemetry.
 * Use the code in `SessionContour.kql` to chart a session contour in Azure Data Explorer.
 */
export declare class SessionContour implements Disposable {
    private static readonly initialInterval;
    /** Current size of the metrics interval, in milliseconds. */
    private intervalMs;
    /** Number of intervals for which metrics have been recorded. */
    private count;
    private readonly intervalBytesSent;
    private readonly intervalBytesReceived;
    private readonly intervalLatencyMin;
    private readonly intervalLatencyMax;
    private readonly intervalLatencySum;
    private readonly intervalLatencyCount;
    private readonly intervalLatencyAvg;
    private readonly updateQueue;
    private readonly updateSemaphore;
    private disposed;
    /**
     * Creates a new instance of the `SessionContour` class.
     *
     * @param maxIntervals Maximum number of metric intervals to record,
     * defaults to 256. Must be a power of two.
     */
    constructor(maxIntervals?: number);
    /**
     * Gets the maximum number of intervals that can be recorded in this contour. Intervals
     * are expanded as necesary such that the entire duration of the session is always covered
     * by fewer intervals than this limit.
     */
    readonly maxIntervals: number;
    /**
     * Gets the current number of contour intervals with recorded metrics. This is always
     * less than `maxIntervals`.
     */
    get intervalCount(): number;
    /**
     * Gets the current time span of each contour interval, in milliseconds. This interval time
     * span is doubled as necesary such that the entire duration of the session is always covered
     * by fewer intervals than the maximum.
     */
    get interval(): number;
    /**
     * Gets the total number of bytes sent for each interval during the session,
     * including all channels and non-channel protocol messages, and including message
     * framing, padding, and MAC bytes. The number of values is equal to `intervalCount`.
     */
    get bytesSent(): readonly number[];
    /**
     * Gets the total number of bytes received for each interval during the session,
     * including all channels and non-channel protocol messages, and including message
     * framing, padding, and MAC bytes. The number of values is equal to `intervalCount`.
     */
    get bytesReceived(): readonly number[];
    /**
     * Gets the minimum recorded round-trip connection latency between client and server for
     * each interval during the session. The number of values is equal to `intervalCount`.
     */
    get latencyMinMs(): readonly number[];
    /**
     * Gets the maximum recorded round-trip connection latency between client and server for
     * each interval during the session. The number of values is equal to `intervalCount`.
     */
    get latencyMaxMs(): readonly number[];
    /**
     * Gets the average recorded round-trip connection latency between client and server for
     * each interval during the session. The number of values is equal to `intervalCount`.
     */
    get latencyAverageMs(): readonly number[];
    private onMessageSent;
    private onMessageReceived;
    private onLatencyUpdated;
    private onSessionClosed;
    /**
     * Starts collecting session metrics, and processes the metrics in a backgroud loop until
     * cancelled or until the session is closed or the `SessionContour` instance is disposed.
     */
    collectMetrics(sessionMetrics: SessionMetrics, cancellation?: CancellationToken): Promise<void>;
    private updateInterval;
    private expandIntervals;
    dispose(): void;
    /**
     * Serializes the session contour into a compact form suitable for recording in
     * logs or telemetry.
     *
     * This compact serialization format uses one byte per metric per interval, so there is
     * some loss of precision, but generally not so much that it affects a visualization. A
     * scale factor for each metric is automatically determined and included in the serialized
     * header. The size of the serialized encoded data will be a little under 7 bytes per
     * interval. With the default interval maximum (256), that comes out to less than 1.75 KB.
     *
     * Use the code in `SessionContour.kql` to decode and chart this output in
     * Azure Data Explorer.
     */
    export(): string;
    /**
     * Deserializes a session contour that was previously exported.
     *
     * Due to loss in precision, some values in the deserialized contour will not exactly match
     * the original, but they will be close.
     */
    static import(contourBase64: string): SessionContour;
}
//# sourceMappingURL=sessionContour.d.ts.map