Run Metadata

This foundational layer captures the who, when, and where of a run's execution. It includes immutable identifiers and timestamps essential for audit trails and chronological analysis.

• Run ID: A unique, immutable identifier (often a UUID) for the specific execution instance.
• User/Initiator: The identity of the person or system service that launched the run.
• Start/End Timestamps: Precise timestamps recording the run's duration and latency.
• Status: The final state of the run (e.g., FINISHED, FAILED, KILLED).

This component ensures reproducibility by logging the exact code and software environment used. It answers the critical question: "What code version, under what conditions, produced these results?"

• Git Commit Hash: The specific version of the source code repository used for the run.
• Environment Snapshot: A record of all software dependencies (e.g., from conda env export or pip freeze).
• Entry Point: The main script or command that was executed to launch the training job.

This is the core of experimental design, logging all tunable inputs that define the model's behavior. Distinguishing between hyperparameters and configuration is key for systematic tuning.

• Hyperparameters: Model-architecture and training-process settings (e.g., learning rate, batch size, layer count).
• Static Configuration: Fixed settings for data paths, feature flags, or system resource limits.
• Source: The file (e.g., config.yaml) or framework (e.g., Hydra, argparse) used to manage these parameters.

These are the quantitative outputs used to evaluate model performance and training behavior. They are logged over time (e.g., per epoch) to create training curves.

• Objective Metrics: The primary measures being optimized, such as validation accuracy, F1 score, or loss.
• System Metrics: Resource utilization data like GPU memory consumption, CPU usage, and epoch duration.
• Custom Metrics: Project-specific calculations, such as business KPIs or domain-specific scores.

This component manages the large, immutable outputs generated by the run, linking them to the metadata for full lineage. Artifacts are stored in dedicated object storage, not the metadata database.

• Model Checkpoints: Serialized model weights saved at intervals during training.
• Final Model: The fully trained model file ready for deployment or evaluation.
• Evaluation Reports: Files containing detailed performance analysis, confusion matrices, or visualizations.
• Processed Datasets: Versioned outputs from data preprocessing steps within the run.

This layer adds human-readable context and flexible, searchable annotations to runs. It transforms raw data into organized, queryable knowledge for teams.

• Tags: Key-value pairs for categorization (e.g., model_type: "bert", dataset: "v1.2"). Used for filtering and grouping runs in dashboards.
• Notes: Free-text descriptions of the run's purpose, hypotheses, or observations.
• Custom JSON: A flexible field for storing any additional structured data relevant to the project's tracking needs.

A Run ID is the unique, immutable identifier for a single execution of a machine learning training or evaluation script. It is the primary key used to retrieve all associated run metadata, parameters, metrics, and artifacts from a tracking system. This identifier enables precise querying, comparison, and lineage tracing for every experiment.

Artifact storage refers to the system for versioning and persisting large, immutable outputs generated during a machine learning run. This is distinct from lightweight metadata and includes:

• Trained model files (.pt, .h5)
• Evaluation reports and visualizations
• Serialized preprocessing objects (e.g., vectorizers, scalers)
• Generated datasets or predictions These artifacts are linked to a run via its metadata, ensuring full provenance.

An environment snapshot is a critical piece of run metadata that records the exact software state required to reproduce a training run. It typically includes:

• Python version and all installed packages (via pip freeze or conda env export)
• System library versions (e.g., CUDA, cuDNN)
• Environment variables This snapshot ensures that the run metadata is actionable for true reproducibility, preventing "it worked on my machine" failures.

Configuration management is the practice of externalizing all tunable parameters from code into structured files (e.g., YAML, JSON). Frameworks like Hydra manage these configurations. The specific configuration used for a run is logged as key metadata, providing a complete, versioned record of the experiment's setup. This separates code logic from experimental parameters, a foundational principle for systematic tracking.

Lineage tracking extends run metadata to document the complete origin and transformation history of all inputs. It answers:

• Which dataset version (commit hash, S3 URI) was used?
• What preprocessing code and parameters transformed it?
• What was the parent run that generated the input model? This creates an auditable graph of dependencies, making run metadata part of a broader provenance system essential for debugging and compliance.

A tracking server (e.g., MLflow Tracking Server, Weights & Biases backend) is the centralized service that receives, stores, and serves all run metadata from distributed training jobs. It provides:

• A unified API for logging metrics and parameters.
• A database for querying runs.
• A web dashboard for visualization and comparison. It is the infrastructure backbone that makes run metadata accessible and actionable for teams.