add documentation regarding limitations of log_metric method

Author: danabens

src/smexperiments/tracker.py

@@ -82,6 +82,8 @@ def load(
     ):
         """Create a new ``Tracker`` by loading an existing trial component.
 
+        Note that `log_metric` will only work from a training job host.
+
         Examples:
             .. code-block:: python
 
@@ -142,7 +144,7 @@ def load(
         else:
             raise ValueError('Could not load TrialComponent. Specify a trial_component_name or invoke "create"')
 
-        # if running in a SageMaker context write metrics to file
+        # metrics require the metrics agent running on training job hosts
         if not trial_component_name and tce.environment_type == _environment.EnvironmentType.SageMakerTrainingJob:
             metrics_writer = metrics.SageMakerFileMetricsWriter()
         else:
@@ -168,6 +170,8 @@ def create(
     ):
         """Create a new ``Tracker`` by creating a new trial component.
 
+        Note that `log_metric` will _not_ work when tracker is created this way.
+
         Examples
             .. code-block:: python
 
@@ -197,7 +201,10 @@ def create(
             sagemaker_boto_client=sagemaker_boto_client,
         )
 
-        metrics_writer = metrics.SageMakerFileMetricsWriter()
+        # metrics require the metrics agent running on training job hosts and in which case the load
+        # method should be used because it loads the trial component associated with the currently
+        # running training job
+        metrics_writer = None
 
         return cls(
             tc,
@@ -364,7 +371,10 @@ def log_input_artifact(self, file_path, name=None, media_type=None):
         self._lineage_artifact_tracker.add_input_artifact(name, s3_uri, etag, media_type)
 
     def log_metric(self, metric_name, value, timestamp=None, iteration_number=None):
-        """Record a scalar metric value for this TrialComponent to file, not SageMaker.
+        """Record a scalar metric value for this TrialComponent.
+
+        Note that metrics logged with this method will only appear in SageMaker when this method
+        is called from a training job host.
 
         Examples
             .. code-block:: python

tests/unit/test_tracker.py

@@ -151,12 +151,7 @@ def test_create(boto3_session, sagemaker_boto_client):
     )
     assert trial_component_name == tracker_created.trial_component.trial_component_name
 
-    assert tracker_created._metrics_writer is not None
-
-    tracker_created._metrics_writer = unittest.mock.Mock()
-    now = datetime.datetime.now()
-    tracker_created.log_metric("foo", 1.0, 1, now)
-    tracker_created._metrics_writer.log_metric.assert_called_with("foo", 1.0, 1, now)
+    assert tracker_created._metrics_writer is None
 
 
 @pytest.fixture