Registry / ai-ml / ml-goodput-measurement

ml-goodput-measurement

JSON →
library0.2.0pypypiunverified

ML Goodput Measurement (ml-goodput-measurement) is a Python library designed to monitor and analyze the efficiency of Machine Learning (ML) workloads. It tracks metrics such as Goodput, Badput, and step time deviation, integrating with Google Cloud Logging, Google Cloud Monitoring, and TensorBoard for data storage, visualization, and alerting. The library is actively maintained, with minor version releases occurring roughly monthly or bi-monthly, and is currently at version 0.0.16.

pip install ml-goodput-measurement
INSTALL
IMPORT
SIG · ML-GOODPUT-MEASURE
M
ml-goodput-measurement
ai-mlpythonv0.2.0
Install
12.4s avg
Import
Disk
291MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.2.0 · 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
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 290.9MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 12.4s · import 0.000s · 279MB
291MB installed
● package 291MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

GoodputMonitor
from ml_goodput_measurement.goodput import GoodputMonitor
from ml_goodput_measurement.goodput import GoodputMonitor

This quickstart demonstrates how to use `GoodputRecorder` to log productive steps and `GoodputMonitor` to asynchronously query and upload Goodput metrics. It simulates a basic ML training loop. Ensure you have a Google Cloud project with billing enabled and appropriate permissions for Cloud Logging, Cloud Monitoring, and GCS (for TensorBoard logs) before running in a real environment. Replace placeholder environment variables with actual unique values for production use.

import os import time from goodput import GoodputMonitor, GoodputRecorder # --- Configuration Parameters (replace with your actual values) --- # IMPORTANT: Use unique run_name and logger_name for each experiment to avoid data corruption. JOB_NAME = os.environ.get('GOODPUT_JOB_NAME', 'my-ml-training-job-unique-id') LOGGER_NAME = os.environ.get('GOODPUT_LOGGER_NAME', f'goodput_{JOB_NAME}') TENSORBOARD_DIR = os.environ.get('GOODPUT_TENSORBOARD_DIR', '/tmp/tensorboard_logs') # --- Initialize Recorder to log productive steps --- recorder = GoodputRecorder( job_name=JOB_NAME, logger_name=LOGGER_NAME, logging_enabled=True # Set to True to enable logging to Google Cloud Logging ) # --- Simulate a training loop --- print(f"Starting ML workload: {JOB_NAME}") for step in range(10): recorder.log_productive_step(step) print(f"Completed productive step {step}") time.sleep(1) # Simulate productive work # Simulate some unproductive time or I/O if step % 3 == 0: time.sleep(0.5) recorder.log_unproductive_time("data_loading", 0.5) # --- Initialize and start GoodputMonitor for asynchronous upload --- # The monitor runs in a separate process and uploads to TensorBoard and Google Cloud Monitoring. monitor = GoodputMonitor( job_name=JOB_NAME, logger_name=LOGGER_NAME, tensorboard_dir=TENSORBOARD_DIR, upload_interval=30, # Upload every 30 seconds monitoring_enabled=True, # Set to True to enable monitoring include_badput_breakdown=True ) monitor.start_goodput_uploader() print("Goodput Monitor started. Metrics will be uploaded asynchronously.") # Continue with the rest of your training job... # For demonstration, let's keep it running for a bit time.sleep(65) # --- Stop the monitor when the job is done --- monitor.stop_goodput_uploader() recorder.log_job_completion() print("ML workload finished. Goodput Monitor stopped.")
Debug
Known issues
breakingThe `GoodputMonitor` implementation was refactored in `v0.0.15` to use `multiprocessing` instead of `multithreading` for asynchronous metric uploads.
fix
If your application relied on `GoodputMonitor` sharing memory or specific threading behaviors with your main application, you may need to adjust your concurrency model. `multiprocessing` uses separate process spaces, which impacts shared state.
affects: >=0.0.15
gotchaReusing `job_name` or `logger_name` across different experiments or job runs within the same Google Cloud project can lead to inaccurate cumulative Goodput metrics.
fix
Always use a unique `job_name` and `goodput_logger_name` for each individual experiment or workload you intend to monitor separately to ensure accurate cumulative metrics.
affects: All versions
gotchaFull functionality relies on a properly configured Google Cloud project, including enabled billing and necessary access scopes for Google Cloud Logging, Google Cloud Monitoring, and Google Cloud Storage (for TensorBoard).
fix
Before deployment, ensure your GCP project has the required APIs enabled and service accounts have permissions to write to Cloud Logging, write custom metrics to Cloud Monitoring, and write to the specified TensorBoard GCS bucket.
affects: All versions
Upgrade
Version history
0.2.0latest on PyPI · released Jun 12, 2026
Audit
Dependencies
google-cloud-loggingoptionalRequired for logging productive step time and total job run time to Google Cloud Logging.
tensorflowoptionalRequired for uploading Goodput and Badput metrics to TensorBoard.
google-cloud-monitoringoptionalRequired for automatically sending performance data (cumulative/rolling window Goodput/Badput) to Google Cloud Monitoring.
Agent activity
20 hits · last 30 days
node
18
OpenAI (training)
2
Resources
ml-goodput-measurement — pip install ml-goodput-measurement · libregistry