Code at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.
use collections::{HashMap, HashSet};
use gpui::{
App, FRAME_DURATION_BUCKETS_MS, FRAME_WORK_BUCKETS_PERCENT, Global, InputLatencySnapshot,
RefreshIntervalFrames, Window, WindowId, actions, histogram_bucket_counts,
};
use hdrhistogram::Histogram;
use std::{
sync::OnceLock,
time::{Duration, Instant},
};
actions!(
dev,
[
/// Opens a buffer showing the input-to-frame latency histogram for the current window.
DumpInputLatencyHistogram,
]
);
/// The data needed to format an input-latency report, captured synchronously
/// by [`snapshot_input_latency_report`]. Formatting via
/// [`format_input_latency_report`] is pure computation and can happen on a
/// background thread.
pub struct InputLatencyReportData {
snapshot: InputLatencySnapshot,
previous_snapshot: Option<InputLatencySnapshot>,
previous_timestamp: Option<chrono::DateTime<chrono::Local>>,
timestamp: chrono::DateTime<chrono::Local>,
/// The collab username of the user whose machine produced the data.
/// Set when the report will be placed in a buffer visible to other
/// collaborators, so it's clear whose latency was measured.
reported_by: Option<String>,
}
/// Captures the input-to-frame latency histogram for the given window, along
/// with the previous report's baseline (tracked via a global on the `App`) for
/// delta computation. Advances the baseline to this snapshot.
pub fn snapshot_input_latency_report(
window: &Window,
reported_by: Option<String>,
cx: &mut App,
) -> InputLatencyReportData {
let snapshot = window.input_latency_snapshot();
let timestamp = chrono::Local::now();
let state = cx.default_global::<ReporterState>();
let data = InputLatencyReportData {
snapshot: snapshot.clone(),
previous_snapshot: state.previous_snapshot.take(),
previous_timestamp: state.previous_timestamp.take(),
timestamp,
reported_by,
};
state.previous_snapshot = Some(snapshot);
state.previous_timestamp = Some(timestamp);
data
}
/// Generates a formatted text report from a previously captured
/// [`InputLatencyReportData`]. If the capture included a previous snapshot,
/// includes a delta section showing changes since that report.
pub fn format_input_latency_report(data: &InputLatencyReportData) -> String {
format_report(data)
}
#[derive(Default)]
struct ReporterState {
previous_snapshot: Option<InputLatencySnapshot>,
previous_timestamp: Option<chrono::DateTime<chrono::Local>>,
}
impl Global for ReporterState {}
/// Per-window state used for telemetry delta computation. Kept separate from
/// `ReporterState` so the user-facing dump and the background telemetry flush
/// maintain independent baselines.
#[derive(Default)]
struct TelemetryReporterState {
/// Keyed by window id. Each entry holds the cumulative snapshot at the time
/// of the last telemetry flush, plus the wall-clock time of that flush.
previous: HashMap<WindowId, (Instant, InputLatencySnapshot)>,
}
impl Global for TelemetryReporterState {}
/// Nanosecond boundaries for the time-range buckets used in telemetry.
/// These match the display distribution in format_report so the two stay in sync.
const MS4_NS: u64 = 4_000_000;
const MS8_NS: u64 = 8_000_000;
const MS16_NS: u64 = 16_000_000;
const MS33_NS: u64 = 33_000_000;
const MS100_NS: u64 = 100_000_000;
/// Minimum number of frames that must be present in the delta window for the
/// telemetry report to be sent. Avoids sending noise for windows that are
/// mostly idle.
const MIN_FRAMES_TO_REPORT: u64 = 5_000;
/// Computes and sends a `input_latency_report` telemetry event for the given
/// window if enough frames have been recorded since the last report.
///
/// Call this periodically (e.g. every five minutes) from a spawned task. A
/// separate baseline snapshot is kept per window so user-facing histogram dumps
/// and telemetry never share state.
pub fn report_input_latency_telemetry(window: &Window, cx: &mut App) {
let current = window.input_latency_snapshot();
let window_id = window.window_handle().window_id();
let open_window_ids = open_window_ids(cx);
let state = cx.default_global::<TelemetryReporterState>();
state
.previous
.retain(|window_id, _| open_window_ids.contains(window_id));
let now = Instant::now();
let (delta_latency, delta_coalesce, report_window_seconds) =
if let Some((prev_instant, prev_snapshot)) = state.previous.get(&window_id) {
let mut delta_latency = current.latency_histogram.clone();
delta_latency
.subtract(&prev_snapshot.latency_histogram)
.ok();
let mut delta_coalesce = current.events_per_frame_histogram.clone();
delta_coalesce
.subtract(&prev_snapshot.events_per_frame_histogram)
.ok();
let elapsed = now.duration_since(*prev_instant).as_secs();
(delta_latency, delta_coalesce, elapsed)
} else {
// First report for this window: the full cumulative histogram is the
// delta from the empty starting state. We don't know how long the
// window has been open, so record 0 to signal that this is the
// initial accumulation period rather than a fixed-width window.
(
current.latency_histogram.clone(),
current.events_per_frame_histogram.clone(),
0u64,
)
};
let total_frames = delta_latency.len();
if total_frames < MIN_FRAMES_TO_REPORT {
return;
}
state.previous.insert(window_id, (now, current));
// Frames over 100 ms, or with 4+ events, are implied by total_frames.
let latency_counts =
histogram_bucket_counts(&delta_latency, [MS4_NS, MS8_NS, MS16_NS, MS33_NS, MS100_NS]);
let coalesce_counts = histogram_bucket_counts(&delta_coalesce, [1, 2, 3]);
let latency = |index: usize| latency_counts.get(index).copied().unwrap_or_default();
let coalesce = |index: usize| coalesce_counts.get(index).copied().unwrap_or_default();
telemetry::event!(
"Latency Report",
frames_sub4 = latency(0),
frames_4to8 = latency(1),
frames_8to16 = latency(2),
frames_16to33 = latency(3),
frames_33to100 = latency(4),
total_frames = total_frames,
frames_with_1_event = coalesce(0),
frames_with_2_events = coalesce(1),
frames_with_3_events = coalesce(2),
report_window_seconds = report_window_seconds,
measurement_version = gpui::profiler::hang::MEASUREMENT_VERSION,
);
}
/// Per-window, per-refresh-interval baselines for frame-duration telemetry.
/// Kept separate from the input-latency baselines so the two reports never
/// share state.
#[derive(Default)]
struct FrameDurationTelemetryState {
previous: HashMap<(WindowId, Option<Duration>), (Instant, RefreshIntervalFrames)>,
}
impl Global for FrameDurationTelemetryState {}
/// Minimum number of draws at one refresh interval since its last report for
/// a frame-duration report to be sent. Avoids sending noise for windows that
/// are mostly idle.
const MIN_DRAWS_TO_REPORT: u64 = 1_000;
/// Sends a `Frame Duration Report` telemetry event for each refresh interval
/// the given window drew enough frames at since its last report, so every
/// report describes frames on displays with one refresh rate.
///
/// Each report contains frame pacing (frames on time and late, missed
/// refreshes, and work per frame as a percentage of the refresh interval), the
/// same for frames that responded to input, and bucketed draw durations.
/// Buckets rather than percentiles, so reports can be summed.
///
/// Call this periodically from a spawned task.
pub fn report_frame_duration_telemetry(window: &Window, cx: &mut App) {
let snapshot = window.frame_duration_snapshot();
let window_handle = window.window_handle();
let window_id = window_handle.window_id();
let gpu = window.gpu_specs();
let open_window_ids = open_window_ids(cx);
let state = cx.default_global::<FrameDurationTelemetryState>();
state
.previous
.retain(|(window_id, _), _| open_window_ids.contains(window_id));
let now = Instant::now();
for current in snapshot.by_refresh_interval {
let key = (window_id, current.refresh_interval);
let (frames, report_window_seconds) = match state.previous.get(&key) {
Some((previous_instant, previous)) => (
current.since(previous),
now.duration_since(*previous_instant).as_secs(),
),
// First report for this window and refresh interval: we don't know
// how long it has been accumulating, so record 0 to signal that
// this isn't a fixed-width window.
None => (current.clone(), 0),
};
if frames.frames_drawn < MIN_DRAWS_TO_REPORT {
continue;
}
state.previous.insert(key, (now, current));
let mut properties = std::collections::HashMap::from_iter([
(
"refresh_interval_ms".to_string(),
serde_json::json!(
frames
.refresh_interval
.map(|interval| interval.as_secs_f64() * 1000.0)
),
),
(
"refresh_rate_hz".to_string(),
serde_json::json!(
frames
.refresh_interval
.map(|interval| (1.0 / interval.as_secs_f64()).round() as u64)
),
),
("frames_drawn".to_string(), frames.frames_drawn.into()),
(
"input_frames_on_time".to_string(),
frames.input_frames_on_time.into(),
),
(
"input_frames_late".to_string(),
frames.input_frames_late.into(),
),
("frames_on_time".to_string(), frames.frames_on_time.into()),
("frames_late".to_string(), frames.frames_late.into()),
(
"missed_refreshes".to_string(),
frames.missed_refreshes.into(),
),
(
"frames_unmeasured".to_string(),
frames.frames_unmeasured.into(),
),
(
"gpu_name".to_string(),
serde_json::json!(gpu.as_ref().map(|gpu| gpu.device_name.clone())),
),
(
"gpu_is_software_emulated".to_string(),
serde_json::json!(gpu.as_ref().map(|gpu| gpu.is_software_emulated)),
),
("cpu_name".to_string(), serde_json::json!(cpu_name())),
(
"root_entity_type_name".to_string(),
serde_json::json!(window_handle.root_entity_type_name()),
),
(
"report_window_seconds".to_string(),
report_window_seconds.into(),
),
(
"measurement_version".to_string(),
gpui::profiler::hang::MEASUREMENT_VERSION.into(),
),
]);
// Work buckets are relative to the refresh interval, so frames on
// displays with an unknown interval have none.
if let Some(refresh_interval) = frames.refresh_interval {
let work_bounds = FRAME_WORK_BUCKETS_PERCENT.map(|percent| {
u64::try_from(refresh_interval.as_nanos() * u128::from(percent) / 100)
.unwrap_or(u64::MAX)
});
for (prefix, work) in [
("work_pct", &frames.work),
("input_work_pct", &frames.input_work),
] {
let counts = histogram_bucket_counts(work, work_bounds);
insert_buckets(
&mut properties,
prefix,
&FRAME_WORK_BUCKETS_PERCENT,
&counts,
);
}
}
let draw_counts = histogram_bucket_counts(
&frames.draw_duration,
FRAME_DURATION_BUCKETS_MS.map(|milliseconds| milliseconds * 1_000_000),
);
insert_buckets(
&mut properties,
"draw_ms",
&FRAME_DURATION_BUCKETS_MS,
&draw_counts,
);
telemetry::send_event(telemetry::Event {
event_type: "Frame Duration Report".to_string(),
event_properties: properties,
});
}
}
/// Inserts bucket counts as `{prefix}_le_{bound}` properties, plus
/// `{prefix}_gt_{last bound}` for the final, unbounded bucket.
fn insert_buckets(
properties: &mut std::collections::HashMap<String, serde_json::Value>,
prefix: &str,
upper_bounds: &[u64],
counts: &[u64],
) {
for (index, count) in counts.iter().enumerate() {
let name = match upper_bounds.get(index) {
Some(bound) => format!("{prefix}_le_{bound}"),
None => format!(
"{prefix}_gt_{}",
upper_bounds.last().copied().unwrap_or_default()
),
};
properties.insert(name, (*count).into());
}
}
fn cpu_name() -> Option<&'static str> {
static CPU_NAME: OnceLock<Option<String>> = OnceLock::new();
CPU_NAME
.get_or_init(|| {
let system = sysinfo::System::new_with_specifics(
sysinfo::RefreshKind::nothing().with_cpu(sysinfo::CpuRefreshKind::nothing()),
);
system
.cpus()
.first()
.map(|cpu| cpu.brand().trim().to_string())
.filter(|brand| !brand.is_empty())
})
.as_deref()
}
fn open_window_ids(cx: &App) -> HashSet<WindowId> {
cx.windows()
.into_iter()
.map(|window| window.window_id())
.collect()
}
fn format_report(data: &InputLatencyReportData) -> String {
let snapshot = &data.snapshot;
let histogram = &snapshot.latency_histogram;
let total = histogram.len();
if total == 0 {
return "No input latency samples recorded yet.\n\nTry typing or clicking in a buffer first.".to_string();
}
let percentiles: &[(&str, f64)] = &[
("min ", 0.0),
("p50 ", 0.50),
("p75 ", 0.75),
("p90 ", 0.90),
("p95 ", 0.95),
("p99 ", 0.99),
("p99.9", 0.999),
("max ", 1.0),
];
let now = data.timestamp;
let mut report = String::new();
report.push_str("Input Latency Histogram\n");
report.push_str("=======================\n");
let timestamp = now.format("%Y-%m-%d %H:%M:%S %Z");
report.push_str(&format!("Timestamp: {timestamp}\n"));
if let Some(reported_by) = &data.reported_by {
report.push_str(&format!("Reported from {reported_by}'s machine\n"));
}
report.push_str(&format!("Samples: {total}\n"));
if snapshot.mid_draw_events_dropped > 0 {
report.push_str(&format!(
"Mid-draw events excluded: {}\n",
snapshot.mid_draw_events_dropped
));
}
write_latency_percentiles(&mut report, "Percentiles", histogram, percentiles);
write_latency_distribution(&mut report, "Distribution", histogram);
let coalesce = &snapshot.events_per_frame_histogram;
let coalesce_total = coalesce.len();
if coalesce_total > 0 {
report.push('\n');
report.push_str("Events coalesced per frame:\n");
for (label, quantile) in percentiles {
let value = if *quantile == 0.0 {
coalesce.min()
} else if *quantile == 1.0 {
coalesce.max()
} else {
coalesce.value_at_quantile(*quantile)
};
report.push_str(&format!(" {label}: {value:>6} events\n"));
}
report.push('\n');
report.push_str("Distribution:\n");
let bar_width = 30usize;
let max_count = coalesce.max();
for n in 1..=max_count {
let count = coalesce
.iter_recorded()
.filter(|value| value.value_iterated_to() == n)
.map(|value| value.count_at_value())
.sum::<u64>();
if count == 0 {
continue;
}
let fraction = count as f64 / coalesce_total as f64;
let bar_len = (fraction * bar_width as f64) as usize;
let bar = "\u{2588}".repeat(bar_len);
report.push_str(&format!(
" {n:>6} events: {count:>6} ({:>5.1}%) {bar}\n",
fraction * 100.0,
));
}
}
// Delta section: compare against the previous report's snapshot.
if let (Some(prev_snapshot), Some(prev_timestamp)) =
(&data.previous_snapshot, &data.previous_timestamp)
{
let prev_latency = &prev_snapshot.latency_histogram;
let prev_total = prev_latency.len();
let delta_total = total - prev_total;
report.push('\n');
report.push_str("Delta Since Last Report\n");
report.push_str("-----------------------\n");
let prev_ts = prev_timestamp.format("%Y-%m-%d %H:%M:%S %Z");
let elapsed_secs = (now - *prev_timestamp).num_seconds().max(0);
report.push_str(&format!(
"Previous report: {prev_ts} ({elapsed_secs}s ago)\n"
));
report.push_str(&format!("New samples: {delta_total}\n"));
if delta_total > 0 {
let mut delta_histogram = histogram.clone();
delta_histogram.subtract(prev_latency).ok();
write_latency_percentiles(
&mut report,
"Percentiles (new samples only)",
&delta_histogram,
percentiles,
);
write_latency_distribution(
&mut report,
"Distribution (new samples only)",
&delta_histogram,
);
}
}
report
}
fn write_latency_percentiles(
report: &mut String,
heading: &str,
histogram: &Histogram<u64>,
percentiles: &[(&str, f64)],
) {
let ns_to_ms = |ns: u64| ns as f64 / 1_000_000.0;
report.push('\n');
report.push_str(heading);
report.push_str(":\n");
for (label, quantile) in percentiles {
let value_ns = if *quantile == 0.0 {
histogram.min()
} else if *quantile == 1.0 {
histogram.max()
} else {
histogram.value_at_quantile(*quantile)
};
let hz = if value_ns > 0 {
1_000_000_000.0 / value_ns as f64
} else {
f64::INFINITY
};
report.push_str(&format!(
" {label}: {:>8.2}ms ({:>7.1} Hz)\n",
ns_to_ms(value_ns),
hz
));
}
}
fn write_latency_distribution(report: &mut String, heading: &str, histogram: &Histogram<u64>) {
const BUCKETS: &[(u64, u64, &str, &str)] = &[
(0, 4_000_000, "0\u{2013}4ms", "(excellent)"),
(4_000_000, 8_000_000, "4\u{2013}8ms", "(120fps)"),
(8_000_000, 16_000_000, "8\u{2013}16ms", "(60fps)"),
(16_000_000, 33_000_000, "16\u{2013}33ms", "(30fps)"),
(33_000_000, 100_000_000, "33\u{2013}100ms", ""),
(100_000_000, u64::MAX, "100ms+", "(sluggish)"),
];
let bar_width = 30usize;
let total = histogram.len() as f64;
report.push('\n');
report.push_str(heading);
report.push_str(":\n");
for (low, high, range, note) in BUCKETS {
let count: u64 = histogram
.iter_recorded()
.filter(|value| value.value_iterated_to() >= *low && value.value_iterated_to() < *high)
.map(|value| value.count_at_value())
.sum();
let fraction = if total > 0.0 {
count as f64 / total
} else {
0.0
};
let bar_len = (fraction * bar_width as f64) as usize;
let bar = "\u{2588}".repeat(bar_len);
report.push_str(&format!(
" {range:>8} {note:<11}: {count:>6} ({:>5.1}%) {bar}\n",
fraction * 100.0,
));
}
}