taolib.harness.devtools.profiler

性能剖析器 - 节点耗时、LLM 延迟、Token 吞吐与内存峰值的统一采集。

提供 PerformanceProfiler 作为入口，搭配 profiled() 装饰器 对函数级别打点，最后由 HotspotAnalyzer 识别耗时热点。

Classes

HotspotAnalyzer	热点分析器 - 从剖析样本中识别最耗时的标签。
HotspotEntry	热点条目。
PerformanceProfiler	性能剖析器。
ProfileConfig	剖析配置。
ProfileResult	剖析结果。
ProfileSample	单条耗时打点。

Functions

profiled(...)

函数装饰器：自动向当前活跃剖析器登记耗时。

Module Contents

class taolib.harness.devtools.profiler.HotspotAnalyzer(*, top_k: int = 5)

热点分析器 - 从剖析样本中识别最耗时的标签。

analyze(samples_or_result: collections.abc.Sequence[ProfileSample] | ProfileResult) → list[HotspotEntry]

聚合并按总耗时降序返回 top_k 个热点。

class taolib.harness.devtools.profiler.HotspotEntry

Bases: pydantic.BaseModel

热点条目。

category: str

count: int

label: str

max_seconds: float

mean_seconds: float

model_config

share: float

total_seconds: float

class taolib.harness.devtools.profiler.PerformanceProfiler(*, config: ProfileConfig | None = None)

性能剖析器。

ameasure(label: str, *, category: str = 'node', metadata: collections.abc.Mapping[str, Any] | None = None, tokens: collections.abc.Mapping[str, float] | None = None) → PerformanceProfiler

异步打点上下文。

async aprofile(execution: collections.abc.Callable[[], collections.abc.Awaitable[R]], *, label: str = 'execution') → tuple[R, ProfileResult]

异步剖析单次执行。

classmethod current() → PerformanceProfiler | None

返回栈顶的活跃剖析器（若存在）。

measure(label: str, *, category: str = 'node', metadata: collections.abc.Mapping[str, Any] | None = None, tokens: collections.abc.Mapping[str, float] | None = None) → Any

同步打点上下文。

profile(execution: collections.abc.Callable[[], R], *, label: str = 'execution') → tuple[R, ProfileResult]

同步剖析单次执行。

record_event(label: str, duration_seconds: float, *, category: str = 'node', metadata: collections.abc.Mapping[str, Any] | None = None, tokens: collections.abc.Mapping[str, float] | None = None) → None

直接登记一条已知耗时的打点。

report() → ProfileResult

生成当前已收集样本的报告（不停止剖析）。

session() → Any

上下文管理器：with profiler.session(): ...。

start() → None

启动剖析（清空缓冲并开启内存追踪）。

stop() → ProfileResult

停止剖析并生成结果。

class taolib.harness.devtools.profiler.ProfileConfig

Bases: pydantic.BaseModel

剖析配置。

collect_llm: bool = True

collect_memory: bool = True

collect_tokens: bool = True

model_config

output_path: pathlib.Path | None = None

sample_rate: float

class taolib.harness.devtools.profiler.ProfileResult

Bases: pydantic.BaseModel

剖析结果。

finished_at: float

llm_call_count: int = 0

llm_latency_p95: float = 0.0

memory_peak_bytes: int = 0

model_config

profile_id: str

property sample_count: int

打点总数。

samples: list[ProfileSample]

started_at: float

token_throughput: float = 0.0

total_duration_seconds: float = 0.0

class taolib.harness.devtools.profiler.ProfileSample

Bases: pydantic.BaseModel

单条耗时打点。

category: str = 'node'

duration_seconds: float

finished_at: float

label: str

metadata: dict[str, Any]

model_config

started_at: float

tokens: dict[str, float]

taolib.harness.devtools.profiler.profiled(label: str | None = None, *, category: str = 'node') → collections.abc.Callable[[collections.abc.Callable[P, R]], collections.abc.Callable[P, R]]

函数装饰器：自动向当前活跃剖析器登记耗时。

若调用时没有活跃剖析器则等同于直接调用。