feat: add import profiler tool with dynamic loaded lines code volume … (#17467)

###  Overview
This PR introduces `profiler.py`, a zero-dependency, process-isolated
import profiling tool designed to benchmark Python SDK modules with
extreme precision and zero dynamic cache interference.

To evaluate authentic import initialization overhead without the
"observer effect", the profiler leverages a Master/Worker architecture.
The master orchestrator executes each benchmark iteration inside a
completely isolated, dynamically spawned subprocess. By bypassing
Python's `sys.modules` cache and sweeping disk-level `__pycache__`
directories, the tool guarantees a 100% authentic "cold-start"
evaluation every time.

### Key Telemetry Vectors & Features
- **Initialization Latency (ms):** Measured at high resolution natively,
securely omitting VM startup skew.
- **Physical Memory Deltas (RAM):** Employs a dual-strategy approach
tracking both internal block allocator shifts via `tracemalloc`
(cross-platform), and pure OS-level physical memory footprints via
`/proc/self/statm` deltas (Linux RSS) to catch heavy C/C++ backend
extensions like `protobuf`.
- **Deterministic Code Volume (LOC):** Tracks the physical delta of
`sys.modules` across the import window, traversing disk paths to
aggregate the exact number of physical Lines of Code (LOC) injected into
the interpreter.
- **CPU Pinning:** Binds worker processes to a single CPU core via
`taskset` on Linux to eliminate OS-level context-switching jitter across
iterations.
- **Diagnostic Tooling:** Supports one-off diagnostic tracing for
bottleneck discovery via `--trace` (`-X importtime`) and `--cprofile`.

*A comprehensive breakdown of the architecture, data pipeline, and trace
log analysis is documented in
[`scripts/import_profiler/documentation.md`](./scripts/import_profiler/documentation.md).*

### Related Links
- **Design Doc:** `
[go/sdk-performance-design](http://goto.google.com/sdk-performance-design)`
- **Related Issue:**
googleapis/python-aiplatform#4749

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: hebaalazzeh

scripts/import_profiler/documentation.md

@@ -0,0 +1,72 @@
+# Python SDK Import Profiler: Documentation & Breakdown
+
+This document provides a comprehensive guide to the `import_profiler` scripts, directory files, and how to analyze the generated import trace logs to target optimization areas.
+
+---
+
+## 1. File Guide & Directory Structure
+The profiling tool is located in the [scripts/import_profiler/](./) directory:
+
+* **[profiler.py](./profiler.py)**: The core executable script. It is designed as a single-file, self-spawning harness that performs process-isolated importing benchmarks and generates trace logs.
+
+---
+
+## 2. Profiler Mechanism (`profiler.py`)
+
+**Objective**
+The Profiler functions as a process-isolated verification harness designed to capture before-and-after metrics across three distinct vectors: Initialization Latency (ms), Peak Memory Usage (MB), and Dynamic Code Volume (Loaded Modules & Lines of Code).
+
+**Usage**
+
+Run this command to collect the metrics:
+```bash
+python profiler.py --module <target_module> --iterations <N>
+```
+
+**Expected Output**
+```text
+--- Results for <target_module> (<N> iterations) ---
+Code Volume (Deterministic):
+  Loaded Modules: <count>
+  Loaded Lines:   <count>
+Time (ms):
+  P50 (Median): <time>
+  P90:          <time>
+  P99:          <time>
+RAM (MB):
+  P50 (Median): <memory>
+  P90:          <memory>
+  P99:          <memory>
+```
+
+---
+
+## 3. How to Interpret Python `-X importtime` Trace Logs
+When running with the `--trace` flag, the script captures the raw stderr trace produced by Python's `-X importtime` option. The trace looks like this:
+
+```
+import time: self [us] | cumulative | imported package
+import time:       536 |        536 |   _io
+import time:      1077 |       2385 | _frozen_importlib_external
+import time:    773659 |     793010 |                   google.cloud.compute_v1.types.compute
+```
+
+### Explaining the Fields:
+1. **`self [us]` (Microseconds):** The time spent importing the module itself, *excluding* any time spent importing its child dependencies.
+2. **`cumulative` (Microseconds):** The total time spent loading the module *including* all nested imports. This represents the total wait time introduced by this line.
+3. **Hierarchy Indentation:** Indented packages are sub-imports triggered by the parent module. A package with higher indentation is loaded deeper in the call stack.
+
+---
+
+## 4. Execution Reference
+Ensure you are in the correct pyenv virtual environment where packages are installed in editable mode:
+
+```bash
+# 1. Run the profiler to get baseline/optimized outcomes (e.g. 5 iterations)
+PYENV_VERSION=py312 python profiler.py --module=google.cloud.compute --iterations=5
+PYENV_VERSION=py312 python profiler.py --module=google.cloud.aiplatform --iterations=5
+
+# 2. Run the profiler to generate trace logs
+PYENV_VERSION=py312 python profiler.py --module=google.cloud.compute --trace
+PYENV_VERSION=py312 python profiler.py --module=google.cloud.aiplatform --trace
+```