Merge pull request #40 from comet-ml/CM-1630-logging-remote-asset

[CM-1630] Add support for logging remote assets

Author: Lothiraldan

README.md

@@ -5,8 +5,8 @@
 |--------|--------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|----------------------------------------------------------------------------|
 | master | [![CI](https://github.com/comet-ml/comet-java-sdk/actions/workflows/ci-maven.yml/badge.svg)](https://github.com/comet-ml/comet-java-sdk/workflows/ci-maven.yml) | [![codecov](https://codecov.io/gh/comet-ml/comet-java-sdk/branch/master/graph/badge.svg)](https://codecov.io/gh/comet-ml/comet-java-sdk) | [![Lint Code Base](https://github.com/comet-ml/comet-java-sdk/actions/workflows/super-linter.yml/badge.svg)](https://github.com/comet-ml/comet-java-sdk/actions/workflows/super-linter.yml) | [![CodeQL](https://github.com/comet-ml/comet-java-sdk/actions/workflows/codeQL.yml/badge.svg)](https://github.com/comet-ml/comet-java-sdk/actions/workflows/codeQL.yml) |
 
-### Using Comet Java SDK:
-#### Add dependency to pom.xml:
+## Using Comet Java SDK
+### Add dependency to the pom.xml
 ```
     <dependencies>
         <dependency>
@@ -16,44 +16,70 @@
         </dependency>
     </dependencies>
 ```
-#### Create experiment and log metrics and parameters:
+### Create experiment and log metrics and parameters
 ```java
 OnlineExperiment experiment = ExperimentBuilder.OnlineExperiment()
                 .withApiKey("someApiKey")
                 .withProjectName("someProject")
                 .withWorkspace("someWorkspace")
                 .build();
-        experiment.setExperimentName("My experiment");
-        experiment.logParameter("batch_size", "500");
-        experiment.logMetric("strMetric", 123);
-        experiment.end();
+    experiment.setExperimentName("My experiment");
+    experiment.logParameter("batch_size", "500");
+    experiment.logMetric("strMetric", 123);
+    experiment.end();
 ```
-
-#### Configure you experiment object:
+The ```OnlineExperiment``` also can be used with [try-with-resources](https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html) statement which automatically
+handles call to the ```experiment.end()```.
 ```java
-# Configuration hierarchy:
-Environment Variable > Configuration File Override > Default config file (application.conf)
+try (OnlineExperiment experiment = ExperimentBuilder.OnlineExperiment()
+                .withApiKey("someApiKey")
+                .withProjectName("someProject")
+                .withWorkspace("someWorkspace")
+                .build()) {
+    experiment.setExperimentName("My experiment");
+    experiment.logParameter("batch_size", "500");
+    experiment.logMetric("strMetric", 123);
+} catch (Exception e) {
+    e.printStackTrace();
+}
+```
 
-# Setting configuration in code:
-OnlineExperimentImpl.builder().withApiKey("someApiKey").build();
+### Configure experiment object
 
-# Override configuration file (can have partial keys)
-OnlineExperimentImpl.builder().withConfig(new File("/tmp/comet.conf")).build();
+#### Configuration sources hierarchy
 
-# Read from environment variables OR from configuration file in classpath (application.conf)
-OnlineExperimentImpl.builder().build();
-```
+The configuration parameters search order as following (first-listed are higher priority):
+ * system properties or environment variables
+ * configuration file set by call to [```withConfigOverride(java.io.File)```](comet-java-client/src/main/java/ml/comet/experiment/builder/BaseCometBuilder.java)
+ * ```application.conf``` (all resources on the classpath with this name)
+ * ```reference.conf``` (all resources on the classpath with this name)
+ 
+#### Programmatic configuration
 
-#### Full list of environment variables:
+It is possible to override some or all configuration parameters programmatically when 
+you create a new experiment's instance using [```ExperimentBuilder```](comet-java-client/src/main/java/ml/comet/experiment/ExperimentBuilder.java)
+factory.
 ```java
+// Setting specific configuration parameters with builder
+ExperimentBuilder.OnlineExperiment().withApiKey("someApiKey").build();
+
+// Override configuration file (can have partial keys)
+ExperimentBuilder.OnlineExperiment().withConfigOverride(new File("/tmp/comet.conf")).build();
+
+// Read from environment variables OR from configuration file in classpath (application.conf)
+ExperimentBuilder.OnlineExperiment().build();
+```
+
+### Full list of environment variables
+```text
 COMET_API_KEY
 COMET_PROJECT_NAME
 COMET_WORKSPACE_NAME
 COMET_BASE_URL
 COMET_MAX_AUTH_RETRIES
 ```
 
-#### Examples
+### Examples
 
 * You also can check 
   * [sample experiment](comet-examples/src/main/java/ml/comet/examples/OnlineExperimentExample.java)

comet-examples/src/main/java/ml/comet/examples/OnlineExperimentExample.java

@@ -6,6 +6,7 @@
 import org.apache.commons.io.file.PathUtils;
 
 import java.io.IOException;
+import java.net.URI;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.Objects;
@@ -53,14 +54,14 @@ public static void main(String[] args) {
 
         try {
             OnlineExperimentExample.run(experiment);
-        } catch (IOException e) {
+        } catch (Throwable e) {
             e.printStackTrace();
         } finally {
             experiment.end();
         }
     }
 
-    private static void run(OnlineExperiment experiment) throws IOException {
+    private static void run(OnlineExperiment experiment) throws Exception {
         experiment.setExperimentName("Java-SDK 2.0.2");
         experiment.nextStep();
 
@@ -81,16 +82,23 @@ private static void run(OnlineExperiment experiment) throws IOException {
         experiment.logParameter("batch_size", "500");
         experiment.logParameter("learning_rate", 12);
 
+        // upload assets
+        //
         experiment.uploadAsset(getResourceFile(CHART_IMAGE_FILE), "amazing chart.png", false);
         experiment.uploadAsset(getResourceFile(MODEL_FILE), false,
                 ExperimentContext.builder().withContext("train").build());
 
         experiment.nextStep();
 
-        // upload assets from folder
+        // upload asset files from folder
+        //
         Path assetDir = copyResourcesToTmpDir();
         experiment.logAssetFolder(assetDir.toFile(), true, true);
 
+        // log remote assets
+        //
+        experiment.logRemoteAsset(new URI("s3://bucket/folder/dataCorpus.hd5"), "modelDataCorpus", false);
+
         experiment.logOther("Parameter", 4);
 
         System.out.println("Epoch 1/20");

comet-java-client/src/main/java/ml/comet/experiment/Experiment.java

@@ -22,7 +22,7 @@
  * <p>Your {@link Experiment} will automatically track and collect many things and will also
  * allow you to manually report anything.
  */
-public interface Experiment {
+public interface Experiment extends AutoCloseable {
 
     /**
      * Get the experiment key returned by Comet.

comet-java-client/src/main/java/ml/comet/experiment/OnlineExperiment.java

@@ -4,6 +4,8 @@
 
 import java.io.File;
 import java.io.IOException;
+import java.net.URI;
+import java.util.Map;
 
 /**
  * The {@code OnlineExperiment} should be used to asynchronously update data of your Comet.ml experiment.
@@ -15,7 +17,7 @@
  * <p>Also, it is possible to use {@link #setStep(long)}, {@link #setEpoch(long)},
  * and {@link #setContext(String)} which will bbe automatically associated with related logged data records.
  */
-public interface OnlineExperiment extends Experiment, AutoCloseable {
+public interface OnlineExperiment extends Experiment {
 
     /**
      * Turn on intercept of stdout and stderr and the logging of both in Comet.
@@ -141,4 +143,26 @@ public interface OnlineExperiment extends Experiment, AutoCloseable {
     void logAssetFolder(File folder, boolean logFilePath, boolean recursive);
 
     void logAssetFolder(File folder, boolean logFilePath);
+
+    /**
+     * Logs a Remote Asset identified by a {@link URI}. A Remote Asset is an asset but its content is not uploaded
+     * and stored on Comet. Rather a link for its location is stored, so you can identify and distinguish
+     * between two experiment using different version of a dataset stored somewhere else.
+     *
+     * @param uri       the {@link URI} pointing to the remote asset location. There is no imposed format,
+     *                  and it could be a private link.
+     * @param fileName  the optional "name" of the remote asset, could be a dataset name, a model file name.
+     * @param overwrite if {@code true} will overwrite all existing assets with the same name.
+     * @param metadata  Some additional data to attach to the remote asset.
+     *                  The dictionary values must be JSON compatible.
+     * @param context   the experiment context to be associated with the logged assets.
+     */
+    void logRemoteAsset(URI uri, String fileName, boolean overwrite,
+                        Map<String, Object> metadata, ExperimentContext context);
+
+    void logRemoteAsset(URI uri, String fileName, boolean overwrite, Map<String, Object> metadata);
+
+    void logRemoteAsset(URI uri, String fileName, boolean overwrite);
+
+    void logRemoteAsset(URI uri, boolean overwrite);
 }

comet-java-client/src/main/java/ml/comet/experiment/context/ExperimentContext.java

@@ -4,6 +4,8 @@
 import lombok.NonNull;
 import org.apache.commons.lang3.StringUtils;
 
+import java.util.Objects;
+
 /**
  * Describes context of the {@link ml.comet.experiment.Experiment}.
  */
@@ -48,6 +50,17 @@ public ExperimentContext(long step) {
         this(step, 0);
     }
 
+    /**
+     * The copy constructor.
+     *
+     * @param other the other {@link ExperimentContext} to be used as source.
+     */
+    public ExperimentContext(ExperimentContext other) {
+        this.step = other.step;
+        this.epoch = other.epoch;
+        this.context = other.context;
+    }
+
     /**
      * Merges not empty values from other context into this one.
      *
@@ -58,10 +71,10 @@ public void mergeFrom(@NonNull ExperimentContext other) {
             return;
         }
 
-        if (other.step != null) {
+        if (Objects.nonNull(other.step)) {
             this.step = other.step;
         }
-        if (other.epoch != null) {
+        if (Objects.nonNull(other.epoch)) {
             this.epoch = other.epoch;
         }
         if (StringUtils.isNotBlank(other.context)) {

comet-java-client/src/main/java/ml/comet/experiment/impl/ApiExperimentImpl.java

@@ -38,9 +38,6 @@ private ApiExperimentImpl(
         if (logger != null) {
             this.logger = logger;
         }
-
-        // initialize this experiment
-        this.init();
     }
 
     @Override
@@ -77,6 +74,11 @@ public Optional<String> getExperimentLink() {
         }
     }
 
+    @Override
+    public void close() {
+        this.end();
+    }
+
     /**
      * Returns builder to create {@link Experiment} instance.
      *
@@ -136,11 +138,20 @@ public ApiExperiment build() {
             if (StringUtils.isBlank(this.apiKey)) {
                 this.apiKey = COMET_API_KEY.getString();
             }
-            return new ApiExperimentImpl(
+            ApiExperimentImpl experiment = new ApiExperimentImpl(
                     this.apiKey, this.experimentKey, this.logger,
                     COMET_BASE_URL.getString(),
                     COMET_MAX_AUTH_RETRIES.getInt(),
                     COMET_TIMEOUT_CLEANING_SECONDS.getDuration());
+            try {
+                // initialize experiment
+                experiment.init();
+            } catch (Throwable ex) {
+                // release hold resources and signal to user about failure
+                experiment.end();
+                throw ex;
+            }
+            return experiment;
         }
     }
 }

comet-java-client/src/main/java/ml/comet/experiment/impl/BaseExperiment.java

@@ -400,12 +400,12 @@ public void uploadAsset(@NonNull File file, @NonNull String fileName,
     }
 
     @Override
-    public void uploadAsset(File asset, String fileName, boolean overwrite, long step, long epoch) {
+    public void uploadAsset(@NonNull File asset, String fileName, boolean overwrite, long step, long epoch) {
         this.uploadAsset(asset, fileName, overwrite, new ExperimentContext(step, epoch));
     }
 
     @Override
-    public void uploadAsset(File asset, boolean overwrite, ExperimentContext context) {
+    public void uploadAsset(@NonNull File asset, boolean overwrite, @NonNull ExperimentContext context) {
         this.uploadAsset(asset, asset.getName(), overwrite, context);
     }