Document MLflow system tags (mlflow#1342)

simonvanbernem · May 27, 2019 · 3482ace · 3482ace
1 parent 7426ee0
commit 3482ace
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 0 deletions.
diff --git a/docs/source/tracking.rst b/docs/source/tracking.rst
@@ -433,3 +433,40 @@ then make API requests to your remote tracking server.
     with mlflow.start_run():
         mlflow.log_param("a", 1)
         mlflow.log_metric("b", 2)
+
+.. _system_tags:
+
+System Tags
+===========
+
+You can annotate runs with arbitrary tags. Tag keys that start with ``mlflow.`` are reserved for
+internal use. The following tags are set automatically by MLflow, when appropriate:
+
++-------------------------------+----------------------------------------------------------------------------------------+
+| Key                           | Description                                                                            |
++===============================+========================================================================================+
+| ``mlflow.runName``            | Human readable name that identifies this run.                                          |
++-------------------------------+----------------------------------------------------------------------------------------+
+| ``mlflow.parentRunId``        | The ID of the parent run, if this is a nested run.                                     |
++-------------------------------+----------------------------------------------------------------------------------------+
+| ``mlflow.user``               | Identifier of the user who created the run.                                            |
++-------------------------------+----------------------------------------------------------------------------------------+
+| ``mlflow.source.type``        | Source type (possible values are ``"NOTEBOOK"``, ``"JOB"``, ``"PROJECT"``,             |
+|                               | ``"LOCAL"``, and ``"UNKNOWN"``)                                                        |
++-------------------------------+----------------------------------------------------------------------------------------+
+| ``mlflow.source.name``        | Source identifier (e.g., GitHub URL, local Python filename, name of notebook)          |
++-------------------------------+----------------------------------------------------------------------------------------+
+| ``mlflow.source.git.commit``  | Commit hash of the executed code, if in a git repository.                              |
++-------------------------------+----------------------------------------------------------------------------------------+
+| ``mlflow.source.git.branch``  | Name of the branch of the executed code, if in a git repository.                       |
++-------------------------------+----------------------------------------------------------------------------------------+
+| ``mlflow.source.git.repoURL`` | URL that the executed code was cloned from.                                            |
++-------------------------------+----------------------------------------------------------------------------------------+
+| ``mlflow.project.env``        | One of "docker" or "conda", indicating the runtime context used by the MLflow project. |
++-------------------------------+----------------------------------------------------------------------------------------+
+| ``mlflow.project.entryPoint`` | Name of the project entry point associated with the current run, if any.               |
++-------------------------------+----------------------------------------------------------------------------------------+
+| ``mlflow.docker.image.name``  | Name of the Docker image used to execute this run.                                     |
++-------------------------------+----------------------------------------------------------------------------------------+
+| ``mlflow.docker.image.id``    | ID of the Docker image used to execute this run.                                       |
++-------------------------------+----------------------------------------------------------------------------------------+
diff --git a/mlflow/tracking/fluent.py b/mlflow/tracking/fluent.py
@@ -78,6 +78,9 @@ def start_run(run_id=None, experiment_id=None, run_name=None, nested=False):
     ``start_run`` attempts to resume a run with the specified run ID and
     other parameters are ignored. ``run_id`` takes precedence over ``MLFLOW_RUN_ID``.
 
+    MLflow will set a variety of default tags on the run, as defined in
+    :ref:`MLflow system tags <system_tags>`.
+
     :param run_id: If specified, get the run with the specified UUID and log parameters
                      and metrics under that run. The run's end time is unset and its status
                      is set to running, but the run's other attributes (``source_version``,