Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/davidlandup0/microtrax

Yet Another Experiment Tracking Library. Local, minimalist, micro experiment tracking for Machine Learning/Deep Learning workflows. No accounts, no setups. 3 lines to track.
https://github.com/davidlandup0/microtrax

deep-learning experiment-tracking machine-learning scientific-computing

Last synced: 8 months ago
JSON representation

Yet Another Experiment Tracking Library. Local, minimalist, micro experiment tracking for Machine Learning/Deep Learning workflows. No accounts, no setups. 3 lines to track.

Awesome Lists containing this project

README 

          
microtrax


Yet Another Experiment Tracking Library



Local, minimalist, micro experiment tracking for Machine Learning/Deep Learning workflows.








Free. Fully local. Lightweight.






No accounts, no setups. 3 lines to track.



`microtrax` attempts to be a modern, minimalist library for experiment tracking. Inspired by TensorBoard.



Quickstart



```bash

$ pip install microtrax

```



```python

import microtrax as mtx



epochs = 10

mtx.init('./logbook_dir') #, optionally also track_resources=True)



for i in range(epochs):

    mtx.log({

        "step": i,

        "loss": epochs-i

    })



mtx.finish()

```



Then serve the dashboard:



```

$ mtx serve -f ./logbook_dir

```



This automatically starts both the FastAPI backend and React frontend!



image



It's called a quickstart as if there's anything else you can do with it. Actually, that's pretty much it.



Design Philosophy



- Free forever.

- Simplicity > feature-richness.

- Research-experience first.

- Framework agnostic - no specialized adapters for different libraries nor ecosystem favoritism. Log whatever.

- Lightweight footprint. No hogging the CPU or memory.

- Easily extendable (standard stack + simple to add new components/routes)

- No setups, no accounts, no enterprise versions.



Learning microtrax in 10 seconds



- **Experiment:** whatever happens between `mtx.init()` and `mtx.finish()`, housing a series of `mtx.log()`s.

- **Logbook:** Collection of experiments in a log directory.

- **Dashboard:** Where your visualizations go. You can select which experiments to visualize and overlay from the logbook.



No need to learn anything else to use `microtrax`.



CLI Usage



After installation, you can use the `mtx` command:



```bash

# Start the dashboard 

mtx serve -f ./logbook_dir -p 8080



# Start with Docker Compose

mtx serve -f ./logbook_dir --docker



# List all experiments in a directory

mtx list -f ./logbook_dir



# Serve with custom host/port

mtx serve -f ./logbook_dir --host 0.0.0.0 -p 8080

```



**Commands:**

- `mtx serve` - Start the interactive dashboard web server

- `mtx list` - List all experiments in the specified directory



**Options:**

- `-f, --logdir` - Directory containing experiments (default: ~/.microtrax)

- `-p, --port` - Port to run dashboard on (default: 8080)  

- `--host` - Host to bind to (default: localhost)

- `--docker` - Run using Docker Compose instead of local servers







# microtrax - Bird's Eye View



From a bird's eye view, `microtrax` has four main components:



- **Core:** Core operations like `mtx.init()`, `mtx.log()` and `mtx.finish()`, as well as handling of I/O

- **CLI:** Runner for the CLI commands like `mtx list` and `mtx serve`

- **Backend:** FastAPI server + routers for exposing a logdir's logs

- **Frontend:** React frontend for visualizing data provided by the server via Plotly



### Why React + FastAPI and not something "simpler"? 



Because this is a hackable, extendable, simple format. We want to make it as easy as possible to extend and tweak the library.

Proprietary formats, uncommon libs or "simplifying" by obscurity go against the core principles of the library.



- Need a new widget -> Add a single React component in `/frontend/src/components`

- Need a new server endpoint -> Add a single endpoint in FastAPI's routers in `/backend/routers`



A highly standard stack ensures that the widest number of users can easily and comfortably understand and extend the library as needed.



```



  ┌─────────────────────────────────────────────────────────────────────────────┐

  │                               microtrax                                     │

  └─────────────────────────────────────────────────────────────────────────────┘



  ┌─────────────────┐      ┌───────────────────┐    ┌─────────────────────────────┐

  │   User Code     │      │   File System     │    │        Dashboard            │

  │                 │      │                   │    │                             │

  │  mtx.init()     │─────▶│  ~/.microtrax/    │◀───│ ┌─────────────────────────┐ │

  │  mtx.log({...}) │      │    experiments/   │    │ │    React Frontend       │ │

  │  mtx.finish()   │      │    resources/     │    │ │    (Port 8080)          │ │

  │                 │      │                   │    │ │  - Plot visualizations  │ │

  └─────────────────┘      │  exp_id.jsonl     │    │ │  - Experiment browser   │ │

                           │  (w/ base64 imgs) │    │ │  - Settings panel       │ │

  ┌───────────────────┐    │  resources.jsonl  │    │ └─────────────────────────┘ │

  │   Core Module     │    │                   │    │             │               │

  │                   │───▶│                   │    │           HTTP              │

  │ • Experiment      │    └───────────────────┘    │             │               │

  │ • ResourceTracker │                             │ ┌─────────────────────────┐ │

  │ • I/O Utils       │   ┌──────────────────┐      │ │   FastAPI Backend       │ │

  │ • Image Processing│   │       CLI        │──────│ │   (Port 8080)           │ │

  └───────────────────┘   │                  │      │ │                         │ │

                          │  mtx serve       │      │ │  /api/experiments       │ │

                          │  mtx list        │      │ │  /api/plots             │ │

                          └──────────────────┘      │ │  /api/images            │ │

                                                    │ │  /api/plot-options      │ │

                                                    │ └─────────────────────────┘ │

                                                    └─────────────────────────────┘



  Data Flow:

  User Code ─> JSONL -> File System -> Backend -> JSON -> Frontend -> User

```



### Frontend Serving



The frontend is served as static files on the same port as the backend (`localhost:8080`).

You can separately build the frontend for hot reloads during development of new features if you're customizing the library.



# Docker Compose



You can also run the `microtrax` dashboard through Docker Compose for containerized deployment.



## Setup



1. Configure your experiment log directory in `.env`:

```bash

# Directory where experiment logs are stored

MICROTRAX_LOGDIR=./my_experiments

```



2. Run the stack:

```bash

docker-compose up

```



This will start:

- **Backend API and frontend served** on port 8080



## Configuration



The `MICROTRAX_LOGDIR` environment variable specifies where your experiment logs are stored on the host machine. This directory is mounted into the backend container at `/data`.



Default: `~/.microtrax` if not specified



## Access



- Dashboard: http://localhost:8080

- Backend API: http://localhost:8080



The frontend handles routing and proxies `/api/*` requests to the backend automatically.



# Contributing



We welcome contributions to `microtrax`! 

It's community-first, so any and every issue and idea will be considered.

This guide will help you get started if you'd like to propose a change.



## Getting Started



1. **Fork and clone the repository**

    

```bash

$ git clone https://github.com/yourusername/microtrax.git

$ cd microtrax

```



2. Set up development environment



```bash

# Install Python dependencies

$ pip install microtrax

$ pip install pytest ruff



# Install and build frontend

$ cd microtrax/frontend

$ npm install

$ npm run build

```



3. Run tests



```bash

# Python tests

pytest

# Format code

make format

```



## Development Workflow



### Backend Changes



- Location: `/microtrax/backend/`

- For routers: `/backend/routers/`

- For endpoints: `/backend/routers/router_name.py`

- For business logic: `/backend/services/`

- For data models: `/backend/domain/schemas.py`



### Frontend Changes



- Location: `/microtrax/frontend/src/`

- For new components: `/frontend/src/components/`



### Core Changes



- Location: `/microtrax/core.py`, `/microtrax/io_utils.py`

- Experiment tracking logic

- File I/O operations

- Image processing



### Code Standards

- Python: Follow PEP 8, use type hints, run ruff for linting



### Submitting Changes



1. Create a feature branch

```

git checkout -b feature/your-feature-name

```



2. Make your changes

3. Test

4. Submit a pull request



### Questions?



- Check existing issues on GitHub

- Start a discussion for feature ideas



# Citation



If you happen to use `microtrax` for your research, and publish your results - we'd appreciate a citation~



```

@misc{landup2025microtrax,

  title={microtrax},

  author={David Landup},

  year={2025},

  howpublished={\url{https://github.com/DavidLandup0/microtrax/}},

}

```