Skip to content

Add Google Cloud ML Diagnostics metrics support and documentation - #459

Open
richaguptaa17 wants to merge 1 commit into
AI-Hypercomputer:mainfrom
richaguptaa17:mldiagnostics-metrics
Open

Add Google Cloud ML Diagnostics metrics support and documentation#459
richaguptaa17 wants to merge 1 commit into
AI-Hypercomputer:mainfrom
richaguptaa17:mldiagnostics-metrics

Conversation

@richaguptaa17

@richaguptaa17 richaguptaa17 commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

Integrate Google Cloud ML Diagnostics SDK (google-cloud-mldiagnostics) into MaxDiffusion to automatically record training, system, and performance metrics.

Key Changes:

  • train_utils.py: Added _METRICS_TO_MANAGED mapping table converting metrics names to canonical MetricType enums (loss, learning_rate, gradient_norm, total_weights, step_time, tflops) with automatic pass-through for custom metrics.
  • max_utils.py: configured region=None for GCP cluster auto-discovery, and enabled background hardware metric collection (log_system_metrics=True).
  • metrics.md: Created comprehensive guide for capturing metrics using google-cloud-mldiagnostics integration in training scripts.

Tested:

  • Ran a multi-host distributed training run on TPU v6e cluster. Verified successful metric ingestion in Cloud Logging for predefined, custom, and hardware utilization metrics.

@richaguptaa17
richaguptaa17 requested a review from entrpn as a code owner August 13, 2026 16:21

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request integrates the Google Cloud ML Diagnostics SDK into MaxDiffusion to enable real-time telemetry, including workload, system, and accelerator metrics. Key changes include adding documentation, filtering non-JSON serializable keys from the configuration, and recording scalar metrics like gradient norm and total weights in the training loops. The review feedback highlights two important issues: first, workload metrics recording should be restricted to the master node (process 0) to prevent duplicate logs in multi-host setups; second, the MetricType enum resolution should be made safer to avoid potential AttributeError crashes during module import.

Comment thread src/maxdiffusion/train_utils.py Outdated
Comment thread src/maxdiffusion/train_utils.py Outdated
@richaguptaa17
richaguptaa17 force-pushed the mldiagnostics-metrics branch 2 times, most recently from 8f59dbe to ed938eb Compare August 13, 2026 16:37
@richaguptaa17 richaguptaa17 changed the title Add Google Cloud ML Diagnostics metrics support and developer guide. Add Google Cloud ML Diagnostics metrics support and documentation Aug 13, 2026
@richaguptaa17
richaguptaa17 force-pushed the mldiagnostics-metrics branch from 74bb624 to 7d3579f Compare August 13, 2026 16:44
entrpn
entrpn previously approved these changes Aug 13, 2026
return "enable_ml_diagnostics" in config.get_keys() and config.enable_ml_diagnostics


_ml_diagnostics_profiler_enabled = ml_diagnostics_enabled

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do you need this?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed. It was an unnecessary alias from renaming the function.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can still see it, maybe you forgot to push?

Comment thread src/maxdiffusion/train_utils.py Outdated
metric_types = None


_metric_type_enum = getattr(metric_types, "MetricType", None) if metric_types else None

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we expect MetricType attribute not present if metric_types is not None? Lots of silence failure here. If ml diagnostic exists, we should not ignore any failure after that. So if I install ml_diagnostic dependencies on a job, I expect it to work and if there is any incompatibilities/failures, the job should fail rather than ignore it and disable ml_diagnostics.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. If google_cloud_mldiagnostics is installed, metric_types.MetricType should be present. Replaced fallback with direct mapping.

Made a change to raise an explicit ImportError if a user sets enable_ml_diagnostics: True but google_cloud_mldiagnostics is not installed or initialized.

@Perseus14

Copy link
Copy Markdown
Collaborator

Thanks for the PR @richaguptaa17. Could you please do the following?

  • Run linting commands ruff check . and pyink src/maxdiffusion --pyink-indentation=2 --line-length=125 (ruff==0.15.12 and pyink==23.10.0)
  • Squash commits

@richaguptaa17
richaguptaa17 force-pushed the mldiagnostics-metrics branch 3 times, most recently from 141c0a7 to c42939a Compare August 14, 2026 15:16
Integrate Google Cloud ML Diagnostics SDK (google-cloud-mldiagnostics) into
MaxDiffusion to automatically record training, system, and performance metrics.

Key Changes:
- train_utils.py: Added _METRICS_TO_MANAGED mapping table converting MaxDiffusion
  keys to canonical MetricType enums (loss, learning_rate, gradient_norm,
  total_weights, step_time, tflops) with automatic pass-through for custom metrics.
  Added batch metric logging to write_metrics().
- max_utils.py: Added _clean_config_dict() to sanitize non-JSON serializable
  hyperparameters, configured region=None for GCP cluster auto-discovery, and
  enabled background hardware metric collection (log_system_metrics=True).
- docs/metrics.md: Created comprehensive integration, architecture, and verification
  guide for developers adding new model trainers.

Tested:
- Ran a 500-step multi-host distributed training run on TPU v6e cluster
  richa-maxdiffusion-test (JobSet richa-metrics-test-v11). Verified
  successful metric ingestion in Cloud Logging (ml_diagnostics_metric) for
  predefined, custom, and hardware utilization metrics.
@richaguptaa17
richaguptaa17 force-pushed the mldiagnostics-metrics branch from c42939a to 36cfd7e Compare August 14, 2026 15:31
@richaguptaa17

Copy link
Copy Markdown
Contributor Author

Ran the linting commands and squashed the commits.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants