Registry /
gcp / cloud-accelerator-diagnostics
Install & Compatibility
Where this runs
tested against v0.1.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 281.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 18.0s · import 0.000s · 279MB
295MB installed
● package 295MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
start_upload_to_tensorboard
✓ from cloud_accelerator_diagnostics.upload_to_tensorboard import start_upload_to_tensorboard
Main function for initiating Tensorboard uploads.
stop_upload_to_tensorboard
✓ from cloud_accelerator_diagnostics.upload_to_tensorboard import stop_upload_to_tensorboard
Function to gracefully shut down the Tensorboard upload thread.
This quickstart demonstrates how to initialize and use `cloud-accelerator-diagnostics` to upload logs to a Vertex AI Tensorboard instance. It covers starting and stopping the background upload thread and highlights the necessary Google Cloud setup (API enablement, IAM roles).
import os
import time
from cloud_accelerator_diagnostics.upload_to_tensorboard import start_upload_to_tensorboard, stop_upload_to_tensorboard
# Replace with your Google Cloud Project ID and desired Tensorboard instance/experiment names
PROJECT_ID = os.environ.get('GCP_PROJECT_ID', 'your-gcp-project-id')
REGION = os.environ.get('GCP_REGION', 'us-central1') # e.g., 'us-central1'
TENSORBOARD_INSTANCE_NAME = 'test-instance'
EXPERIMENT_NAME = 'my-accelerator-experiment'
LOG_DIR = '/tmp/my_tpu_logs' # Directory where Tensorboard logs are written by your workload
# Ensure the log directory exists
os.makedirs(LOG_DIR, exist_ok=True)
print(f"Starting Tensorboard uploader for project {PROJECT_ID} in region {REGION}...")
print(f"Logs from {LOG_DIR} will be uploaded to Tensorboard instance '{TENSORBOARD_INSTANCE_NAME}' and experiment '{EXPERIMENT_NAME}'.")
try:
# Start the background thread to monitor log_dir and upload to Vertex AI Tensorboard.
# This will create the instance and experiment if they don't exist.
uploader_thread_handle = start_upload_to_tensorboard(
project_id=PROJECT_ID,
region=REGION,
tensorboard_instance_name=TENSORBOARD_INSTANCE_NAME,
experiment_name=EXPERIMENT_NAME,
logdir=LOG_DIR
)
print("Tensorboard uploader started. Running for 60 seconds...")
# Simulate a workload generating logs (e.g., a JAX/PyTorch training loop)
# In a real scenario, your ML framework would write events to LOG_DIR.
# For this example, we'll just wait.
time.sleep(60)
print("Workload simulation complete.")
except Exception as e:
print(f"An error occurred: {e}")
finally:
# Ensure the uploader thread is gracefully shut down
print("Stopping Tensorboard uploader...")
stop_upload_to_tensorboard(uploader_thread_handle)
print("Tensorboard uploader stopped.")
Errors
Common errors & fixes
google.api_core.exceptions.PermissionDenied: 403 Permission 'aiplatform.tensorboards.create' denied on resource
The service account or user credentials used to run the application do not have the necessary permissions (e.g., 'Vertex AI User' role) to create or access Vertex AI Tensorboard resources.
fixEnsure the Vertex AI API is enabled and the executing principal has the 'Vertex AI User' (roles/aiplatform.user) IAM role on the Google Cloud project.
ModuleNotFoundError: No module named 'cloud_accelerator_diagnostics'
The `cloud-accelerator-diagnostics` package is not installed in the current Python environment.
fixRun `pip install cloud-accelerator-diagnostics` to install the package.
Thread RuntimeError: cannot join current thread
Attempting to call `stop_upload_to_tensorboard()` on a thread handle when the thread has not been properly started or is already stopped. More commonly, if `start_upload_to_tensorboard` was called without capturing its return value.
fixAlways capture the return value of `start_upload_to_tensorboard()` and pass it to `stop_upload_to_tensorboard()`. Ensure the `stop` function is called only once per `start`.
Upgrade
Version history
0.1.1latest on PyPI · released Oct 15, 2024
Audit
Dependencies
google-cloud-aiplatformrequiredRequired for integrating with Vertex AI Tensorboard.
libtpuoptionalUnderlies TPU utilization metrics, used by related diagnostic tools like `tpu-info` which can be installed from a subdirectory of the cloud-accelerator-diagnostics repository.
Resources
No resource links recorded.