blob: f11e066a1baf7bb354efe34f75963e29fb847c24 [file]
# 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.
"""Diagnostic analysis plugins for perf-analyze."""
import argparse
import io
from dataclasses import dataclass
from typing import Any, NoReturn, Protocol, Sequence, runtime_checkable
class PluginArgumentError(Exception):
"""Exception raised when plugin arguments are invalid."""
class PluginArgumentParser(argparse.ArgumentParser):
"""Custom ArgumentParser that raises PluginArgumentError instead of calling sys.exit."""
def error(self, message: str) -> NoReturn:
fp = io.StringIO()
self.print_usage(fp)
usage = fp.getvalue().strip()
raise PluginArgumentError(f"{usage}\nError: {message}")
@dataclass
class SectionResult:
"""A named section within a batch query or analysis plugin result.
Attributes:
name: The title or identifier of the section.
results: Optional list of row dictionaries representing tabular query data.
error: Optional error message string if the query/analysis failed.
note: Optional contextual note or diagnostic recommendation.
"""
name: str
results: Sequence[dict[str, Any]] | None = None
error: str | None = None
note: str | None = None
def to_dict(self) -> dict[str, Any]:
"""Converts the SectionResult to a dictionary representation."""
data: dict[str, Any] = {"name": self.name}
if self.note is not None:
data["note"] = self.note
if self.error is not None:
data["error"] = self.error
elif self.results is not None:
data["results"] = self.results
return data
@classmethod
def from_dict(cls, data: dict[str, Any]) -> SectionResult:
"""Creates a SectionResult from a dictionary representation."""
return cls(
name=data.get("name", ""),
results=data.get("results"),
error=data.get("error"),
note=data.get("note"),
)
@runtime_checkable
class AnalyzePlugin(Protocol):
"""Protocol defining the interface for performance analysis plugins."""
name: str
description: str
def analyze(
self,
remaining_args: Sequence[str],
trace_path: str,
cache: bool = True,
) -> Sequence[SectionResult]:
"""Executes the analysis specified by args on the given trace."""
...