datadog-ux-utils/dist/telemetry/runtime/componentTelemetry.d.ts

Datadog RUM focused UX & performance toolkit: API guards (retry, breaker, rate), React telemetry (error boundary, profiler, Suspense), web vitals & resource observers, offline queues.

/**
 * @file componentTelemetry.ts
 * @description Runtime component telemetry instrumentation for sampled mount events and UX component adoption tracking.
 */
/** Configuration for runtime component telemetry (subset; extended externally if needed). */
/** @category Telemetry */
export interface ComponentTelemetryConfig {
    /**
     * Fraction (0..1) of mount events to sample.
     * @default 0.25
     */
    sampleRate?: number;
    /**
     * Flush interval (ms) for queued events.
     * Set to 0 to disable interval flushing (still flushes on threshold / visibility hidden).
     * @default 5000
     */
    flushIntervalMs?: number;
    /**
     * By default events are suppressed when `env === "dev"` to avoid local noise.
     * Set `allowInDev` true to always record.
     * @default false
     */
    allowInDev?: boolean;
    /**
     * Optional custom sink callback.
     * If provided each flush will pass a batch array; returning void.
     * When present the internal Datadog `addAction` forwarding is skipped.
     */
    sink?: (batch: ComponentMountEvent[]) => void;
}
/** Shape recorded for each component mount (only first mount per component instance). */
/** @category Telemetry */
export interface ComponentMountEvent {
    /** Event type discriminator */
    t: "component_mount";
    /** Epoch timestamp (ms) when component mounted */
    ts: number;
    /** Component name identifier (keep stable across versions) */
    component: string;
    /** Library version pulled from `getUxConfig().version` */
    libVersion: string;
    /** Current route / pathname (best effort) */
    route?: string;
    /** Optional variant (e.g. size, theme) for A/B style analysis */
    variant?: string;
    /** App name from config */
    app?: string;
    /** Environment from config */
    env?: string;
}
/**
 * Initialize component runtime telemetry (idempotent).
 *
 * Call once during app bootstrap (after `initDatadogUx`).
 * Skips activation in `dev` unless `allowInDev` true.
 *
 * Example:
 * ```ts
 * import { initDatadogUx } from 'datadog-ux-utils';
 * import { initComponentTelemetry } from 'datadog-ux-utils/telemetry';
 *
 * initDatadogUx({ appName: 'Shop', actionSampleRate: 50 });
 * initComponentTelemetry({ sampleRate: 0.2 });
 * ```
 */
/** @category Telemetry */
export declare function initComponentTelemetry(config?: ComponentTelemetryConfig): void;
/**
 * Report a component mount.
 * Usually invoked automatically via the `useComponentTelemetry` React hook.
 * Safe no-op if not initialized or sampled out.
 *
 * Example (manual call):
 * ```ts
 * reportComponentMount('Button', { variant: 'primary', route: '/checkout' });
 * ```
 */
/** @category Telemetry */
export declare function reportComponentMount(component: string, options?: {
    variant?: string;
    route?: string;
    force?: boolean;
}): void;
/**
 * Flush queued events to the configured sink immediately.
 * Automatically invoked on size threshold, interval, and page hide.
 */
/** @category Telemetry */
export declare function flush(useBeacon?: boolean): void;
/**
 * Test helper: reset internal state & timers.
 * Not part of the public API (subject to change).
 */
/** @category Telemetry */
export declare function _resetComponentTelemetry(): void;
//# sourceMappingURL=componentTelemetry.d.ts.map