0
# Tracking and Experiment Management
1

2
MLflow's tracking system provides comprehensive experiment and run management with parameter, metric, and artifact logging. It supports both interactive (fluent API) and programmatic workflows with automatic logging capabilities for popular ML frameworks.
3

4
## Capabilities
5

6
### Run Management
7

8
Core functionality for starting, managing, and ending MLflow runs with support for nested runs and comprehensive metadata tracking.
9

10
```python { .api }
11
def start_run(run_id=None, experiment_id=None, run_name=None, nested=False, parent_run_id=None, tags=None, description=None, log_system_metrics=None):
12
    """
13
    Start a new MLflow run.
14
    
15
    Parameters:
16
    - run_id: str, optional - Existing run ID to resume
17
    - experiment_id: str, optional - Experiment ID for the run
18
    - run_name: str, optional - Human-readable name for the run
19
    - nested: bool - Whether this is a nested run (default False)
20
    - parent_run_id: str, optional - Parent run ID for nested runs
21
    - tags: dict, optional - Dictionary of string key-value pairs
22
    - description: str, optional - Description of the run
23
    - log_system_metrics: bool, optional - Whether to log system metrics
24
    
25
    Returns:
26
    ActiveRun object representing the started run
27
    """
28

29
def end_run(status=None):
30
    """
31
    End the currently active run.
32
    
33
    Parameters:
34
    - status: str, optional - Status of the run ('FINISHED', 'FAILED', 'KILLED')
35
    """
36

37
def active_run():
38
    """
39
    Get the currently active run.
40
    
41
    Returns:
42
    ActiveRun object or None if no run is active
43
    """
44

45
def get_run(run_id):
46
    """
47
    Get run by ID.
48
    
49
    Parameters:
50
    - run_id: str - The run ID
51
    
52
    Returns:
53
    Run object containing run information and data
54
    """
55

56
def delete_run(run_id):
57
    """
58
    Delete a run.
59
    
60
    Parameters:
61
    - run_id: str - The run ID to delete
62
    """
63

64
def search_runs(experiment_ids=None, filter_string="", run_view_type=ViewType.ACTIVE_ONLY, max_results=SEARCH_MAX_RESULTS_DEFAULT, order_by=None, page_token=None, search_all_experiments=False, experiment_names=None, output_format=""):
65
    """
66
    Search for runs matching criteria.
67
    
68
    Parameters:
69
    - experiment_ids: list, optional - List of experiment IDs to search
70
    - filter_string: str - Filter expression for runs
71
    - run_view_type: ViewType - Type of runs to return (ACTIVE_ONLY, DELETED_ONLY, ALL)
72
    - max_results: int - Maximum number of runs to return
73
    - order_by: list, optional - List of columns to order by
74
    - page_token: str, optional - Token for pagination
75
    - search_all_experiments: bool - Whether to search all experiments
76
    - experiment_names: list, optional - List of experiment names to search
77
    - output_format: str - Output format ('list', 'pandas')
78
    
79
    Returns:
80
    List of Run objects or pandas DataFrame
81
    """
82
```
83

84
### Experiment Management
85

86
Functions for creating, managing, and organizing experiments to group related runs and provide hierarchical organization of ML projects.
87

88
```python { .api }
89
def create_experiment(name, artifact_location=None, tags=None):
90
    """
91
    Create a new experiment.
92
    
93
    Parameters:
94
    - name: str - Experiment name (must be unique)
95
    - artifact_location: str, optional - Location to store artifacts
96
    - tags: dict, optional - Dictionary of string key-value pairs
97
    
98
    Returns:
99
    str - Experiment ID of the created experiment
100
    """
101

102
def set_experiment(experiment_name=None, experiment_id=None):
103
    """
104
    Set the active experiment by name or ID.
105
    
106
    Parameters:
107
    - experiment_name: str, optional - Name of the experiment
108
    - experiment_id: str, optional - ID of the experiment
109
    
110
    Returns:
111
    Experiment object
112
    """
113

114
def get_experiment(experiment_id):
115
    """
116
    Get experiment by ID.
117
    
118
    Parameters:
119
    - experiment_id: str - The experiment ID
120
    
121
    Returns:
122
    Experiment object
123
    """
124

125
def get_experiment_by_name(name):
126
    """
127
    Get experiment by name.
128
    
129
    Parameters:
130
    - name: str - The experiment name
131
    
132
    Returns:
133
    Experiment object or None if not found
134
    """
135

136
def delete_experiment(experiment_id):
137
    """
138
    Delete an experiment.
139
    
140
    Parameters:
141
    - experiment_id: str - The experiment ID to delete
142
    """
143

144
def search_experiments(view_type=ViewType.ACTIVE_ONLY, max_results=None, filter_string=None, order_by=None, page_token=None):
145
    """
146
    Search experiments matching criteria.
147
    
148
    Parameters:
149
    - view_type: ViewType - Type of experiments to return
150
    - max_results: int, optional - Maximum number of experiments
151
    - filter_string: str, optional - Filter expression
152
    - order_by: list, optional - List of columns to order by
153
    - page_token: str, optional - Token for pagination
154
    
155
    Returns:
156
    List of Experiment objects
157
    """
158
```
159

160
### Parameter and Metric Logging
161

162
Core logging functions for tracking experiment parameters, metrics, and performance data with support for batch operations and time-series metrics.
163

164
```python { .api }
165
def log_param(key, value):
166
    """
167
    Log a parameter for the current run.
168
    
169
    Parameters:
170
    - key: str - Parameter name
171
    - value: str/int/float/bool - Parameter value
172
    """
173

174
def log_params(params):
175
    """
176
    Log multiple parameters for the current run.
177
    
178
    Parameters:
179
    - params: dict - Dictionary of parameter name-value pairs
180
    """
181

182
def log_metric(key, value, step=None, timestamp=None, synchronous=None):
183
    """
184
    Log a metric for the current run.
185
    
186
    Parameters:
187
    - key: str - Metric name
188
    - value: float - Metric value
189
    - step: int, optional - Training step/epoch number
190
    - timestamp: int, optional - Unix timestamp in milliseconds
191
    - synchronous: bool, optional - Whether to log synchronously
192
    """
193

194
def log_metrics(metrics, step=None, timestamp=None, synchronous=None):
195
    """
196
    Log multiple metrics for the current run.
197
    
198
    Parameters:
199
    - metrics: dict - Dictionary of metric name-value pairs
200
    - step: int, optional - Training step/epoch number
201
    - timestamp: int, optional - Unix timestamp in milliseconds
202
    - synchronous: bool, optional - Whether to log synchronously
203
    """
204
```
205

206
### Artifact Logging
207

208
Functions for logging files, directories, and various data formats as artifacts with support for different storage backends and artifact organization.
209

210
```python { .api }
211
def log_artifact(local_path, artifact_path=None, synchronous=None):
212
    """
213
    Log a local file as an artifact.
214
    
215
    Parameters:
216
    - local_path: str - Local file path
217
    - artifact_path: str, optional - Relative artifact path within run
218
    - synchronous: bool, optional - Whether to log synchronously
219
    """
220

221
def log_artifacts(local_dir, artifact_path=None, synchronous=None):
222
    """
223
    Log all files in a local directory as artifacts.
224
    
225
    Parameters:
226
    - local_dir: str - Local directory path
227
    - artifact_path: str, optional - Relative artifact path within run
228
    - synchronous: bool, optional - Whether to log synchronously
229
    """
230

231
def log_dict(dictionary, artifact_file):
232
    """
233
    Log a dictionary as a JSON artifact.
234
    
235
    Parameters:
236
    - dictionary: dict - Dictionary to log
237
    - artifact_file: str - Name of the artifact file
238
    """
239

240
def log_figure(figure, artifact_file, save_kwargs=None):
241
    """
242
    Log a matplotlib figure as an artifact.
243
    
244
    Parameters:
245
    - figure: matplotlib.figure.Figure - Figure to log
246
    - artifact_file: str - Name of the artifact file
247
    - save_kwargs: dict, optional - Keyword arguments for savefig
248
    """
249

250
def log_image(image, artifact_file=None, key=None, step=None, timestamp=None, synchronous=None):
251
    """
252
    Log an image as an artifact.
253
    
254
    Parameters:
255
    - image: PIL Image, numpy array, or file path - Image to log
256
    - artifact_file: str, optional - Name of the artifact file
257
    - key: str, optional - Metric key for image logging
258
    - step: int, optional - Training step number
259
    - timestamp: int, optional - Unix timestamp in milliseconds
260
    - synchronous: bool, optional - Whether to log synchronously
261
    """
262

263
def log_table(data, artifact_file, extra_tags=None):
264
    """
265
    Log tabular data as an artifact.
266
    
267
    Parameters:
268
    - data: pandas.DataFrame, numpy.ndarray, or list - Tabular data
269
    - artifact_file: str - Name of the artifact file
270
    - extra_tags: dict, optional - Additional tags for the artifact
271
    """
272

273
def log_text(text, artifact_file):
274
    """
275
    Log text content as an artifact.
276
    
277
    Parameters:
278
    - text: str - Text content to log
279
    - artifact_file: str - Name of the artifact file
280
    """
281
```
282

283
### Tagging
284

285
Functions for adding metadata tags to runs and experiments for organization, filtering, and categorization purposes.
286

287
```python { .api }
288
def set_tag(key, value):
289
    """
290
    Set a tag on the current run.
291
    
292
    Parameters:
293
    - key: str - Tag key
294
    - value: str - Tag value
295
    """
296

297
def set_tags(tags):
298
    """
299
    Set multiple tags on the current run.
300
    
301
    Parameters:
302
    - tags: dict - Dictionary of tag key-value pairs
303
    """
304

305
def delete_tag(key):
306
    """
307
    Delete a tag from the current run.
308
    
309
    Parameters:
310
    - key: str - Tag key to delete
311
    """
312

313
def set_experiment_tag(key, value):
314
    """
315
    Set a tag on the current experiment.
316
    
317
    Parameters:
318
    - key: str - Tag key
319
    - value: str - Tag value
320
    """
321

322
def set_experiment_tags(tags):
323
    """
324
    Set multiple tags on the current experiment.
325
    
326
    Parameters:
327
    - tags: dict - Dictionary of tag key-value pairs
328
    """
329

330
def delete_experiment_tag(key):
331
    """
332
    Delete a tag from the current experiment.
333
    
334
    Parameters:
335
    - key: str - Tag key to delete
336
    """
337
```
338

339
### Automatic Logging
340

341
Configuration and management of automatic logging for supported ML frameworks with customizable logging behavior and exclusion options.
342

343
```python { .api }
344
def autolog(log_input_examples=False, log_model_signatures=True, log_models=True, log_datasets=True, disable=False, exclusive=False, disable_for_unsupported_versions=False, silent=False, extra_tags=None, registered_model_name=None):
345
    """
346
    Enable automatic logging for supported ML frameworks.
347
    
348
    Parameters:
349
    - log_input_examples: bool - Whether to log input examples
350
    - log_model_signatures: bool - Whether to log model signatures
351
    - log_models: bool - Whether to log models
352
    - log_datasets: bool - Whether to log datasets
353
    - disable: bool - Whether to disable autologging
354
    - exclusive: bool - Whether to disable other autologging integrations
355
    - disable_for_unsupported_versions: bool - Disable for unsupported versions
356
    - silent: bool - Whether to suppress autolog warnings
357
    - extra_tags: dict, optional - Additional tags for autolog runs
358
    - registered_model_name: str, optional - Name for model registration
359
    """
360
```
361

362
### Utility Functions
363

364
Helper functions for accessing run information, artifact URIs, and managing run context within MLflow workflows.
365

366
```python { .api }
367
def get_artifact_uri(artifact_path=None):
368
    """
369
    Get the artifact URI for the current run.
370
    
371
    Parameters:
372
    - artifact_path: str, optional - Relative path within artifacts
373
    
374
    Returns:
375
    str - URI to the artifact location
376
    """
377

378
def get_parent_run():
379
    """
380
    Get the parent run of the current nested run.
381
    
382
    Returns:
383
    Run object or None if not nested
384
    """
385

386
def last_active_run():
387
    """
388
    Get the last active run.
389
    
390
    Returns:
391
    Run object or None
392
    """
393
```
394

395
## Usage Examples
396

397
### Basic Experiment Tracking
398

399
```python
400
import mlflow
401
import numpy as np
402
from sklearn.model_selection import train_test_split
403
from sklearn.ensemble import RandomForestRegressor
404
from sklearn.metrics import mean_squared_error
405

406
# Set experiment
407
mlflow.set_experiment("housing-price-prediction")
408

409
# Generate sample data
410
X = np.random.rand(1000, 10)
411
y = np.random.rand(1000)
412
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)
413

414
# Start run
415
with mlflow.start_run(run_name="random-forest-experiment"):
416
    # Log parameters
417
    n_estimators = 100
418
    max_depth = 10
419
    mlflow.log_param("n_estimators", n_estimators)
420
    mlflow.log_param("max_depth", max_depth)
421
    
422
    # Train model
423
    model = RandomForestRegressor(n_estimators=n_estimators, max_depth=max_depth)
424
    model.fit(X_train, y_train)
425
    
426
    # Make predictions and calculate metrics
427
    y_pred = model.predict(X_test)
428
    mse = mean_squared_error(y_test, y_pred)
429
    
430
    # Log metrics
431
    mlflow.log_metric("mse", mse)
432
    mlflow.log_metric("rmse", np.sqrt(mse))
433
    
434
    # Log model
435
    mlflow.sklearn.log_model(model, "model")
436
    
437
    # Log additional artifacts
438
    import matplotlib.pyplot as plt
439
    
440
    plt.figure(figsize=(8, 6))
441
    plt.scatter(y_test, y_pred, alpha=0.6)
442
    plt.plot([y_test.min(), y_test.max()], [y_test.min(), y_test.max()], 'r--', lw=2)
443
    plt.xlabel('Actual')
444
    plt.ylabel('Predicted')
445
    plt.title('Actual vs Predicted Values')
446
    
447
    mlflow.log_figure(plt.gcf(), "predictions_scatter.png")
448
    plt.close()
449
    
450
    print(f"Run ID: {mlflow.active_run().info.run_id}")
451
```
452

453
### Nested Runs for Hyperparameter Tuning
454

455
```python
456
import mlflow
457
from sklearn.model_selection import ParameterGrid
458
from sklearn.ensemble import RandomForestRegressor
459
from sklearn.metrics import mean_squared_error
460
import numpy as np
461

462
# Set experiment
463
mlflow.set_experiment("hyperparameter-tuning")
464

465
# Parameter grid
466
param_grid = {
467
    'n_estimators': [50, 100, 200],
468
    'max_depth': [5, 10, 15]
469
}
470

471
# Sample data
472
X = np.random.rand(1000, 10)
473
y = np.random.rand(1000)
474

475
best_mse = float('inf')
476
best_params = None
477

478
# Parent run for the entire tuning process
479
with mlflow.start_run(run_name="hyperparameter-tuning-parent"):
480
    for params in ParameterGrid(param_grid):
481
        # Nested run for each parameter combination
482
        with mlflow.start_run(nested=True, run_name=f"rf-{params['n_estimators']}-{params['max_depth']}"):
483
            # Log parameters
484
            mlflow.log_params(params)
485
            
486
            # Train model
487
            model = RandomForestRegressor(**params)
488
            model.fit(X, y)
489
            
490
            # Calculate and log metrics
491
            y_pred = model.predict(X)
492
            mse = mean_squared_error(y, y_pred)
493
            mlflow.log_metric("mse", mse)
494
            
495
            # Track best parameters
496
            if mse < best_mse:
497
                best_mse = mse
498
                best_params = params
499
    
500
    # Log best results to parent run
501
    mlflow.log_params(best_params)
502
    mlflow.log_metric("best_mse", best_mse)
503
```
504

505
## Types
506

507
```python { .api }
508
from mlflow.entities import Experiment, Run, RunInfo, RunData, Metric, Param, RunTag
509
from mlflow.tracking.fluent import ActiveRun
510
from mlflow.utils.mlflow_tags import MLFLOW_RUN_NAME, MLFLOW_USER, MLFLOW_SOURCE_NAME
511

512
class Experiment:
513
    experiment_id: str
514
    name: str
515
    artifact_location: str
516
    lifecycle_stage: str
517
    tags: Dict[str, str]
518
    creation_time: int
519
    last_update_time: int
520

521
class Run:
522
    info: RunInfo
523
    data: RunData
524

525
class RunInfo:
526
    run_id: str
527
    run_uuid: str  # Deprecated, use run_id
528
    run_name: str
529
    experiment_id: str
530
    user_id: str
531
    status: str
532
    start_time: int
533
    end_time: int
534
    artifact_uri: str
535
    lifecycle_stage: str
536

537
class RunData:
538
    metrics: List[Metric]
539
    params: List[Param]
540
    tags: List[RunTag]
541

542
class ActiveRun:
543
    info: RunInfo
544
    data: RunData
545

546
class Metric:
547
    key: str
548
    value: float
549
    timestamp: int
550
    step: int
551

552
class Param:
553
    key: str
554
    value: str
555

556
class RunTag:
557
    key: str
558
    value: str
559

560
class ViewType:
561
    ACTIVE_ONLY: str = "1"
562
    DELETED_ONLY: str = "2"
563
    ALL: str = "3"
564
```