| # 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. | |
| """Trace Processor wrapper utilities for Perfetto trace analysis.""" | |
| import contextlib | |
| import hashlib | |
| import importlib.resources | |
| import json | |
| import logging | |
| import os | |
| import re | |
| import ssl | |
| import subprocess | |
| import tempfile | |
| import urllib.error | |
| import urllib.parse | |
| import urllib.request | |
| import weakref | |
| from collections.abc import Iterator | |
| from types import TracebackType | |
| from typing import Any, Self | |
| import perfetto.trace_processor.api | |
| from perfetto.tools.download_trace import resolve_trace_url | |
| from perfetto.trace_processor.api import TraceProcessor as PerfettoTP | |
| from perfetto.trace_processor.platform import PlatformDelegate | |
| from perfetto.trace_uri_resolver import util as resolver_util | |
| from perfetto.trace_uri_resolver.path import PathUriResolver | |
| from perfetto.trace_uri_resolver.registry import ResolverRegistry | |
| from perfetto.trace_uri_resolver.resolver import TraceUriResolver | |
| from tp_shell.tp_server import TraceProcessorServer | |
| _LOGGER = logging.getLogger(__name__) | |
| DEFAULT_GCS_BUCKET = "fuchsia-trace-viewer-traces" | |
| DEFAULT_VIEWER_URL = "https://fuchsia-trace-viewer.corp.goog" | |
| DEFAULT_VIEWER_HOSTS = frozenset( | |
| { | |
| "fuchsia-trace-viewer.corp.goog", | |
| "fuchsia-trace-viewer-dev.corp.goog", | |
| "fuchsia-trace-viewer.corp.google.com", | |
| } | |
| ) | |
| RESULTDB_PRPC_ENDPOINT = ( | |
| "https://results.api.luci.app/prpc/luci.resultdb.v1.ResultDB/QueryArtifacts" | |
| ) | |
| _UI_VIEWPORT_PARAMS = frozenset( | |
| {"ts", "dur", "visStart", "visEnd", "query", "table", "origin"} | |
| ) | |
| _HTML_SIGNATURES = (b"<!doctype html", b"<html", b"<!--googleoff:") | |
| _HEX_RE = re.compile(r"^[0-9a-fA-F]+$") | |
| _FFX_CONFIG_CACHE: dict[str, str | None] = {} | |
| def _is_html_bytes(data: bytes) -> bool: | |
| """Returns True if the byte prefix begins with an HTML document or SSO login signature. | |
| Complexity: O(1) time and space (inspects at most the first 256 bytes). | |
| """ | |
| stripped = data[:256].lstrip().lower() | |
| return any(stripped.startswith(sig) for sig in _HTML_SIGNATURES) | |
| def _is_cached_file_valid_trace(file_path: str) -> bool: | |
| """Checks that a cached trace file is non-empty and not a cached HTML/SSO login page. | |
| Complexity: O(1) time and space (reads at most 256 bytes). | |
| """ | |
| if not os.path.exists(file_path) or os.path.getsize(file_path) <= 0: | |
| return False | |
| try: | |
| with open(file_path, "rb") as f: | |
| header = f.read(256) | |
| return len(header) > 0 and not _is_html_bytes(header) | |
| except OSError: | |
| return False | |
| def _query_ffx_config(key: str) -> str | None: | |
| """Queries `ffx config get <key>` once per process and memoizes the result.""" | |
| if key in _FFX_CONFIG_CACHE: | |
| return _FFX_CONFIG_CACHE[key] | |
| value: str | None = None | |
| try: | |
| proc = subprocess.run( | |
| ["ffx", "config", "get", key], | |
| capture_output=True, | |
| text=True, | |
| timeout=5, | |
| check=False, | |
| ) | |
| if proc.returncode == 0: | |
| cleaned = proc.stdout.strip().strip('"').strip() | |
| if cleaned and cleaned.lower() != "none": | |
| value = cleaned | |
| except (OSError, subprocess.SubprocessError) as e: | |
| _LOGGER.debug("ffx config get %s failed: %s", key, e) | |
| _FFX_CONFIG_CACHE[key] = value | |
| return value | |
| def _resolve_gcs_bucket( | |
| query_params: dict[str, list[str]] | None = None, | |
| ) -> str: | |
| """Resolves the target GCS bucket name from query params, env var, ffx config, or default.""" | |
| if query_params and "bucket" in query_params: | |
| for val in query_params["bucket"]: | |
| if val.strip(): | |
| return val.strip() | |
| env_bucket = os.environ.get("TRACE_BUCKET_NAME", "").strip() | |
| if env_bucket: | |
| return env_bucket | |
| cfg_bucket = _query_ffx_config("trace.gcs_bucket") | |
| if cfg_bucket: | |
| return cfg_bucket | |
| return DEFAULT_GCS_BUCKET | |
| def _is_fuchsia_trace_viewer_url( | |
| uri: str, check_ffx_config: bool = False | |
| ) -> bool: | |
| """Returns True if `uri` targets a Fuchsia Trace Viewer `/trace/...` or `/api/trace/...` endpoint.""" | |
| parsed = urllib.parse.urlsplit(uri) | |
| host = (parsed.hostname or "").lower() | |
| path = parsed.path or "" | |
| if not (path.startswith("/trace/") or path.startswith("/api/trace/")): | |
| return False | |
| if ( | |
| host in DEFAULT_VIEWER_HOSTS | |
| or host.endswith(".corp.goog") | |
| or host.endswith(".corp.google.com") | |
| ): | |
| return True | |
| env_viewer = os.environ.get("TRACE_VIEWER_URL", "").strip() | |
| if env_viewer: | |
| env_host = (urllib.parse.urlsplit(env_viewer).hostname or "").lower() | |
| if env_host and host == env_host: | |
| return True | |
| if check_ffx_config: | |
| cfg_viewer = _query_ffx_config("trace.viewer_url") | |
| if cfg_viewer: | |
| cfg_host = ( | |
| urllib.parse.urlsplit(cfg_viewer).hostname or "" | |
| ).lower() | |
| if cfg_host and host == cfg_host: | |
| return True | |
| return False | |
| def _normalize_cache_url(url: str) -> str: | |
| """Normalizes trace URLs before computing cache keys so deep links share the same cache file. | |
| Strips Perfetto UI viewport query parameters (`ts`, `dur`, `visStart`, `visEnd`, `query`, | |
| `table`, `origin`) and fragments, and canonicalizes `/api/trace/...` to `/trace/...`. | |
| Complexity: O(U) where U is the URL string length. | |
| """ | |
| if not _is_fuchsia_trace_viewer_url(url, check_ffx_config=False): | |
| return url | |
| parsed = urllib.parse.urlsplit(url) | |
| path = parsed.path | |
| if path.startswith("/api/trace/"): | |
| path = "/trace/" + path[len("/api/trace/") :] | |
| if len(path) > len("/trace/") and path.endswith("/"): | |
| path = path.rstrip("/") | |
| query_pairs = urllib.parse.parse_qsl(parsed.query, keep_blank_values=True) | |
| filtered_pairs = [ | |
| (k, v) for k, v in query_pairs if k not in _UI_VIEWPORT_PARAMS | |
| ] | |
| normalized_query = urllib.parse.urlencode(filtered_pairs) | |
| return urllib.parse.urlunsplit( | |
| ( | |
| parsed.scheme.lower(), | |
| parsed.netloc.lower(), | |
| path, | |
| normalized_query, | |
| "", | |
| ) | |
| ) | |
| def _get_gcp_access_token() -> str: | |
| """Obtains an OAuth2 access token via `gcloud` (ADC first, then standard gcloud auth).""" | |
| commands = [ | |
| ["gcloud", "auth", "application-default", "print-access-token"], | |
| ["gcloud", "auth", "print-access-token"], | |
| ] | |
| errors: list[str] = [] | |
| for cmd in commands: | |
| try: | |
| proc = subprocess.run( | |
| cmd, | |
| capture_output=True, | |
| text=True, | |
| timeout=10, | |
| check=False, | |
| ) | |
| if proc.returncode == 0 and proc.stdout.strip(): | |
| return proc.stdout.strip() | |
| errors.append(f"{' '.join(cmd)}: {proc.stderr.strip()}") | |
| except (OSError, subprocess.SubprocessError) as e: | |
| errors.append(f"{' '.join(cmd)}: {e}") | |
| raise RuntimeError( | |
| "Failed to obtain GCP access token for trace download. Please authenticate by running:\n" | |
| " gcloud auth application-default login\n" | |
| " gcloud auth login\n" | |
| f"Details: {'; '.join(errors)}" | |
| ) | |
| def _build_gcs_media_request( | |
| bucket: str, object_name: str, token: str | |
| ) -> urllib.request.Request: | |
| """Builds an authenticated GCS JSON API media download request.""" | |
| encoded_bucket = urllib.parse.quote(bucket, safe="") | |
| encoded_object = urllib.parse.quote(object_name.lstrip("/"), safe="") | |
| media_url = f"https://storage.googleapis.com/storage/v1/b/{encoded_bucket}/o/{encoded_object}?alt=media" | |
| return urllib.request.Request( | |
| media_url, | |
| headers={"Authorization": f"Bearer {token}"}, | |
| ) | |
| def _resolve_gcs_trace_object( | |
| bucket: str, trace_id: str, token: str, ssl_context: ssl.SSLContext | |
| ) -> str: | |
| """Resolves a Fuchsia Trace Viewer trace ID (short hex prefix, full hash, or path) to a GCS object name. | |
| Mirrors `storage.ResolveTraceID` in `fuchsia_trace_viewer`, querying at most 2 items | |
| (`maxResults=2&fields=items(name)`) for O(1) prefix resolution and collision detection. | |
| """ | |
| clean_id = trace_id.strip("/") | |
| if clean_id.lower().endswith(".fxt"): | |
| clean_id = clean_id[:-4] | |
| if clean_id.lower().startswith("sha256/"): | |
| clean_id = clean_id[7:] | |
| is_hex = bool(_HEX_RE.match(clean_id)) | |
| if is_hex: | |
| clean_id = clean_id.lower() | |
| if is_hex and 6 <= len(clean_id) < 64: | |
| prefix = f"sha256/{clean_id}" | |
| encoded_bucket = urllib.parse.quote(bucket, safe="") | |
| encoded_prefix = urllib.parse.quote(prefix, safe="") | |
| list_url = ( | |
| f"https://storage.googleapis.com/storage/v1/b/{encoded_bucket}/o" | |
| f"?prefix={encoded_prefix}&maxResults=2&fields=items(name)" | |
| ) | |
| req = urllib.request.Request( | |
| list_url, headers={"Authorization": f"Bearer {token}"} | |
| ) | |
| try: | |
| with urllib.request.urlopen( | |
| req, context=ssl_context, timeout=30 | |
| ) as resp: | |
| payload = json.loads(resp.read().decode("utf-8")) | |
| except urllib.error.HTTPError as e: | |
| if e.code in (401, 403): | |
| raise RuntimeError( | |
| f"GCS access denied (HTTP {e.code}) for bucket 'gs://{bucket}'. " | |
| "Ensure you have access and run `gcloud auth application-default login`." | |
| ) from e | |
| raise ValueError( | |
| f"Failed to list GCS prefix '{prefix}' in bucket '{bucket}' (HTTP {e.code})" | |
| ) from e | |
| items = payload.get("items") or [] | |
| if not items: | |
| raise FileNotFoundError( | |
| f"Trace '{trace_id}' (prefix '{prefix}') not found in gs://{bucket}" | |
| ) | |
| if len(items) > 1: | |
| names = ", ".join(item.get("name", "") for item in items) | |
| raise ValueError( | |
| f"Ambiguous trace prefix '{trace_id}' matched multiple objects in gs://{bucket}: {names}" | |
| ) | |
| resolved_name = items[0].get("name", "") | |
| if not resolved_name: | |
| raise FileNotFoundError( | |
| f"Trace '{trace_id}' resolved to empty object name in gs://{bucket}" | |
| ) | |
| return str(resolved_name) | |
| if is_hex and len(clean_id) == 64: | |
| return f"sha256/{clean_id}.fxt" | |
| return trace_id.lstrip("/") | |
| def _resolve_resultdb_trace_request( | |
| escaped_rdb_tail: str, token: str, ssl_context: ssl.SSLContext | |
| ) -> urllib.request.Request: | |
| """Resolves a `/trace/rdb/{invocation_id}/{escaped_test_id}/{artifact_path...}` route via LUCI ResultDB pRPC.""" | |
| parts = escaped_rdb_tail.strip("/").split("/", 2) | |
| if len(parts) != 3 or not all(parts): | |
| raise ValueError( | |
| f"Invalid ResultDB trace path '/trace/rdb/{escaped_rdb_tail}': " | |
| "expected /trace/rdb/<invocation_id>/<escaped_test_id>/<artifact_path>" | |
| ) | |
| raw_inv_id, escaped_test_id, raw_artifact_path = parts | |
| invocation_id = urllib.parse.unquote(raw_inv_id) | |
| if invocation_id.startswith("invocations/"): | |
| invocation_id = invocation_id[len("invocations/") :] | |
| test_id = urllib.parse.unquote(escaped_test_id) | |
| artifact_path = "/".join( | |
| urllib.parse.unquote(seg) for seg in raw_artifact_path.split("/") | |
| ) | |
| body = json.dumps( | |
| { | |
| "invocations": [f"invocations/{invocation_id}"], | |
| "predicate": { | |
| "testResultPredicate": { | |
| "testIdRegexp": re.escape(test_id), | |
| }, | |
| "artifactIdRegexp": re.escape(artifact_path), | |
| }, | |
| "pageSize": 1, | |
| } | |
| ).encode("utf-8") | |
| req = urllib.request.Request( | |
| RESULTDB_PRPC_ENDPOINT, | |
| data=body, | |
| headers={ | |
| "Authorization": f"Bearer {token}", | |
| "Content-Type": "application/json", | |
| "Accept": "application/json", | |
| }, | |
| method="POST", | |
| ) | |
| try: | |
| with urllib.request.urlopen( | |
| req, context=ssl_context, timeout=30 | |
| ) as resp: | |
| raw_text = resp.read().decode("utf-8") | |
| except urllib.error.HTTPError as e: | |
| if e.code in (401, 403): | |
| raise RuntimeError( | |
| f"ResultDB access denied (HTTP {e.code}) for invocation '{invocation_id}'. " | |
| "Please run `gcloud auth application-default login`." | |
| ) from e | |
| raise ValueError( | |
| f"Failed to query ResultDB artifact for invocation '{invocation_id}' (HTTP {e.code})" | |
| ) from e | |
| if raw_text.startswith(")]}'"): | |
| raw_text = raw_text[4:].lstrip("\r\n") | |
| data = json.loads(raw_text) | |
| artifacts = data.get("artifacts") or [] | |
| if not artifacts: | |
| raise FileNotFoundError( | |
| f"ResultDB artifact '{artifact_path}' not found for invocation '{invocation_id}', test '{test_id}'" | |
| ) | |
| fetch_url = artifacts[0].get("fetchUrl", "") | |
| if not fetch_url: | |
| raise ValueError( | |
| f"ResultDB artifact '{artifact_path}' is missing a signed fetchUrl" | |
| ) | |
| return urllib.request.Request(fetch_url) | |
| def resolve_fuchsia_trace_viewer_request( | |
| uri: str, ssl_context: ssl.SSLContext | |
| ) -> urllib.request.Request: | |
| """Resolves a Fuchsia Trace Viewer URL (`/trace/...` or `/api/trace/...`) to an authenticated download Request.""" | |
| parsed = urllib.parse.urlsplit(uri) | |
| path = parsed.path or "" | |
| if path.startswith("/api/trace/"): | |
| tail = path[len("/api/trace/") :] | |
| elif path.startswith("/trace/"): | |
| tail = path[len("/trace/") :] | |
| else: | |
| raise ValueError(f"Unsupported Fuchsia Trace Viewer path in URL: {uri}") | |
| tail = tail.strip("/") | |
| if not tail: | |
| raise ValueError( | |
| f"Missing trace identifier in Fuchsia Trace Viewer URL: {uri}" | |
| ) | |
| token = _get_gcp_access_token() | |
| if tail.startswith("rdb/"): | |
| return _resolve_resultdb_trace_request( | |
| tail[len("rdb/") :], token, ssl_context | |
| ) | |
| query_params = urllib.parse.parse_qs(parsed.query) | |
| bucket = _resolve_gcs_bucket(query_params) | |
| unquoted_id = urllib.parse.unquote(tail) | |
| object_name = _resolve_gcs_trace_object( | |
| bucket, unquoted_id, token, ssl_context | |
| ) | |
| return _build_gcs_media_request(bucket, object_name, token) | |
| def _validate_and_stream_response( | |
| response: Any, source_url: str | |
| ) -> Iterator[bytes]: | |
| """Validates that an HTTP response is not an HTML/SSO login page and streams its bytes.""" | |
| headers = getattr(response, "headers", None) | |
| if headers is not None and hasattr(headers, "get"): | |
| content_type = headers.get("Content-Type", "") | |
| if isinstance(content_type, str) and content_type.lower().startswith( | |
| "text/html" | |
| ): | |
| response.close() | |
| raise ValueError( | |
| f"URL '{source_url}' returned an HTML page (Content-Type: {content_type}) " | |
| "instead of a binary trace file (possible Corp SSO login redirect)." | |
| ) | |
| gen = resolver_util.read_generator(response) | |
| first_chunk = next(gen, b"") | |
| if _is_html_bytes(first_chunk): | |
| response.close() | |
| raise ValueError( | |
| f"URL '{source_url}' returned an HTML document instead of a binary trace file " | |
| "(possible Corp SSO login redirect)." | |
| ) | |
| def _stream() -> Iterator[bytes]: | |
| if first_chunk: | |
| yield first_chunk | |
| yield from gen | |
| return _stream() | |
| class GsUriResolver(TraceUriResolver): | |
| """URI Resolver that streams trace data directly from `gs://<bucket>/<object>` URIs.""" | |
| PREFIX = "gs" | |
| def __init__(self, uri: str) -> None: | |
| self.uri = uri | |
| @classmethod | |
| # TODO(https://fxbug.dev/571891548): decorate with typing.override when able. | |
| def from_trace_uri(cls, uri: str) -> Self: | |
| return cls(uri) | |
| # TODO(https://fxbug.dev/571891548): decorate with typing.override when able. | |
| def resolve(self) -> list[TraceUriResolver.Result]: | |
| parsed = urllib.parse.urlsplit(self.uri) | |
| bucket = parsed.netloc.strip() | |
| object_name = urllib.parse.unquote(parsed.path.lstrip("/")) | |
| if not bucket or not object_name: | |
| raise ValueError( | |
| f"Invalid GCS URI '{self.uri}': expected gs://<bucket>/<object_path>" | |
| ) | |
| context = ssl._create_unverified_context() | |
| token = _get_gcp_access_token() | |
| req = _build_gcs_media_request(bucket, object_name, token) | |
| response = urllib.request.urlopen(req, context=context, timeout=120) | |
| return [ | |
| TraceUriResolver.Result( | |
| trace=_validate_and_stream_response(response, self.uri), | |
| metadata={"_url": req.full_url}, | |
| ) | |
| ] | |
| class HttpUriResolver(TraceUriResolver): | |
| """URI Resolver that streams trace data from HTTP/HTTPS endpoints and permalinks.""" | |
| PREFIX = "http" | |
| def __init__(self, uri: str) -> None: | |
| self.uri = uri | |
| @classmethod | |
| # TODO(https://fxbug.dev/571891548): decorate with typing.override when able. | |
| def from_trace_uri(cls, uri: str) -> Self: | |
| return cls(uri) | |
| # TODO(https://fxbug.dev/571891548): decorate with typing.override when able. | |
| def resolve(self) -> list[TraceUriResolver.Result]: | |
| context = ssl._create_unverified_context() | |
| if "perfetto.dev" in self.uri: | |
| req_or_url: str | urllib.request.Request = resolve_trace_url( | |
| self.uri | |
| ) | |
| resolved_url = req_or_url | |
| elif _is_fuchsia_trace_viewer_url(self.uri, check_ffx_config=True): | |
| req_or_url = resolve_fuchsia_trace_viewer_request(self.uri, context) | |
| resolved_url = req_or_url.full_url | |
| else: | |
| req_or_url = self.uri | |
| resolved_url = self.uri | |
| # Add a default timeout as a backstop to avoid permanently blocking when loading | |
| # the trace file. | |
| response = urllib.request.urlopen( | |
| req_or_url, context=context, timeout=120 | |
| ) | |
| return [ | |
| TraceUriResolver.Result( | |
| trace=_validate_and_stream_response(response, self.uri), | |
| metadata={"_url": resolved_url}, | |
| ) | |
| ] | |
| class HttpsUriResolver(HttpUriResolver): | |
| PREFIX = "https" | |
| class FuchsiaPlatformDelegate(PlatformDelegate): | |
| """PlatformDelegate that points directly to the host's prebuilt trace_processor_shell binary. | |
| This delegate is used to override the default PlatformDelegate in the | |
| third_party Perfetto Python SDK, ensuring that it uses our prebuilt, in-tree | |
| version of trace_processor_shell instead of trying to download or resolve it | |
| from the network or default paths. | |
| """ | |
| host_tp_shell_path: str | |
| def __init__(self, host_tp_shell_path: str) -> None: | |
| super().__init__() | |
| self.host_tp_shell_path = host_tp_shell_path | |
| # TODO(https://fxbug.dev/571891548): decorate with typing.override when able. | |
| def get_shell_path( | |
| self, bin_path: str | None = None, fetch_latest: bool = False | |
| ) -> str: | |
| return self.host_tp_shell_path | |
| # TODO(https://fxbug.dev/571891548): decorate with typing.override when able. | |
| def get_resource(self, file: str) -> bytes: | |
| return ( | |
| importlib.resources.files("perfetto.trace_processor") | |
| .joinpath(file) | |
| .read_bytes() | |
| ) | |
| # TODO(https://fxbug.dev/571891548): decorate with typing.override when able. | |
| def default_resolver_registry(self) -> ResolverRegistry: | |
| return ResolverRegistry( | |
| resolvers=[ | |
| PathUriResolver, | |
| GsUriResolver, | |
| HttpUriResolver, | |
| HttpsUriResolver, | |
| ] | |
| ) | |
| def _release(resources: contextlib.ExitStack) -> None: | |
| """Releases a PerfettoTraceProcessor's resources, logging any failure.""" | |
| _LOGGER.info("Tearing down Perfetto TraceProcessor shell process...") | |
| try: | |
| resources.close() | |
| except Exception as e: | |
| _LOGGER.error(f"Error tearing down trace processor: {e}") | |
| class PerfettoTraceProcessor: | |
| """A wrapper around Perfetto's official Python TraceProcessor API. | |
| This class provides a way to interact with Perfetto's TraceProcessor API, | |
| handling the setup and teardown of the trace_processor_shell backend. | |
| The trace file is parsed only once, and backend process is torn down | |
| when the processor is closed. | |
| Attributes: | |
| trace_path: Path to the trace file to ingest. | |
| tp_shell_path: Path to the trace_processor_shell binary. | |
| debug: If True, prints SQL queries. | |
| """ | |
| trace_path: str | |
| tp_shell_path: str | |
| debug: bool | |
| _tp: PerfettoTP | |
| _finalizer: weakref.finalize[Any, Any] | |
| def __init__( | |
| self, | |
| trace_path: str, | |
| tp_shell_path: str | None = None, | |
| debug: bool = False, | |
| cache: bool = True, | |
| ) -> None: | |
| """Initializes PerfettoTraceProcessor. | |
| Args: | |
| trace_path: Path to the trace file to ingest. | |
| tp_shell_path: Optional path to the trace_processor_shell binary. | |
| debug: If True, prints SQL queries. | |
| cache: If True and trace_path is a URL, reuses local cached trace if valid; | |
| if False, forces a fresh download overwriting the cache entry (default: True). | |
| """ | |
| self.debug = debug | |
| # Everything this object owns, released in reverse order by close(): | |
| # the client connection, then the shell process, then the extracted | |
| # shell binary. | |
| resources = contextlib.ExitStack() | |
| try: | |
| self.tp_shell_path = self._find_tp_shell(tp_shell_path, resources) | |
| delegate = FuchsiaPlatformDelegate(self.tp_shell_path) | |
| self.trace_path = self._resolve_trace_path( | |
| trace_path, delegate, cache | |
| ) | |
| # The Perfetto client loads its protos and URI resolvers through | |
| # the platform delegate. | |
| perfetto.trace_processor.api.PLATFORM_DELEGATE = lambda: delegate | |
| _LOGGER.info( | |
| f"Initializing Perfetto TraceProcessor for trace: {self.trace_path}" | |
| ) | |
| server = resources.enter_context( | |
| TraceProcessorServer(self.tp_shell_path, self.trace_path) | |
| ) | |
| self._tp = resources.enter_context( | |
| contextlib.closing(PerfettoTP(remote=server.socket_path)) | |
| ) | |
| except BaseException: | |
| resources.close() | |
| raise | |
| # Releases the resources even if close() is never called. | |
| self._finalizer = weakref.finalize(self, _release, resources) | |
| @staticmethod | |
| def _find_tp_shell( | |
| tp_shell_path: str | None, resources: contextlib.ExitStack | |
| ) -> str: | |
| """Returns the absolute path to the trace_processor_shell binary. | |
| Without an explicit path, extracts the binary packaged with this | |
| library, registering its cleanup with `resources`. | |
| """ | |
| if tp_shell_path is None: | |
| resource = importlib.resources.files("tp_shell.bin").joinpath( | |
| "trace_processor_shell" | |
| ) | |
| try: | |
| # Inside a .pyz archive this extracts the binary to a | |
| # temporary file that is deleted when `resources` is closed. | |
| tp_shell_path = str( | |
| resources.enter_context( | |
| importlib.resources.as_file(resource) | |
| ) | |
| ) | |
| except Exception as e: | |
| raise FileNotFoundError( | |
| "trace_processor_shell was not found in the packaged resources. " | |
| "The binary must either be explicitly specified or packaged as a data source dependency." | |
| ) from e | |
| # Extraction from a ZIP archive does not preserve the executable bit. | |
| os.chmod(tp_shell_path, 0o755) | |
| tp_shell_path = os.path.abspath(tp_shell_path) | |
| if not os.path.exists(tp_shell_path): | |
| raise FileNotFoundError( | |
| f"Trace processor shell not found: {tp_shell_path}" | |
| ) | |
| return tp_shell_path | |
| @classmethod | |
| def _resolve_trace_path( | |
| cls, trace_path: str, delegate: PlatformDelegate, cache: bool | |
| ) -> str: | |
| """Returns an absolute local path for `trace_path`, downloading URLs.""" | |
| if trace_path.startswith(("http://", "https://", "gs://")): | |
| return os.path.abspath( | |
| cls._resolve_and_cache_url( | |
| trace_path, | |
| delegate.default_resolver_registry(), | |
| force_refresh=not cache, | |
| ) | |
| ) | |
| trace_path = os.path.abspath(trace_path) | |
| if not os.path.exists(trace_path): | |
| raise FileNotFoundError(f"Trace file not found: {trace_path}") | |
| return trace_path | |
| def run_query(self, query: str) -> list[dict[str, Any]]: | |
| """Runs a SQL query against the trace and returns the result as a list of dicts.""" | |
| if not hasattr(self, "_finalizer") or not self._finalizer.alive: | |
| raise RuntimeError("Trace processor is closed.") | |
| if self.debug: | |
| _LOGGER.debug( | |
| f"--- DEBUG SQL QUERY ---\n{query.strip()}\n-----------------------" | |
| ) | |
| try: | |
| result_iterator = self._tp.query(query) | |
| # Row.__dict__ on instance contains exactly the dynamic attributes (columns) | |
| return [row.__dict__ for row in result_iterator] | |
| except Exception as e: | |
| _LOGGER.error(f"Error running query: {e}") | |
| raise | |
| def query_rows( | |
| self, query: str | |
| ) -> tuple[tuple[str, ...], Iterator[tuple[Any, ...]]]: | |
| """Runs a SQL query against the trace and returns (column_names, row_iterator). | |
| Yields rows lazily as tuples of typed values (int, float, str, bytes, None) | |
| without allocating full materialized result lists or intermediate dicts. | |
| """ | |
| if not hasattr(self, "_finalizer") or not self._finalizer.alive: | |
| raise RuntimeError("Trace processor is closed.") | |
| if self.debug: | |
| _LOGGER.debug( | |
| f"--- DEBUG SQL QUERY ---\n{query.strip()}\n-----------------------" | |
| ) | |
| try: | |
| result_iterator = self._tp.query(query) | |
| columns = tuple(result_iterator.column_names) | |
| def row_gen() -> Iterator[tuple[Any, ...]]: | |
| for row in result_iterator: | |
| yield tuple(getattr(row, col) for col in columns) | |
| return columns, row_gen() | |
| except Exception as e: | |
| _LOGGER.error(f"Error running query: {e}") | |
| raise | |
| def get_tables(self) -> set[str]: | |
| """Returns the set of table and view names available in the trace database.""" | |
| rows = self.run_query( | |
| "SELECT name FROM sqlite_master WHERE type IN ('table', 'view')" | |
| ) | |
| return {row["name"] for row in rows} | |
| def __enter__(self) -> Self: | |
| return self | |
| def __exit__( | |
| self, | |
| exc_type: type[BaseException] | None, | |
| exc_val: BaseException | None, | |
| exc_tb: TracebackType | None, | |
| ) -> None: | |
| self.close() | |
| def close(self) -> None: | |
| """Tears down the trace processor shell process.""" | |
| if hasattr(self, "_finalizer") and self._finalizer.alive: | |
| self._finalizer() | |
| @staticmethod | |
| def _resolve_and_cache_url( | |
| url: str, | |
| registry: ResolverRegistry, | |
| force_refresh: bool = False, | |
| ) -> str: | |
| normalized_url = _normalize_cache_url(url) | |
| cache_key = hashlib.sha256(normalized_url.encode("utf-8")).hexdigest() | |
| cache_dir = os.path.join(tempfile.gettempdir(), "perf_analyze_cache") | |
| cached_file = os.path.join(cache_dir, f"{cache_key}.fxt") | |
| if not force_refresh and os.path.exists(cached_file): | |
| if _is_cached_file_valid_trace(cached_file): | |
| _LOGGER.info("Using cached trace: %s", cached_file) | |
| return cached_file | |
| _LOGGER.warning( | |
| "Evicting invalid or HTML-poisoned cached trace file: %s", | |
| cached_file, | |
| ) | |
| try: | |
| os.remove(cached_file) | |
| except OSError: | |
| pass | |
| results = registry.resolve(url) | |
| if not results: | |
| raise ValueError(f"Could not resolve URL: {url}") | |
| os.makedirs(cache_dir, exist_ok=True) | |
| _LOGGER.info( | |
| "Downloading trace URL %s to cache %s...", url, cached_file | |
| ) | |
| temp_file = f"{cached_file}.tmp.{os.getpid()}" | |
| try: | |
| with open(temp_file, "wb") as out: | |
| for chunk in results[0].generator: | |
| out.write(chunk) | |
| if not _is_cached_file_valid_trace(temp_file): | |
| raise ValueError( | |
| f"Downloaded trace from '{url}' is empty or contains an HTML document " | |
| "(possible Corp SSO login redirect)." | |
| ) | |
| os.replace(temp_file, cached_file) | |
| except Exception: | |
| if os.path.exists(temp_file): | |
| os.remove(temp_file) | |
| raise | |
| return cached_file |