Struct RealUsage 

pub struct RealUsage {
    pub model: String,
    pub input_tokens: u64,
    pub output_tokens: u64,
    pub cache_read_tokens: u64,
    pub cache_write_tokens: u64,
    pub reasoning_tokens: u64,
    pub provider_cost_usd: Option<f64>,
    pub cohort: Cohorts,
    pub wire: Option<Box<WireContext>>,
    pub response_observation: Option<ResponseObservation>,
}

One LLM turn’s real, provider-reported usage, normalized to billable buckets.

output_tokens already includes reasoning/thinking tokens (they are billed at the output rate); reasoning_tokens is retained only for display.

Fields

model: String

input_tokens: u64

Input tokens billed at the input rate (cache reads/writes excluded).

output_tokens: u64

Output tokens billed at the output rate (includes reasoning/thoughts).

cache_read_tokens: u64

Input tokens served from the prompt cache (billed at the cache-read rate).

cache_write_tokens: u64

Input tokens written to the prompt cache (Anthropic + OpenRouter models with explicit cache-write pricing; 0 elsewhere).

reasoning_tokens: u64

Reasoning/thinking subset of output_tokens (display only).

provider_cost_usd: Option<f64>

USD the provider actually charged for this turn, when the response reports it. OpenRouter: usage.cost in credits (≡ USD); for BYOK requests the separate cost_details.upstream_inference_cost is added when it differs from cost (#746 — non-BYOK mirrors cost there). The measured figure beats any price-table estimate wherever both exist. None for providers that report tokens only (Anthropic/OpenAI/Gemini).

cohort: Cohorts

Holdout arms for this turn: output shaping (#895 Track B) and input compression (#1905), each None when that holdout is off. Stamped from the request, not parsed from the response.

wire: Option<Box<WireContext>>

Request-side gateway context (enterprise#11/#17/#18): identity tags, compression savings and baseline inputs, stamped from the request before it left for the upstream. None outside the forward path (e.g. tests that only parse response bodies).

response_observation: Option<ResponseObservation>

Present only for measured upstream responses, never cache hits or synthetic parser inputs. Kept local in the existing usage meter.

Implementations

impl RealUsage

pub fn to_ocla_usage_record(&self) -> OclaResult<Option<UsageRecord>>

Projects measured proxy usage into the payload-free canonical OCLA record. Missing lineage is unmanaged; invalid data and arithmetic overflow fail closed for OCLA without disturbing the existing usage pipeline.

Trait Implementations

impl Clone for RealUsage

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RealUsage

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for RealUsage

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq for RealUsage

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for RealUsage