aws-cdk/lib/cli/telemetry/session.d.ts

AWS CDK CLI, the command line tool for CDK apps

import { type EventType, type ErrorDetails } from './schema';
import type { ITelemetrySink } from './sink/sink-interface';
import type { Context } from '../../api/context';
import type { IMessageSpan } from '../../api-private';
import type { CliIoHost } from '../io-host/cli-io-host';
import type { EventResult } from '../telemetry/messages';
export interface TelemetrySessionProps {
    readonly ioHost: CliIoHost;
    readonly client: ITelemetrySink;
    readonly arguments: any;
    readonly context: Context;
}
export interface TelemetryEvent {
    readonly eventType: EventType;
    readonly duration: number;
    readonly error?: ErrorDetails;
    readonly counters?: Record<string, number>;
}
/**
 * Timer of a single event
 */
export interface Timing {
    /**
     * Total time spent in this operation
     */
    totalMs: number;
    /**
     * Count of operations that together took `totalMs`.
     */
    count: number;
}
export declare class TelemetrySession {
    private readonly props;
    private ioHost;
    private client;
    private _sessionInfo?;
    private _commandSpan?;
    private _nextEventCounters?;
    private count;
    private loadTime?;
    constructor(props: TelemetrySessionProps);
    /**
     * The span that represents the CLI invocation.
     *
     * In the code, this span is named COMMAND but the matching event type
     * in telemetry will be INVOKE.
     *
     * Will be emitted exactly once, at the end of the CLI operation.
     */
    get commandSpan(): IMessageSpan<EventResult> | undefined;
    begin(): Promise<void>;
    attachRegion(region: string): Promise<void>;
    /**
     * Attach a language guess
     */
    attachLanguage(language: string | undefined): void;
    /**
     * Attach our best guess at running under an agent or not
     */
    attachAgent(isAgent: boolean | undefined): void;
    /**
     * Temporarily attach counters for the next event operation.
     *
     * They may be committed to the sent telemetry later.
     */
    attachCountersToNextEvent(counters: Record<string, number>): void;
    /**
     * Set the load time (will be emitted with the COMMAND span)
     */
    attachLoadTime(loadTime: number): void;
    /**
     * Mark when the actual CLI operation starts
     *
     * Emitted as part of the COMMAND span.
     */
    markOperationStart(): void;
    /**
     * Attach the CDK library version
     *
     * By default the telemetry will guess at the CDK library version if it so
     * happens that the CDK project is an NPM project and the CDK CLI is executed
     * in the root of NPM project with `aws-cdk-lib` available in `node_modules`.
     * This may succeed or may fail.
     *
     * Once we have produced and loaded the cloud assembly more accurate
     * information becomes available that we can add in.
     */
    attachCdkLibVersion(libVersion: string): void;
    /**
     * When the command is complete, so is the CliIoHost. Ends the span of the entire CliIoHost
     * and notifies with an optional error message in the data.
     */
    end(error?: ErrorDetails): Promise<void>;
    emit(event: TelemetryEvent): Promise<void>;
    /**
     * This is a DEPLOY event, track some additional statistics about it
     *
     * We use this to measure things about deployment failures, such as the number of
     * failed DEPLOY events in a sequence.
     */
    private trackDeployStatistics;
    private get sessionInfo();
}
/**
 * Validates that the CDK_CLI_USERAGENT env var value matches
 * the expected format: `<name>/<version>/<mode>` where name is one of
 * VALID_USER_AGENTS and mode is either `sandbox` or `production`.
 */
export declare function isValidWrapperUserAgent(value: string | undefined): value is string;