Skip to main content

​
Overview

The log_step_metadata() function allows you to attach metadata to step runs during pipeline execution. This is particularly useful for logging metrics, parameters, or custom tracking information from within your steps.

​
Signature

from zenml import log_step_metadata

def log_step_metadata(
    metadata: Dict[str, MetadataType],
    step_name: Optional[str] = None,
) -> None:
    """Log metadata to a step run.
    
    Args:
        metadata: Dictionary of metadata key-value pairs to log
        step_name: Name of the step (uses current step if not provided)
    """

​
Parameters

​
metadata
Dict[str, MetadataType]
required
Dictionary of metadata key-value pairs to log. Supported value types:
  • Primitives: str, int, float, bool
  • URI: Uri for file/resource references
  • Structured: dict, list
​
step_name
str
default:"None"
Name of the step to log metadata to. If not provided, logs to the currently executing step.

​
Return Value

​
return
None
This function does not return a value. Metadata is logged to the ZenML server and associated with the step run.

​
Usage Examples

​
Log Metrics During Training

from zenml import step, log_step_metadata
import time

@step
def train_model(data: dict) -> str:
    """Train a model and log metrics."""
    start_time = time.time()
    
    # Training logic here
    accuracy = 0.95
    loss = 0.12
    
    # Log training metrics
    log_step_metadata(
        metadata={
            "accuracy": accuracy,
            "loss": loss,
            "training_time_seconds": time.time() - start_time,
            "num_samples": len(data),
        }
    )
    
    return "model_v1"

​
Log Hyperparameters

from zenml import step, log_step_metadata

@step
def train_model(learning_rate: float = 0.001, batch_size: int = 32) -> str:
    """Train with hyperparameters."""
    
    # Log hyperparameters at the start
    log_step_metadata(
        metadata={
            "learning_rate": learning_rate,
            "batch_size": batch_size,
            "optimizer": "adam",
            "activation": "relu",
        }
    )
    
    # Training logic
    model = train(...)
    
    return model

​
Log Data Quality Metrics

from zenml import step, log_step_metadata

@step
def validate_data(dataset: dict) -> dict:
    """Validate dataset and log quality metrics."""
    
    # Calculate data quality metrics
    missing_values = dataset.isnull().sum()
    duplicates = dataset.duplicated().sum()
    total_rows = len(dataset)
    
    log_step_metadata(
        metadata={
            "total_rows": total_rows,
            "missing_values": int(missing_values),
            "duplicate_rows": int(duplicates),
            "data_quality_score": 0.98,
        }
    )
    
    return dataset

​
Log from Different Steps

from zenml import pipeline, step, log_step_metadata

@step
def preprocess_data() -> dict:
    data = {"processed": True}
    log_step_metadata(
        metadata={"preprocessing_version": "v2.1"},
        step_name="preprocess_data"
    )
    return data

@step
def train_model(data: dict) -> str:
    # Can log to a different step
    log_step_metadata(
        metadata={"data_source": "upstream"},
        step_name="preprocess_data"
    )
    return "model"

​
Metadata Types

ZenML supports various metadata types:
  • Primitives: str, int, float, bool
  • URI: Uri for file paths and URLs
  • Storage Size: StorageSize for byte sizes
  • Structured: dict, list for complex data
  • Custom: Any JSON-serializable type

​
Best Practices

Log Early

Log hyperparameters and config at the start of your step for complete tracking

Use Descriptive Keys

Use clear, consistent naming for metadata keys (e.g., “training_accuracy” not “acc”)

Log Incrementally

You can call log_step_metadata multiple times - metadata is accumulated

Track Versions

Log versions of data, models, and dependencies for reproducibility

log_metadata

General metadata logging function

log_artifact_metadata

Log metadata to artifacts

log_model_metadata

Log metadata to models

get_step_context

Access step context information

​
Notes

Metadata logged with log_step_metadata() is visible in the ZenML dashboard and can be used for filtering, searching, and comparing step runs.
If you call log_step_metadata() multiple times within the same step, the metadata is accumulated (not replaced).

Build docs developers (and LLMs) love

Get started for freeTalk to us