# tracker

Python API: `luxonis_ml.tracker`

Experiment tracking facade for Luxonis ML workflows.

The luxonis_ml.tracker package exports
[LuxonisTracker](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md),
a unified logging interface for TensorBoard, Weights & Biases, and MLflow. Training and evaluation code can log metrics,
hyperparameters, images, matrices, and artifacts through one API while choosing the enabled backends at runtime.

Pass `rank` in distributed training. The rank-gated logging methods, such as
[LuxonisTracker.log_metric](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md),
write only on rank 0. The helpers that save or replay the local buffer do not check the rank.

> **Example**
> Start a TensorBoard-backed run and log a scalar metric.

```python
from luxonis_ml.tracker import LuxonisTracker

tracker = LuxonisTracker(
    project_name="training",
    run_name="baseline",
    is_tensorboard=True,
)
tracker.log_metric("loss", 0.42, step=1)
tracker.close()
```

> **Note**
> The `tracker` extra does not install every dependency of this package. The package imports `mlflow` and `cv2` at import time, so install `mlflow` and `opencv-python` as well:

```bash
pip install "luxonis-ml[tracker,mlflow]" opencv-python
```

Install the SDK of each remaining backend you enable:

 * TensorBoard needs `torch`, because the writer comes from `torch.utils.tensorboard`;
 * Weights & Biases needs `wandb`.

The tracker imports `torch` and `wandb` only when you enable those backends, so an absent SDK matters only for the backends you
turn on.

Table of Contents

 * [Enabling the
   Backends](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker.md)
 * [Logging
   API](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker.md)
 * [MLflow
   Notes](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker.md)

## Enabling the Backends

Each backend has its own flag. Turn on as many as you need in one run:

```python
from luxonis_ml.tracker import LuxonisTracker

tracker = LuxonisTracker(
    project_name="my-project",
    run_name="baseline",
    is_tensorboard=True,
    is_wandb=True,
    wandb_entity="my-entity",
)

tracker.log_hyperparams({"lr": 1e-3, "batch_size": 32})
tracker.log_metrics({"acc": 0.92, "loss": 0.18}, step=1)
tracker.upload_artifact("model.onnx", name="model", typ="model")
tracker.close()
```

Two backends need one more argument, and the constructor raises `ValueError` without it:

Backend arguments

| Flag | Also needs |
| --- | --- |
| `is_tensorboard` | Nothing. The writer uses `<save_directory>/tensorboard_logs/<run_name>`. A sweep run adds a `trial_<n>`
level. |
| `is_wandb` | `wandb_entity`, and `project_name` or `project_id`. |
| `is_mlflow` | `mlflow_tracking_uri`, and `project_name` or `project_id`. |

## Logging API

[LuxonisTracker](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)
sends each of these calls to every enabled backend that supports it:

 * [LuxonisTracker.log_hyperparams](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md);
 * [LuxonisTracker.log_metric](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)
   and
   [LuxonisTracker.log_metrics](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md);
 * [LuxonisTracker.log_image](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)
   and
   [LuxonisTracker.log_images](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md);
 * [LuxonisTracker.log_matrix](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md);
 * [LuxonisTracker.upload_artifact](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md).

TensorBoard accepts no artifact, so
[LuxonisTracker.upload_artifact](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)
reaches Weights & Biases and MLflow only.

[LuxonisTracker.close](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)
calls no backend. It writes the unsent MLflow buffer to disk when you enable MLflow.

The images are `numpy` arrays of shape (H, W, C).

## MLflow Notes

MLflow starts on the first access to
[LuxonisTracker.experiment](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md).
A failed MLflow call does not raise. The tracker buffers the payload and retries it after the next successful call.

[LuxonisTracker.close](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)
writes a buffer that is still not empty under `<save_directory>/<run_name>`:

 * `local_logs.json` holds the metrics, the parameters, the matrices, and the index of the saved images and artifacts;
 * `images/` holds the buffered images;
 * `artifacts/` holds a copy of each buffered artifact whose source file still exists.

Set `MLFLOW_CLOUDFLARE_ID` and `MLFLOW_CLOUDFLARE_SECRET` for an MLflow server behind Cloudflare Access. Register
[LuxonisRequestHeaderProvider](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/mlflow_plugins.md)
in your application, because LuxonisML declares no MLflow entry point for it.

> **See Also**
> [luxonis_ml.tracker.tracker](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md) for the logging implementation and [luxonis_ml.tracker.mlflow_plugins](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/mlflow_plugins.md) for MLflow request-header support.

## Child Pages

 * [mlflow_plugins](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/mlflow_plugins.md)
 * [tracker](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/tracker/tracker.md)