metrics
Generated Rust API reference for byte_engine.
Module metrics
Per-tick performance samples for tooling that reads them over the inspector.
Metrics keeps one TickSample per application tick in a bounded ring: the tick's clock, whether it reached
the screen, the CPU time spent in every tracing span the engine opens, and the GPU time of every counter the
renderer records. Spans reach it through MetricsLayer, which the application installs as its global tracing
subscriber, so the spans Tracy shows and the numbers the inspector serves come from the same call sites. GPU
times arrive late, once the frame that recorded them completes, and land in the tick that submitted that frame.
Read the ring as summaries with Metrics::summary or row by row with Metrics::ticks_since. The HTTP
inspector serves both as GET /metrics and GET /metrics/frames.
Contents
Quick Reference
| Item | Kind | Description |
|---|---|---|
MetricId | struct | The MetricId struct names one registered metric so the hot paths index arrays instead of comparing names. |
TickSample | struct | The TickSample struct holds everything one tick measured, with each metric at its registered index. |
TickClock | struct | The TickClock struct carries the per-tick facts only the application loop knows when it ends a tick. |
Metrics | struct | The Metrics struct collects per-tick CPU and GPU timings and serves them to inspection transports. |
Sample | struct | The Sample struct is one retained tick with the names its values serialize under. |
Statistics | struct | The Statistics struct describes the distribution of one metric over the summarized ticks, in milliseconds. |
MetricSummary | struct | The MetricSummary struct is the distribution of one named metric. |
Summary | struct | The Summary struct is the aggregate view of the retained ticks that GET /metrics returns. |
MetricsLayer | struct | The MetricsLayer struct feeds the time spent in tracing spans into a [Metrics] collector. |
MetricKind | enum | The MetricKind enum separates the clock a metric came from, since CPU and GPU times of one tick do not add up. |
METRIC_CAPACITY | const | The number of distinct metrics one application can track, across CPU spans and GPU counters. |
TICK_CAPACITY | const | The number of ticks the ring retains before the oldest one is overwritten. |
Structs
MetricId
struct MetricId();Defined in crates/byte-engine/src/metrics.rs:44
The MetricId struct names one registered metric so the hot paths index arrays instead of comparing names.
Trait Implementations
impl ArchivePointee for MetricId
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for MetricId
impl Clone for MetricId
-
fn clone(&self) -> MetricIdRelated:
MetricId
impl Copy for MetricId
impl Debug for MetricId
-
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for MetricId
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for MetricId
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Eq for MetricId
impl<K> Equivalent for MetricId
-
fn equivalent(&self, key: &K) -> bool
impl Hash for MetricId
-
fn hash<__H: hash::Hasher>(&self, state: &mut __H)
impl Instrument for MetricId
impl LayoutRaw for MetricId
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for MetricId
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for MetricId
-
fn eq(&self, other: &MetricId) -> boolRelated:
MetricId
impl Pointee for MetricId
-
type Metadata = ()
impl Read for MetricId
impl StructuralPartialEq for MetricId
impl WithSubscriber for MetricId
TickSample
struct TickSample {
pub tick: u64,
pub frame: Option<u64>,
pub time: std::time::Duration,
pub delta: std::time::Duration,
pub presented: bool,
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/metrics.rs:58-70
The TickSample struct holds everything one tick measured, with each metric at its registered index.
Fields
-
tick:u64The zero-based application tick this row belongs to.
-
frame:Option<u64>The renderer frame the tick submitted, which screenshots also report, or
Nonewhen it rendered nothing. -
time:std::time::DurationWall-clock time since the application started, measured when the tick ended.
-
delta:std::time::DurationThe frame delta the tick advanced the application clock by.
-
presented:boolWhether a window acquired a swapchain image this tick, so the frame can reach the screen.
Implementations
-
fn value(&self, metric: MetricId) -> Option<Duration>Related:
MetricIdReturns the value
metricmeasured this tick, when it did.
Trait Implementations
impl ArchivePointee for TickSample
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for TickSample
impl Clone for TickSample
-
fn clone(&self) -> TickSampleRelated:
TickSample
impl Downcast for TickSample
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for TickSample
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for TickSample
impl LayoutRaw for TickSample
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for TickSample
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for TickSample
-
type Metadata = ()
impl Read for TickSample
impl WithSubscriber for TickSample
TickClock
struct TickClock {
pub tick: u64,
pub frame: Option<u64>,
pub time: std::time::Duration,
pub delta: std::time::Duration,
pub presented: bool,
}Defined in crates/byte-engine/src/metrics.rs:82-93
The TickClock struct carries the per-tick facts only the application loop knows when it ends a tick.
Fields
-
tick:u64The zero-based tick that is ending.
-
frame:Option<u64>The renderer frame the tick submitted, if any.
-
time:std::time::DurationWall-clock time since the application started.
-
delta:std::time::DurationThe frame delta of the tick.
-
presented:boolWhether a window acquired a swapchain image this tick.
Trait Implementations
impl ArchivePointee for TickClock
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for TickClock
impl Clone for TickClock
-
fn clone(&self) -> TickClockRelated:
TickClock
impl Copy for TickClock
impl Debug for TickClock
-
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for TickClock
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for TickClock
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for TickClock
impl LayoutRaw for TickClock
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for TickClock
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for TickClock
-
type Metadata = ()
impl Read for TickClock
impl WithSubscriber for TickClock
Metrics
struct Metrics {
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/metrics.rs:123-127
The Metrics struct collects per-tick CPU and GPU timings and serves them to inspection transports.
Create one per application, hand a clone of the Arc to the MetricsLayer and the renderer, and call
Self::end_tick once per tick after the tick's own span closed. Read it back through Self::summary and
Self::ticks_since.
Implementations
-
fn new() -> SelfCreates an empty collector that holds
TICK_CAPACITYticks ofMETRIC_CAPACITYmetrics. -
fn register(&self, kind: MetricKind, name: &str) -> Option<MetricId>Related:
MetricKind,MetricIdRegisters a metric by name, or returns the id it already has, so spans with one name share one metric.
Returns
NoneonceMETRIC_CAPACITYdistinct metrics exist, or when the same name was registered with theother clock, which keeps CPU and GPU columns from mixing.
-
fn add_cpu(&self, metric: MetricId, duration: Duration)Related:
MetricIdAdds CPU time to
metricfor the tick in progress. Any thread may call it. -
fn set_gpu(&self, frame: u64, metric: MetricId, duration: Duration)Related:
MetricIdStores the GPU time
metricmeasured in renderer frameframe, which an earlier tick submitted.The sample is dropped when that tick already left the ring.
-
fn end_tick(&self, clock: TickClock)Related:
TickClockCloses the tick: moves the accumulated CPU time into a new row and clears the accumulators.
Call it after the tick's outermost span closed, otherwise that span's time lands in the next tick.
-
fn ticks_since(&self, since: Option<u64>) -> Vec<Sample>Related:
SampleReturns the retained ticks after
since, oldest first, or every retained tick whensinceisNone. -
fn summary(&self, since: Option<u64>, presented_only: bool) -> SummaryRelated:
SummarySummarizes every metric over the retained ticks after
since, optionally over presented ticks only.
Trait Implementations
impl ArchivePointee for Metrics
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for Metrics
impl Default for Metrics
-
fn default() -> Self
impl Downcast for Metrics
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for Metrics
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for Metrics
impl LayoutRaw for Metrics
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for Metrics
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for Metrics
-
type Metadata = ()
impl Read for Metrics
impl<R> ReadPrimitive for Metrics
impl WithSubscriber for Metrics
Sample
struct Sample {
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/metrics.rs:291-294
The Sample struct is one retained tick with the names its values serialize under.
It serializes as one JSON object: tick, frame, time, dt, presented, and a cpu and a gpu object of
metric name to milliseconds, listing only what the tick measured.
Implementations
-
fn tick(&self) -> &TickSampleRelated:
TickSampleReturns the measured tick.
Trait Implementations
impl ArchivePointee for Sample
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for Sample
impl Downcast for Sample
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for Sample
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for Sample
impl LayoutRaw for Sample
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for Sample
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for Sample
-
type Metadata = ()
impl Read for Sample
impl Serialize for Sample
-
fn serialize<S: Serializer>(&self, serializer: S) -> Result<<S as >::Ok, <S as >::Error>
impl WithSubscriber for Sample
Statistics
struct Statistics {
pub count: u64,
pub mean: f64,
pub min: f64,
pub max: f64,
pub p50: f64,
pub p95: f64,
pub p99: f64,
}Defined in crates/byte-engine/src/metrics.rs:351-360
The Statistics struct describes the distribution of one metric over the summarized ticks, in milliseconds.
Fields
-
count:u64How many summarized ticks measured the metric.
Trait Implementations
impl ArchivePointee for Statistics
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for Statistics
impl Clone for Statistics
-
fn clone(&self) -> StatisticsRelated:
Statistics
impl Debug for Statistics
-
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for Statistics
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for Statistics
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for Statistics
impl LayoutRaw for Statistics
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for Statistics
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for Statistics
-
fn eq(&self, other: &Statistics) -> boolRelated:
Statistics
impl Pointee for Statistics
-
type Metadata = ()
impl Read for Statistics
impl Serialize for Statistics
-
fn serialize<__S>(&self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
impl StructuralPartialEq for Statistics
impl WithSubscriber for Statistics
MetricSummary
struct MetricSummary {
pub name: Box<str>,
pub kind: MetricKind,
pub statistics: Statistics,
}Defined in crates/byte-engine/src/metrics.rs:388-393
The MetricSummary struct is the distribution of one named metric.
Trait Implementations
impl ArchivePointee for MetricSummary
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for MetricSummary
impl Clone for MetricSummary
-
fn clone(&self) -> MetricSummaryRelated:
MetricSummary
impl Debug for MetricSummary
-
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for MetricSummary
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for MetricSummary
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for MetricSummary
impl LayoutRaw for MetricSummary
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for MetricSummary
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for MetricSummary
-
type Metadata = ()
impl Read for MetricSummary
impl Serialize for MetricSummary
-
fn serialize<__S>(&self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
impl WithSubscriber for MetricSummary
Summary
struct Summary {
pub ticks: u64,
pub first_tick: Option<u64>,
pub last_tick: Option<u64>,
pub presented_ticks: u64,
pub time_to_first_frame: Option<std::time::Duration>,
pub delta: Option<Statistics>,
pub metrics: Vec<MetricSummary>,
}Defined in crates/byte-engine/src/metrics.rs:397-411
The Summary struct is the aggregate view of the retained ticks that GET /metrics returns.
Fields
-
ticks:u64How many ticks the summary covers.
-
presented_ticks:u64How many of the covered ticks could reach the screen.
-
time_to_first_frame:Option<std::time::Duration>Milliseconds from application start to the first tick that could reach the screen.
-
delta:Option<Statistics>The frame delta over the covered ticks, in milliseconds.
-
metrics:Vec<MetricSummary>Every metric at least one covered tick measured.
Trait Implementations
impl ArchivePointee for Summary
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for Summary
impl Clone for Summary
-
fn clone(&self) -> SummaryRelated:
Summary
impl Debug for Summary
-
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for Summary
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for Summary
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for Summary
impl LayoutRaw for Summary
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for Summary
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for Summary
-
type Metadata = ()
impl Read for Summary
impl Serialize for Summary
-
fn serialize<__S>(&self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
impl WithSubscriber for Summary
MetricsLayer
struct MetricsLayer {
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/metrics.rs:431-435
The MetricsLayer struct feeds the time spent in tracing spans into a Metrics collector.
Install it in the global subscriber, over a registry, before the application opens its first span. Every span
at DEBUG or a less verbose level becomes a CPU metric named after the span; spans with one name share a metric
wherever they open. Events pass through untouched.
Implementations
-
fn new(metrics: Arc<Metrics>) -> SelfRelated:
MetricsCreates a layer that reports into
metrics.
Trait Implementations
impl ArchivePointee for MetricsLayer
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for MetricsLayer
impl Downcast for MetricsLayer
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for MetricsLayer
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for MetricsLayer
impl<S> Layer for MetricsLayer
-
fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest -
fn enabled(&self, metadata: &Metadata<'_>, _: Context<'_, S>) -> bool -
fn on_new_span(&self, _: &Attributes<'_>, _: &Id, _: Context<'_, S>) -
fn on_enter(&self, id: &Id, ctx: Context<'_, S>) -
fn on_exit(&self, _: &Id, _: Context<'_, S>)
impl LayoutRaw for MetricsLayer
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for MetricsLayer
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for MetricsLayer
-
type Metadata = ()
impl Read for MetricsLayer
impl WithSubscriber for MetricsLayer
Enums
MetricKind
enum MetricKind {
Cpu,
Gpu,
}Defined in crates/byte-engine/src/metrics.rs:49-54
The MetricKind enum separates the clock a metric came from, since CPU and GPU times of one tick do not add up.
Variants
-
CpuTime the CPU spent inside spans of one name during the tick, summed over every entry on every thread.
-
GpuTime the GPU spent between the start and end of one counter in the frame the tick submitted.
Trait Implementations
impl ArchivePointee for MetricKind
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for MetricKind
impl Clone for MetricKind
-
fn clone(&self) -> MetricKindRelated:
MetricKind
impl Copy for MetricKind
impl Debug for MetricKind
-
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for MetricKind
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for MetricKind
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Eq for MetricKind
impl<K> Equivalent for MetricKind
-
fn equivalent(&self, key: &K) -> bool
impl Hash for MetricKind
-
fn hash<__H: hash::Hasher>(&self, state: &mut __H)
impl Instrument for MetricKind
impl LayoutRaw for MetricKind
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for MetricKind
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for MetricKind
-
fn eq(&self, other: &MetricKind) -> boolRelated:
MetricKind
impl Pointee for MetricKind
-
type Metadata = ()
impl Read for MetricKind
impl Serialize for MetricKind
-
fn serialize<__S>(&self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
impl StructuralPartialEq for MetricKind
impl WithSubscriber for MetricKind
Constants
METRIC_CAPACITY
const METRIC_CAPACITY: usize = 128usize;Defined in crates/byte-engine/src/metrics.rs:34
The number of distinct metrics one application can track, across CPU spans and GPU counters.
TICK_CAPACITY
const TICK_CAPACITY: usize = 1_024usize;Defined in crates/byte-engine/src/metrics.rs:37
The number of ticks the ring retains before the oldest one is overwritten.