blob: 1963bde1721b0284baeadcdaef123888f7c1f78e [file] [edit]
# Copyright 2026 The Fuchsia Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.
from typing import Any, ClassVar, Final, Literal
from pydantic import BaseModel, ConfigDict, Field
from shared.protocol.base import BaseRequest
from shared.protocol.handles import HandleEntry
from zxdb_dap import AsyncTaskNode
COMMAND_NAME: Final = "diagnose-hang"
__all__ = [
"COMMAND_NAME",
"ClassifiedThread",
"DiagnoseHangRequest",
"DiagnoseHangResponse",
"ThreadHangClassification",
]
ThreadHangClassification = Literal[
"blocked_lock",
"blocked_ipc",
"port_wait",
"interrupt_wait",
"sleeping",
"active",
"unknown",
]
class ClassifiedThread(BaseModel):
"""Stack and concurrency classification for a target thread."""
model_config = ConfigDict(extra="forbid")
thread_id: int = Field(description="Thread KOID.")
name: str = Field(description="Thread name.")
classification: ThreadHangClassification = Field(
description=(
"Concurrency state classification: blocked_lock, blocked_ipc,"
" port_wait, interrupt_wait, sleeping, active, or unknown."
)
)
blocking_symbol: str | None = Field(
default=None,
description=(
"Top blocking syscall or synchronization primitive symbol, if"
" applicable."
),
)
summary: str = Field(
description=(
"Concise human/agent-readable explanation of what this thread is"
" doing."
)
)
top_frames: list[str] = Field(
default_factory=list,
description="Formatted top stack frames for this thread.",
)
class DiagnoseHangResponse(BaseModel):
"""Single-shot concurrency and hang snapshot of a process."""
model_config = ConfigDict(extra="forbid")
pid: int | None = Field(
default=None,
description="Target process KOID.",
)
dwell_ms: float = Field(
default=0.0,
description=(
"Total time (ms) the process was paused during the snapshot."
),
)
auto_resumed: bool = Field(
default=True,
description=(
"Whether threads paused for the snapshot were automatically"
" resumed."
),
)
summary: list[str] = Field(
default_factory=list,
description=(
"High-level diagnostic findings (blocked locks, sync IPCs, async"
" tasks, unserviced interrupts)."
),
)
threads: list[ClassifiedThread] = Field(
default_factory=list,
description=(
"All threads in the process classified by their current"
" wait/execution state."
),
)
async_tasks: list[AsyncTaskNode] = Field(
default_factory=list,
description=(
"Active async task trees in the process (from zxdb"
" async-backtrace)."
),
)
interrupt_handles: list[HandleEntry] = Field(
default_factory=list,
description="Open ZX_OBJ_TYPE_INTERRUPT handles in the process.",
)
channel_handles: list[HandleEntry] = Field(
default_factory=list,
description="Open ZX_OBJ_TYPE_CHANNEL handles in the process.",
)
port_handles: list[HandleEntry] = Field(
default_factory=list,
description="Open ZX_OBJ_TYPE_PORT handles in the process.",
)
class DiagnoseHangRequest(BaseRequest[DiagnoseHangResponse]):
"""Capture a hang/concurrency diagnostic snapshot of a process."""
command: Literal["diagnose-hang"] = COMMAND_NAME
pid: int | None = Field(
default=None,
description="Target process KOID (defaults to attached process).",
)
auto_resume: bool = Field(
default=True,
description=(
"Automatically resume threads paused during snapshot (guaranteed"
" via finally)."
),
)
response_type: ClassVar[Any] = DiagnoseHangResponse