Type Alias TelemetryConfig 

pub type TelemetryConfig = ConfigValueGroup;

Aliased Type

pub struct TelemetryConfig {
    pub enabled: bool,
    pub heartbeat_after: Duration,
    pub heartbeat_interval: Duration,
    pub request_timeout: Duration,
    pub final_flush_timeout: Duration,
    pub max_in_flight: usize,
}

Fields

enabled: bool

Whether the client reports transfer performance telemetry to the CAS server.

When enabled, each upload or download transfer sends a single summary document to POST /v1/telemetry when it finishes, plus periodic heartbeat documents for transfers that run longer than heartbeat_after. Sends are best-effort: they are never retried, never block data movement, and failures are only logged at DEBUG.

The payload carries no file names, paths, hashes, repository ids, or user ids.

Telemetry is force-disabled regardless of this value when any of huggingface_hub’s opt-out variables (HF_HUB_DISABLE_TELEMETRY, DISABLE_TELEMETRY, DO_NOT_TRACK, HF_HUB_OFFLINE, TRANSFORMERS_OFFLINE) is set to a truthy value.

The default value is true.

Use the environment variable HF_XET_TELEMETRY_ENABLED to set this value.

heartbeat_after: Duration

How long a transfer must run before it starts emitting heartbeat documents.

Short transfers - the common case - only ever emit their terminal summary. Heartbeats exist so a long transfer that hangs or is killed still reports something.

Set to zero to disable heartbeats entirely.

The default value is 5 minutes.

Use the environment variable HF_XET_TELEMETRY_HEARTBEAT_AFTER to set this value.

heartbeat_interval: Duration

The interval between heartbeat documents once heartbeat_after has elapsed.

The default value is 5 minutes.

Use the environment variable HF_XET_TELEMETRY_HEARTBEAT_INTERVAL to set this value.

request_timeout: Duration

Whole-request budget for a single telemetry POST, including connection setup.

The default value is 5 seconds.

Use the environment variable HF_XET_TELEMETRY_REQUEST_TIMEOUT to set this value.

final_flush_timeout: Duration

How long a transfer waits for its terminal telemetry document to be delivered.

This runs after all transfer work has completed, so it delays no data movement, but it does delay the return of finalize(). A short bounded wait is used because a fully detached final send is usually lost: host processes frequently exit within milliseconds of the transfer returning.

Set to zero to make the terminal send fully detached.

The default value is 2 seconds.

Use the environment variable HF_XET_TELEMETRY_FINAL_FLUSH_TIMEOUT to set this value.

max_in_flight: usize

Maximum number of telemetry requests allowed in flight at once, across the whole process.

Documents submitted beyond this cap are dropped rather than queued; this is the backpressure mechanism that keeps a degraded telemetry endpoint from accumulating tasks.

The cap is process-wide rather than per-transfer, so it bounds a wide fan-out - a snapshot download becomes many concurrent per-file transfers, and a per-transfer cap would multiply by that count instead of limiting it.

The default value is 32. It is sized as a process-wide number: a transfer emits one terminal document, and heartbeats only start after heartbeat_after, so the realistic burst is a set of concurrent transfers finalizing together. A much smaller ceiling would shed most of a wide snapshot’s terminal documents, which are the ones worth keeping.

Use the environment variable HF_XET_TELEMETRY_MAX_IN_FLIGHT to set this value.