Luxar Viewer API Documentation - v2026.9.22
    Preparing search index...

    Interface CacheMetrics

    Cache metrics for detailed analytics

    interface CacheMetrics {
        totalCacheMemory: number;
        memoryLimit: number;
        memoryPercent: number;
        totalEntries: number;
        effectiveDemandHitRate?: number;
        avgAccessTime: number;
        queriesPerSec: number;
        loadsPerSec: number;
        bandwidth: number;
        l1?: {
            size: number;
            count: number;
            hits: number;
            misses: number;
            evictions: number;
        };
        l2?: {
            size: number;
            count: number;
            reads: number;
            writes: number;
            misses: number;
            canceledReads?: number;
            activeReads?: number;
            queuedReads?: number;
            quotaWriteSkipped?: number;
            writeFailures?: number;
            corruptedEntries?: number;
            metadataParseFailures?: number;
        };
        l0?: {
            size: number;
            count: number;
            hits: number;
            misses: number;
            evictions: number;
            hitRate: number;
            maxSize?: number;
        };
        slice?: {
            size: number;
            count: number;
            hits: number;
            misses: number;
            evictions: number;
            hitRate: number;
            thrashMisses?: number;
            maxSize?: number;
            fullLadderCount?: number;
            ladderDepthHistogram?: Record<string, number>;
        };
        enabled?: boolean;
        telemetryState?: CacheTelemetryState;
        network?: {
            bytesTransferred: number;
            requestCount: number;
            bandwidth: number;
            totalBytesServed?: number;
            totalRequestsServed?: number;
        };
        status?: CacheStatusBadge[];
        health?: {
            validationMode?: CacheValidationMode;
            lastValidatedAt?: number
            | null;
            unvalidatedExternalDataset?: boolean;
            opfsAvailable?: boolean;
        };
    }
    Index
    totalCacheMemory memoryLimit memoryPercent totalEntries effectiveDemandHitRate? avgAccessTime queriesPerSec loadsPerSec bandwidth l1? l2? l0? slice? enabled? telemetryState? network? status? health?
    totalCacheMemory: number
    memoryLimit: number
    memoryPercent: number
    totalEntries: number
    effectiveDemandHitRate?: number

    Effective demand hit-rate across all cache tiers: (l0Hits + l1Hits + l2Hits) / (l0Hits + l1Hits + l2Hits + networkRequests). Undefined when neither L0 provider nor demand counters are wired (lets the UI distinguish "not wired up" from "0% hit rate").

    avgAccessTime: number
    queriesPerSec: number
    loadsPerSec: number
    bandwidth: number
    l1?: {
        size: number;
        count: number;
        hits: number;
        misses: number;
        evictions: number;
    }

    L1 memory cache breakdown (optional, only when CacheStatsProvider connected)

    l2?: {
        size: number;
        count: number;
        reads: number;
        writes: number;
        misses: number;
        canceledReads?: number;
        activeReads?: number;
        queuedReads?: number;
        quotaWriteSkipped?: number;
        writeFailures?: number;
        corruptedEntries?: number;
        metadataParseFailures?: number;
    }

    L2 OPFS cache breakdown (optional, only when CacheStatsProvider connected)

    Type Declaration

    • size: number
    • count: number
    • reads: number

      Successful gets (= L2 hits).

    • writes: number
    • misses: number

      Failed gets (file not present, size mismatch, I/O error).

    • OptionalcanceledReads?: number

      Reads canceled before filesystem I/O.

    • OptionalactiveReads?: number
    • OptionalqueuedReads?: number
    • OptionalquotaWriteSkipped?: number

      R3: surface OPFS health counters so the cache tab can render them inline (rather than only signalling them via the cache-errors-detected / quota-constrained badges). Each is optional — providers that don't expose them simply omit the field and the UI degrades to a "no errors" indicator.

    • OptionalwriteFailures?: number
    • OptionalcorruptedEntries?: number
    • OptionalmetadataParseFailures?: number
    l0?: {
        size: number;
        count: number;
        hits: number;
        misses: number;
        evictions: number;
        hitRate: number;
        maxSize?: number;
    }

    L0 decompressed chunk cache breakdown (optional, only when L0 cache connected)

    Type Declaration

    • size: number
    • count: number
    • hits: number
    • misses: number
    • evictions: number
    • hitRate: number
    • OptionalmaxSize?: number

      Resolved (heap-aware) byte budget.

    slice?: {
        size: number;
        count: number;
        hits: number;
        misses: number;
        evictions: number;
        hitRate: number;
        thrashMisses?: number;
        maxSize?: number;
        fullLadderCount?: number;
        ladderDepthHistogram?: Record<string, number>;
    }

    SliceCache ("S-cache") breakdown (optional, only when the SliceCache is connected)

    Type Declaration

    • size: number
    • count: number
    • hits: number
    • misses: number
    • evictions: number
    • hitRate: number
    • OptionalthrashMisses?: number

      Eviction-induced misses (working-set-over-budget / cyclic-playback thrash).

    • OptionalmaxSize?: number

      Resolved (heap-aware) byte budget — varies by device heap.

    • OptionalfullLadderCount?: number

      Number of ladder entries whose cached prefix is complete.

    • OptionalladderDepthHistogram?: Record<string, number>

      Cached ladder counts keyed by storedDepth/totalDepth.

    enabled?: boolean

    Whether caching is enabled. Derived from telemetryState.kind === 'enabled'. New code should read telemetryState directly to distinguish the three not-enabled variants from each other.

    telemetryState?: CacheTelemetryState

    Explicit cache telemetry state. Distinguishes "disabled-no-cache" (URL flag), "disabled-config" (app config / isEnabled false), and "not-wired" (provider absent during scene transition or before cache setup completes) from each other.

    network?: {
        bytesTransferred: number;
        requestCount: number;
        bandwidth: number;
        totalBytesServed?: number;
        totalRequestsServed?: number;
    }

    Network I/O stats (optional, only when CacheStatsProvider connected)

    Type Declaration

    • bytesTransferred: number
    • requestCount: number
    • bandwidth: number
    • OptionaltotalBytesServed?: number

      Cumulative bytes delivered to demand callers across all cache tiers (L1 + L2 + network). Optional — providers predating the field omit it. Drives the Overview "DATA LOADED" card so it stays informative on warm/cache-served reloads.

    • OptionaltotalRequestsServed?: number

      Count of demand reads served across all tiers.

    status?: CacheStatusBadge[]

    Status badges for the cache tab. Derived in the aggregator from telemetry state + provider presence + cache health. UI renders each as a small chip; consumers reading metrics programmatically (e.g. debug snapshots, E2E tests) can also assert on them.

    health?: {
        validationMode?: CacheValidationMode;
        lastValidatedAt?: number | null;
        unvalidatedExternalDataset?: boolean;
        opfsAvailable?: boolean;
    }

    Cache health snapshot mirroring MultiLevelCachingStore.getStats().health. Optional because some providers may not surface it.

    Type Declaration

    • OptionalvalidationMode?: CacheValidationMode
    • OptionallastValidatedAt?: number | null
    • OptionalunvalidatedExternalDataset?: boolean
    • OptionalopfsAvailable?: boolean

      S2: true when OPFS L2 storage is operational or caching is disabled (no L2 expected). false when L2 was expected but could not be initialised — drives the opfs-unavailable badge.

    Settings
    Member Visibility

    On This Page
    Properties