tensorboard-plugin-profile 2.22.2__py3-none-win_amd64.whl

tensorboard_plugin_profile/__init__.py

@@ -0,0 +1,22 @@
+# Copyright 2025 The XProf Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the 'License');
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an 'AS IS' BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Passthrough __init__.py pointing to xprof."""
+
+from xprof import convert
+from xprof import profile_plugin
+from xprof import profile_plugin_loader
+from xprof import protobuf
+from xprof import server
+from xprof import version

tensorboard_plugin_profile-2.22.2.dist-info/METADATA

@@ -0,0 +1,346 @@
+Metadata-Version: 2.4
+Name: tensorboard_plugin_profile
+Version: 2.22.2
+Summary: XProf Profiler Plugin
+Home-page: https://github.com/openxla/xprof
+Author: Google Inc.
+Author-email: packages@tensorflow.org
+License: Apache 2.0
+Keywords: jax pytorch xla tensorflow tensorboard xprof profile plugin
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >= 3.10
+Description-Content-Type: text/markdown
+Requires-Dist: xprof==2.22.2
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# XProf (+ Tensorboard Profiler Plugin)
+
+XProf offers a number of tools to analyse and visualize the
+performance of your model across multiple devices. Some of the tools include:
+
+*   **Overview**: A high-level overview of the performance of your model. This
+    is an aggregated overview for your host and all devices. It includes:
+    *   Performance summary and breakdown of step times.
+    *   A graph of individual step times.
+    *   High level details of the run environment.
+*   **Trace Viewer**: Displays a timeline of the execution of your model that shows:
+    *   The duration of each op.
+    *   Which part of the system (host or device) executed an op.
+    *   The communication between devices.
+*   **Memory Profile Viewer**: Monitors the memory usage of your model.
+*   **Graph Viewer**: A visualization of the graph structure of HLOs of your model.
+
+To learn more about the various XProf tools, check out the [XProf documentation](https://openxla.org/xprof)
+
+## Demo
+First time user? Come and check out this [Colab Demo](https://docs.jaxstack.ai/en/latest/JAX_for_LLM_pretraining.html).
+
+## Quick Start
+
+### Prerequisites
+
+* xprof >= 2.20.0
+* (optional) TensorBoard >= 2.20.0
+
+Note: XProf requires access to the Internet to load the [Google Chart library](https://developers.google.com/chart/interactive/docs/basic_load_libs#basic-library-loading).
+Some charts and tables may be missing if you run XProf entirely offline on
+your local machine, behind a corporate firewall, or in a datacenter.
+
+If you use Google Cloud to run your workloads, we recommend the
+[xprofiler tool](https://github.com/AI-Hypercomputer/cloud-diagnostics-xprof).
+It provides a streamlined profile collection and viewing experience using VMs
+running XProf.
+
+### Installation
+
+To get the most recent release version of XProf, install it via pip:
+
+```
+$ pip install xprof
+```
+
+or with TensorBoard:
+
+```
+$ pip install xprof tensorboard
+```
+
+*Note: For Python 3.12+ users, if you encounter `ModuleNotFoundError: No module
+named 'pkg_resources'`, install an older version of setuptools:*
+
+```
+pip install "setuptools<70"
+```
+
+## Running XProf
+
+XProf can be launched as a standalone server or used as a plugin within
+TensorBoard. For large-scale use, it can be deployed in a distributed mode with
+separate aggregator and worker instances ([more details on it later in the
+doc](#distributed-profiling)).
+
+### Command-Line Arguments
+
+When launching XProf from the command line, you can use the following arguments:
+
+*   **`logdir`** (optional): The directory containing XProf profile data (files
+    ending in `.xplane.pb`). This can be provided as a positional argument or
+    with `-l` or `--logdir`. If provided, XProf will load and display profiles
+    from this directory. If omitted, XProf will start without loading any
+    profiles, and you can dynamically load profiles using `session_path` or
+    `run_path` URL parameters, as described in the [Log Directory
+    Structure](#log-directory-structure) section.
+*   **`-p <port>`**, **`--port <port>`**: The port for the XProf web server.
+    Defaults to `8791`.
+*   **`-gp <grpc_port>`**, **`--grpc_port <grpc_port>`**: The port for the gRPC
+    server used for distributed processing. Defaults to `50051`. This must be
+    different from `--port`.
+*   **`-wsa <addresses>`**, **`--worker_service_address <addresses>`**: A
+    comma-separated list of worker addresses (e.g., `host1:50051,host2:50051`)
+    for distributed processing. Defaults to to `0.0.0.0:<grpc_port>`.
+*   **`-hcpb`**, **`--hide_capture_profile_button`**: If set, hides the 'Capture
+    Profile' button in the UI.
+
+### Standalone
+
+If you have profile data in a directory (e.g., `profiler/demo`), you can view it
+by running:
+
+```
+$ xprof profiler/demo --port=6006
+```
+
+Or with the optional flag:
+
+```
+$ xprof --logdir=profiler/demo --port=6006
+```
+
+### With TensorBoard
+
+If you have TensorBoard installed, you can run:
+
+```
+$ tensorboard --logdir=profiler/demo
+```
+
+If you are behind a corporate firewall, you may need to include the `--bind_all`
+tensorboard flag.
+
+Go to `localhost:6006/#profile` of your browser, you should now see the demo
+overview page show up.
+Congratulations! You're now ready to capture a profile.
+
+### Log Directory Structure
+
+When using XProf, profile data must be placed in a specific directory structure.
+XProf expects `.xplane.pb` files to be in the following path:
+
+```
+<log_dir>/plugins/profile/<session_name>/
+```
+
+*   `<log_dir>`: This is the root directory that you supply to `tensorboard
+    --logdir`.
+*   `plugins/profile/`: This is a required subdirectory.
+*   `<session_name>/`: Each subdirectory inside `plugins/profile/` represents a
+    single profiling session. The name of this directory will appear in the
+    TensorBoard UI dropdown to select the session.
+
+**Example:**
+
+If your log directory is structured like this:
+
+```
+/path/to/your/log_dir/
+└── plugins/
+    └── profile/
+        ├── my_experiment_run_1/
+        │   └── host0.xplane.pb
+        └── benchmark_20251107/
+            └── host1.xplane.pb
+```
+
+You would launch TensorBoard with:
+
+```bash
+tensorboard --logdir /path/to/your/log_dir/
+```
+
+The runs `my_experiment_run_1` and `benchmark_20251107` will be available in the
+"Sessions" tab of the UI.
+
+You can also dynamically load sessions from a GCS bucket or local filesystem by
+passing URL parameters when loading XProf in your browser. This method works
+whether or not you provided a `logdir` at startup and is useful for viewing
+profiles from various locations without restarting XProf.
+
+For example, if you start XProf with no log directory:
+
+```bash
+xprof
+```
+
+You can load sessions using the following URL parameters.
+
+Assume you have profile data stored on GCS or locally, structured like this:
+
+```
+gs://your-bucket/profile_runs/
+├── my_experiment_run_1/
+│   ├── host0.xplane.pb
+│   └── host1.xplane.pb
+└── benchmark_20251107/
+    └── host0.xplane.pb
+```
+
+There are two URL parameters you can use:
+
+*   **`session_path`**: Use this to load a *single* session directly. The path
+    should point to a directory containing `.xplane.pb` files for one session.
+
+    *   GCS Example:
+        `http://localhost:8791/?session_path=gs://your-bucket/profile_runs/my_experiment_run_1`
+    *   Local Path Example:
+                `http://localhost:8791/?session_path=/path/to/profile_runs/my_experiment_run_1`
+    *   Result: XProf will load the `my_experiment_run_1`
+                        session, and you will see its data in the UI.
+
+*   **`run_path`**: Use this to point to a directory that contains *multiple*
+    session directories.
+
+    *   GCS Example:
+        `http://localhost:8791/?run_path=gs://your-bucket/profile_runs/`
+    *   Local Path Example:
+        `http://localhost:8791/?run_path=/path/to/profile_runs/`
+    *   Result: XProf will list all session directories found under `run_path`
+        (i.e., `my_experiment_run_1` and `benchmark_20251107`) in the "Sessions"
+    dropdown in the UI, allowing you to switch between them.
+
+**Loading Precedence**
+
+If multiple sources are provided, XProf uses the following order of precedence
+to determine which profiles to load:
+
+1.  **`session_path`** URL parameter
+2.  **`run_path`** URL parameter
+3.  **`logdir`** command-line argument
+
+### Distributed Profiling
+
+XProf supports distributed profile processing by using an aggregator that
+distributes work to multiple XProf workers. This is useful for processing large
+profiles or handling multiple users.
+
+**Note**: Currently, distributed processing only benefits the following tools:
+`overview_page`, `framework_op_stats`, `input_pipeline`, and `pod_viewer`.
+
+**Note**: The ports used in these examples (`6006` for the aggregator HTTP
+server, `9999` for the worker HTTP server, and `50051` for the worker gRPC
+server) are suggestions and can be customized.
+
+**Worker Node**
+
+Each worker node should run XProf with a gRPC port exposed so it can receive
+processing requests. You should also hide the capture button as workers are not
+meant to be interacted with directly.
+
+```
+$ xprof --grpc_port=50051 --port=9999 --hide_capture_profile_button
+```
+
+**Aggregator Node**
+
+The aggregator node runs XProf with the `--worker_service_address` flag pointing
+to all available workers. Users will interact with aggregator node's UI.
+
+```
+$ xprof --worker_service_address=<worker1_ip>:50051,<worker2_ip>:50051 --port=6006 --logdir=profiler/demo
+```
+
+Replace `<worker1_ip>, <worker2_ip>` with the addresses of your worker machines.
+Requests sent to the aggregator on port 6006 will be distributed among the
+workers for processing.
+
+For deploying a distributed XProf setup in a Kubernetes environment, see
+[Kubernetes Deployment Guide](docs/kubernetes_deployment.md).
+
+## Nightlies
+
+Every night, a nightly version of the package is released under the name of
+`xprof-nightly`. This package contains the latest changes made by the XProf
+developers.
+
+To install the nightly version of profiler:
+
+```
+$ pip uninstall xprof tensorboard-plugin-profile
+$ pip install xprof-nightly
+```
+
+## Building from source
+
+If the pip packages don't work for you, you can build XProf from source using
+Bazel.
+
+**1. Set up Bazel**
+
+Bazel is the build system used for XProf. Bazelisk is a wrapper for Bazel that
+simplifies Bazel version management. Download the appropriate `.deb` package for
+your system from the
+[Bazelisk releases page](https://github.com/bazelbuild/bazelisk/releases) and
+install the downloaded package:
+
+```
+sudo apt install ~/Downloads/bazelisk-amd64.deb
+```
+
+**2. Obtain the Repository**
+
+Clone the XProf GitHub repository to your local machine:
+
+```
+git clone https://github.com/openxla/xprof.git
+cd xprof
+```
+
+**3. Build the Project**
+
+Build the pip Package: Use Bazel to build the XProf pip package:
+
+```
+bazel run --config=public_cache plugin:build_pip_package
+```
+
+Navigate to the Bazel Output Directory and install:
+
+```
+cd /tmp/profile-pip
+pip install .
+```
+
+## Next Steps
+
+* [JAX Profiling Guide](https://jax.readthedocs.io/en/latest/profiling.html#xprof-tensorboard-profiling)
+* [PyTorch/XLA Profiling Guide](https://cloud.google.com/tpu/docs/pytorch-xla-performance-profiling-tpu-vm)
+* [TensorFlow Profiling Guide](https://tensorflow.org/guide/profiler)
+* [Cloud TPU Profiling Guide](https://cloud.google.com/tpu/docs/cloud-tpu-tools)
+* [Colab Tutorial](https://www.tensorflow.org/tensorboard/tensorboard_profiling_keras)
+* [Tensorflow Colab](https://www.tensorflow.org/tensorboard/tensorboard_profiling_keras)

tensorboard_plugin_profile-2.22.2.dist-info/RECORD

@@ -0,0 +1,5 @@
+tensorboard_plugin_profile/__init__.py,sha256=S02OWyVtjEtTuaAFJkR3t8Q9GQj0ECwn1ZTN81RET6c,911
+tensorboard_plugin_profile-2.22.2.dist-info/METADATA,sha256=kKrfQQVVLobr5InbRk9khuwu_W4Z0VIQuU17N1YnclE,11964
+tensorboard_plugin_profile-2.22.2.dist-info/WHEEL,sha256=QR8DNjG6Lr6bNErJWJgF4dP2dJ2N7NpY-BWly1OvcTM,97
+tensorboard_plugin_profile-2.22.2.dist-info/top_level.txt,sha256=lhPzC2a84VfVAbBlTgLUSZwuuUl9uTj5R1zZMylY1g8,27
+tensorboard_plugin_profile-2.22.2.dist-info/RECORD,,

tensorboard_plugin_profile-2.22.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-win_amd64
+

tensorboard_plugin_profile-2.22.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+tensorboard_plugin_profile