Report why turn critical path capture is incomplete (#62357)

## Why

The `incomplete` status alone gives no indication of which timing dependency was missing or which operation prevented capture.

## What changed

Emit deduplicated `critical_path_incomplete_reasons` in turn analytics for incomplete captures. Reasons cover unsupported Code Mode and agent operations, unattributed reviews and user waits, missing turn starts, and forced teardown, with an `unclassified` fallback. External tools that share a built-in name can still invalidate capture without being classified as the built-in operation.

During interruption, use the task's join result to distinguish forced teardown from normal completion so a task that already finished can still report a complete path.

## Testing

Add coverage for analytics serialization, concurrent reason deduplication, tool name collisions, and interrupted tasks that finish normally or require forced teardown.

GitOrigin-RevId: fab9aa1ff881997a34dcf75adc5638133cedc7fe
This commit is contained in:
akak-oai
2026-11-18 20:29:59 +00:00
committed by copyberry
parent 513577302a
commit ed9becd2fc
17 changed files with 279 additions and 96 deletions
+20 -14
View File
@@ -15,7 +15,6 @@ use codex_diagnostics::Gauge;
use codex_exec_server::ExecutorCapabilityDiscoveryV2Cache;
use codex_extension_api::ThreadIdleCause;
use futures::future::BoxFuture;
use tokio::select;
use tokio::sync::Mutex;
use tokio::sync::MutexGuard;
use tokio::sync::Notify;
@@ -47,6 +46,7 @@ use crate::state::RunningTask;
use crate::state::TaskKind;
use crate::state::TurnState;
use crate::turn_diff_tracker::TurnDiffTracker;
use codex_analytics::IncompleteReason;
use codex_analytics::TurnProfileFact;
use codex_analytics::TurnTokenUsageFact;
use codex_context_fragments::RenderedFragment;
@@ -1229,22 +1229,28 @@ impl Session {
.cancel_git_enrichment_task();
let session_task = task.task;
select! {
_ = task.done.notified() => {
},
_ = tokio::time::sleep(Duration::from_millis(GRACEFULL_INTERRUPTION_TIMEOUT_MS)) => {
warn!("task {sub_id} didn't complete gracefully after {}ms", GRACEFULL_INTERRUPTION_TIMEOUT_MS);
// Forced teardown can abort independently spawned tool dispatches
// whose guards are destroyed later. Do not publish complete totals
// for a dependency graph that has not settled.
task.turn_context.turn_timing_state.invalidate_critical_path();
let mut handle = task.handle;
let grace = Duration::from_millis(GRACEFULL_INTERRUPTION_TIMEOUT_MS);
let joined = match tokio::time::timeout(grace, &mut handle).await {
Ok(joined) => joined,
Err(_) => {
handle.abort();
handle.await
}
};
// A task may finish normally between the deadline and the abort.
if let Err(error) = joined {
warn!(%error, "task {sub_id} did not finish gracefully");
let reason = if error.is_cancelled() {
IncompleteReason::ForcedTeardown
} else {
IncompleteReason::Unclassified
};
task.turn_context
.turn_timing_state
.invalidate_critical_path(&[reason]);
}
task.handle.abort();
// Aborting schedules destruction; join before freezing the turn's timing.
let _ = task.handle.await;
if let Err(error) = self
.record_pending_initial_input(
&task.turn_context,
+45 -15
View File
@@ -600,6 +600,7 @@ fn emit_compact_metric_records_auto_local() {
struct UncooperativeTimedTask {
entered: Arc<tokio::sync::Notify>,
finish: Arc<tokio::sync::Notify>,
}
impl SessionTask for UncooperativeTimedTask {
@@ -631,45 +632,73 @@ impl SessionTask for UncooperativeTimedTask {
_blocking = timing.begin_tool_blocking(Some(batch));
let _review = _work.start_review();
self.entered.notify_one();
std::future::pending().await
self.finish.notified().await;
Ok(None)
}
}
#[test_case::test_case(false; "forced teardown")]
#[test_case::test_case(true; "finished before wait")]
#[tokio::test(flavor = "current_thread")]
async fn hard_abort_drops_timing_guards_before_profile_completion() {
async fn abort_drops_timing_guards_before_profile_completion(finished_before_wait: bool) {
use codex_analytics::IncompleteReason::ForcedTeardown;
use codex_analytics::TurnCriticalPath;
use codex_protocol::protocol::TurnAbortReason;
let (session, context, _receiver) = make_session_and_context_with_rx().await;
let entered = Arc::new(tokio::sync::Notify::new());
let finish = Arc::new(tokio::sync::Notify::new());
session
.spawn_task(
Arc::clone(&context),
Vec::new(),
UncooperativeTimedTask {
entered: Arc::clone(&entered),
finish: Arc::clone(&finish),
},
)
.await;
entered.notified().await;
let turn = session
.active_turn
.lock()
.await
.take()
.expect("active turn");
if finished_before_wait {
// The task exits after the abort claims the turn but before it waits.
let done = turn.task.as_ref().expect("running task").done.notified();
finish.notify_one();
done.await;
}
session
.abort_all_tasks(codex_protocol::protocol::TurnAbortReason::Interrupted)
.abort_taken_tasks(Some(turn), TurnAbortReason::Interrupted)
.await;
// The task's review and tool guards are gone before abort completion.
let timing = &context.turn_timing_state;
assert!(
context
.turn_timing_state
timing
.direct_tool_timings
.owner_for_turn("uncooperative", &context.sub_id)
.is_none()
);
assert_eq!(
context
.turn_timing_state
.snapshot_path(std::time::Instant::now()),
None
);
let (_, _, profile) = timing.complete_profile_and_duration_ms().await;
if finished_before_wait {
assert!(matches!(
profile.critical_path,
TurnCriticalPath::Complete(_)
));
} else {
assert_eq!(
profile.critical_path,
TurnCriticalPath::Incomplete(vec![ForcedTeardown])
);
}
}
#[tokio::test]
async fn turn_critical_path_metrics_count_each_capture_once() {
use codex_analytics::IncompleteReason::Unclassified;
use codex_analytics::TurnCriticalPath;
use codex_analytics::TurnCriticalPathDurations;
@@ -690,11 +719,12 @@ async fn turn_critical_path_metrics_count_each_capture_once() {
});
let _interest_cache_guard =
tracing::Dispatch::new(tracing::subscriber::NoSubscriber::default());
let incomplete = TurnCriticalPath::Incomplete(vec![Unclassified]);
for (sku, path) in [
(Some("codex"), complete),
(Some("codex"), TurnCriticalPath::Disabled),
(None, TurnCriticalPath::Incomplete),
(Some("unrecognized-sku"), TurnCriticalPath::Incomplete),
(None, incomplete.clone()),
(Some("unrecognized-sku"), incomplete),
] {
Arc::make_mut(&mut context.config).apps_mcp_product_sku = sku.map(str::to_owned);
context.turn_timing_state = Arc::default();
@@ -725,7 +755,7 @@ async fn turn_critical_path_metrics_count_each_capture_once() {
assert!(trace.contains("critical_path_inference_ms=31"));
assert!(trace.contains("critical_path_user_wait_ms=0"));
}
TurnCriticalPath::Disabled | TurnCriticalPath::Incomplete => {
TurnCriticalPath::Disabled | TurnCriticalPath::Incomplete(_) => {
assert!(!trace.contains("critical_path_duration_ms="));
let status = if matches!(profile.critical_path, TurnCriticalPath::Disabled) {
"disabled"