TensorBoard 2.0.2

.travis.yml

@@ -57,6 +57,7 @@ install:
   - pip install grpcio-testing==1.24.3
   - pip install 'google-auth >= 1.6.3, < 2'
   - pip install 'google-auth-oauthlib >= 0.4.1, < 0.5'
+  - pip install requests==2.21.0
   - yarn install --ignore-engines
   # Uninstall older Travis numpy to avoid upgrade-in-place issues.
   - pip uninstall -y numpy

RELEASE.md

@@ -1,3 +1,15 @@
+# Release 2.0.2
+
+## Features
+
+- Improvements to [TensorBoard.dev] support:
+  - New `tensorboard dev list` subcommand lists all experiments uploaded to
+    TensorBoard.dev (#2903)
+  - In the event of a transient backend issue or permanent breaking change, the
+    uploader can now gracefully degrade and print a diagnostic (#2879)
+
+[TensorBoard.dev]: https://tensorboard.dev/
+
 # Release 2.0.1
 
 ## Features

tensorboard/BUILD

@@ -373,6 +373,14 @@ py_library(
     visibility = ["//visibility:public"],
 )
 
+py_library(
+    name = "expect_requests_installed",
+    # This is a dummy rule used as a requests dependency in open-source.
+    # We expect requests to already be installed on the system, e.g., via
+    # `pip install requests`.
+    visibility = ["//visibility:public"],
+)
+
 filegroup(
     name = "tf_web_library_default_typings",
     srcs = [

tensorboard/pip_package/setup.py

@@ -32,6 +32,7 @@
     'markdown >= 2.6.8',
     'numpy >= 1.12.0',
     'protobuf >= 3.6.0',
+    'requests >= 2.21.0, < 3',
     'setuptools >= 41.0.0',
     'six >= 1.10.0',
     'werkzeug >= 0.11.15',

tensorboard/uploader/BUILD

@@ -20,6 +20,7 @@ py_library(
         "//tensorboard:expect_grpc_installed",
         "//tensorboard/uploader/proto:protos_all_py_pb2",
         "//tensorboard/util:grpc_util",
+        "@org_pythonhosted_six",
     ],
 )
 
@@ -56,7 +57,9 @@ py_library(
         ":auth",
         ":dev_creds",
         ":exporter_lib",
+        ":server_info",
         ":uploader_lib",
+        ":util",
         "//tensorboard:expect_absl_app_installed",
         "//tensorboard:expect_absl_flags_argparse_flags_installed",
         "//tensorboard:expect_absl_flags_installed",
@@ -201,3 +204,29 @@ py_test(
         "//tensorboard:test",
     ],
 )
+
+py_library(
+    name = "server_info",
+    srcs = ["server_info.py"],
+    deps = [
+        "//tensorboard:expect_requests_installed",
+        "//tensorboard:version",
+        "//tensorboard/uploader/proto:protos_all_py_pb2",
+        "@com_google_protobuf//:protobuf_python",
+    ],
+)
+
+py_test(
+    name = "server_info_test",
+    size = "medium",  # local network requests
+    timeout = "short",
+    srcs = ["server_info_test.py"],
+    deps = [
+        ":server_info",
+        "//tensorboard:expect_futures_installed",
+        "//tensorboard:test",
+        "//tensorboard:version",
+        "//tensorboard/uploader/proto:protos_all_py_pb2",
+        "@org_pocoo_werkzeug",
+    ],
+)

tensorboard/uploader/exporter.py

@@ -26,6 +26,8 @@
 import string
 import time
 
+import six
+
 from tensorboard.uploader.proto import export_service_pb2
 from tensorboard.uploader import util
 from tensorboard.util import grpc_util
@@ -126,13 +128,13 @@ def export(self, read_time=None):
 
   def _request_experiment_ids(self, read_time):
     """Yields all of the calling user's experiment IDs, as strings."""
-    request = export_service_pb2.StreamExperimentsRequest(limit=_MAX_INT64)
-    util.set_timestamp(request.read_timestamp, read_time)
-    stream = self._api.StreamExperiments(
-        request, metadata=grpc_util.version_metadata())
-    for response in stream:
-      for experiment_id in response.experiment_ids:
-        yield experiment_id
+    for experiment in list_experiments(self._api, read_time=read_time):
+      if isinstance(experiment, export_service_pb2.Experiment):
+        yield experiment.experiment_id
+      elif isinstance(experiment, six.string_types):
+        yield experiment
+      else:
+        raise AssertionError("Unexpected experiment type: %r" % (experiment,))
 
   def _request_scalar_data(self, experiment_id, read_time):
     """Yields JSON-serializable blocks of scalar data."""
@@ -163,6 +165,38 @@ def _request_scalar_data(self, experiment_id, read_time):
       }
 
 
+def list_experiments(api_client, fieldmask=None, read_time=None):
+  """Yields all of the calling user's experiments.
+
+  Args:
+    api_client: A TensorBoardExporterService stub instance.
+    fieldmask: An optional `export_service_pb2.ExperimentMask` value.
+    read_time: A fixed timestamp from which to export data, as float seconds
+      since epoch (like `time.time()`). Optional; defaults to the current
+      time.
+
+  Yields:
+    For each experiment owned by the user, an `export_service_pb2.Experiment`
+    value, or a simple string experiment ID for older servers.
+  """
+  if read_time is None:
+    read_time = time.time()
+  request = export_service_pb2.StreamExperimentsRequest(limit=_MAX_INT64)
+  util.set_timestamp(request.read_timestamp, read_time)
+  if fieldmask:
+    request.experiments_mask.CopyFrom(fieldmask)
+  stream = api_client.StreamExperiments(
+      request, metadata=grpc_util.version_metadata())
+  for response in stream:
+    if response.experiments:
+      for experiment in response.experiments:
+        yield experiment
+    else:
+      # Old servers.
+      for experiment_id in response.experiment_ids:
+        yield experiment_id
+
+
 class OutputDirectoryExistsError(ValueError):
   pass
 

tensorboard/uploader/exporter_test.py

@@ -45,15 +45,7 @@
 class TensorBoardExporterTest(tb_test.TestCase):
 
   def _create_mock_api_client(self):
-    # Create a stub instance (using a test channel) in order to derive a mock
-    # from it with autospec enabled. Mocking TensorBoardExporterServiceStub
-    # itself doesn't work with autospec because grpc constructs stubs via
-    # metaclassing.
-    test_channel = grpc_testing.channel(
-        service_descriptors=[], time=grpc_testing.strict_real_time())
-    stub = export_service_pb2_grpc.TensorBoardExporterServiceStub(test_channel)
-    mock_api_client = mock.create_autospec(stub)
-    return mock_api_client
+    return _create_mock_api_client()
 
   def _make_experiments_response(self, eids):
     return export_service_pb2.StreamExperimentsResponse(experiment_ids=eids)
@@ -323,6 +315,62 @@ def test_propagates_mkdir_errors(self):
     mock_api_client.StreamExperimentData.assert_not_called()
 
 
+class ListExperimentsTest(tb_test.TestCase):
+
+  def test_experiment_ids_only(self):
+    mock_api_client = _create_mock_api_client()
+
+    def stream_experiments(request, **kwargs):
+      del request  # unused
+      yield export_service_pb2.StreamExperimentsResponse(
+          experiment_ids=["123", "456"])
+      yield export_service_pb2.StreamExperimentsResponse(
+          experiment_ids=["789"])
+
+    mock_api_client.StreamExperiments = mock.Mock(wraps=stream_experiments)
+    gen = exporter_lib.list_experiments(mock_api_client)
+    mock_api_client.StreamExperiments.assert_not_called()
+    self.assertEqual(list(gen), ["123", "456", "789"])
+
+  def test_mixed_experiments_and_ids(self):
+    mock_api_client = _create_mock_api_client()
+
+    def stream_experiments(request, **kwargs):
+      del request  # unused
+
+      # Should include `experiment_ids` when no `experiments` given.
+      response = export_service_pb2.StreamExperimentsResponse()
+      response.experiment_ids.append("123")
+      response.experiment_ids.append("456")
+      yield response
+
+      # Should ignore `experiment_ids` in the presence of `experiments`.
+      response = export_service_pb2.StreamExperimentsResponse()
+      response.experiment_ids.append("999")  # will be omitted
+      response.experiments.add(experiment_id="789")
+      response.experiments.add(experiment_id="012")
+      yield response
+
+      # Should include `experiments` even when no `experiment_ids` are given.
+      response = export_service_pb2.StreamExperimentsResponse()
+      response.experiments.add(experiment_id="345")
+      response.experiments.add(experiment_id="678")
+      yield response
+
+    mock_api_client.StreamExperiments = mock.Mock(wraps=stream_experiments)
+    gen = exporter_lib.list_experiments(mock_api_client)
+    mock_api_client.StreamExperiments.assert_not_called()
+    expected = [
+        "123",
+        "456",
+        export_service_pb2.Experiment(experiment_id="789"),
+        export_service_pb2.Experiment(experiment_id="012"),
+        export_service_pb2.Experiment(experiment_id="345"),
+        export_service_pb2.Experiment(experiment_id="678"),
+    ]
+    self.assertEqual(list(gen), expected)
+
+
 class MkdirPTest(tb_test.TestCase):
 
   def test_makes_full_chain(self):
@@ -384,5 +432,17 @@ def test_propagates_other_errors(self):
     self.assertEqual(cm.exception.errno, errno.ENOENT)
 
 
+def _create_mock_api_client():
+  # Create a stub instance (using a test channel) in order to derive a mock
+  # from it with autospec enabled. Mocking TensorBoardExporterServiceStub
+  # itself doesn't work with autospec because grpc constructs stubs via
+  # metaclassing.
+  test_channel = grpc_testing.channel(
+      service_descriptors=[], time=grpc_testing.strict_real_time())
+  stub = export_service_pb2_grpc.TensorBoardExporterServiceStub(test_channel)
+  mock_api_client = mock.create_autospec(stub)
+  return mock_api_client
+
+
 if __name__ == "__main__":
   tb_test.main()

tensorboard/uploader/proto/BUILD

@@ -6,11 +6,13 @@ licenses(["notice"])  # Apache 2.0
 
 exports_files(["LICENSE"])
 
+# TODO(@wchargin): Split more granularly.
 tb_proto_library(
     name = "protos_all",
     srcs = [
         "export_service.proto",
         "scalar.proto",
+        "server_info.proto",
         "write_service.proto",
     ],
     has_services = True,

tensorboard/uploader/proto/export_service.proto

@@ -27,19 +27,80 @@ message StreamExperimentsRequest {
   string user_id = 2;
   // Limits the number of experiment IDs returned. This is useful to check if
   // user might have any data by setting limit=1. Also useful to preview the
-  // list of experiments.
+  // list of experiments. TODO(@karthikv2k): Support pagination.
   int64 limit = 3;
-  // TODO(@karthikv2k): Support pagination.
+  // Field mask for what experiment data to return via the `experiments` field
+  // on the response. If not specified, this should be interpreted the same as
+  // an empty message: i.e., only the experiment ID should be returned.
+  ExperimentMask experiments_mask = 4;
 }
 
-// Streams experiment IDs returned from TensorBoard.dev.
+// Streams experiment metadata (ID, creation time, etc.) from TensorBoard.dev.
 message StreamExperimentsResponse {
-  // List of experiment IDs for the experiments owned by the user. The entire
-  // list of experiments owned by the user is streamed in batches and each batch
-  // contains a list of experiment IDs. A consumer of this stream needs to
-  // concatenate all these lists to get the full response. The order of
-  // experiment IDs in the stream is not defined.
+  // Deprecated in favor of `experiments`. If a response has `experiments` set,
+  // clients should ignore `experiment_ids` entirely. Otherwise, clients should
+  // treat `experiment_ids` as a list of `experiments` for which only the
+  // `experiment_id` field is set, with the understanding that the other fields
+  // were not populated regardless of the requested field mask.
+  //
+  // For example, the following responses should be treated the same:
+  //
+  //     # Response 1
+  //     experiment_ids: "123"
+  //     experiment_ids: "456"
+  //
+  //     # Response 2
+  //     experiments { experiment_id: "123" }
+  //     experiments { experiment_id: "456" }
+  //
+  //     # Response 3
+  //     experiment_ids: "789"
+  //     experiments { experiment_id: "123" }
+  //     experiments { experiment_id: "456" }
+  //
+  // See documentation on `experiments` for batching semantics.
   repeated string experiment_ids = 1;
+  // List of experiments owned by the user. The entire list of experiments
+  // owned by the user is streamed in batches and each batch contains a list of
+  // experiments. A consumer of this stream needs to concatenate all these
+  // lists to get the full response. The order of experiments in the stream is
+  // not defined. Every response will contain at least one experiment.
+  //
+  // These messages may be partially populated, in accordance with the field
+  // mask given in the request.
+  repeated Experiment experiments = 2;
+}
+
+// Metadata about an experiment.
+message Experiment {
+  // Permanent ID of this experiment; e.g.: "AdYd1TgeTlaLWXx6I8JUbA".
+  string experiment_id = 1;
+  // The time that the experiment was created.
+  google.protobuf.Timestamp create_time = 2;
+  // The time that the experiment was last modified: i.e., the most recent time
+  // that scalars were added to the experiment.
+  google.protobuf.Timestamp update_time = 3;
+  // The number of scalars in this experiment, across all time series.
+  int64 num_scalars = 4;
+  // The number of distinct run names in this experiment.
+  int64 num_runs = 5;
+  // The number of distinct tag names in this experiment. A tag name that
+  // appears in multiple runs will be counted only once.
+  int64 num_tags = 6;
+}
+
+// Field mask for `Experiment`. The `experiment_id` field is always implicitly
+// considered to be requested. Other fields of `Experiment` will be populated
+// if their corresponding bits in the `ExperimentMask` are set. The server may
+// choose to populate fields that are not explicitly requested.
+message ExperimentMask {
+  reserved 1;
+  reserved "experiment_id";
+  bool create_time = 2;
+  bool update_time = 3;
+  bool num_scalars = 4;
+  bool num_runs = 5;
+  bool num_tags = 6;
 }
 
 // Request to stream scalars from all the runs and tags in an experiment.