Overview
To use Comet’s Java SDK programming interface, you will first need a Comet API key from your account settings or by navigating to https://www.comet.com/api/my/settings/.
Once you have your key, you must do one of the following:
- Add Comet to your dependencies
- Download the latest release
- Clone Comet’s Java SDK
The full reference documentation of the Java SDK is available on javadoc.io. This documentation is auto-generated as part of each Java SDK release to ensure it is always up to date.
Further details are provided below.
Experiment¶
The core concept of Comet's Java API is the Experiment interface with two implementations:
OnlineExperiment is a specific run of a script that generated a result such as training a model on a single set of hyperparameters. OnlineExperimentlets you asynchronously log script output (stdout/stderr), parameters, metrics, and other items on any Java-based program.
While OnlineExperiment is for new Experiments, ApiExperiment is for existing ones. ApiExperiment synchronously fetches or updates data on a previously created Experiment.
CometApi stands for common project queries. CometApi can fetch all user workspaces, find Experiments by project id, and more.
Java configuration¶
Before you can use Comet, you must configure the Comet Experiment object with your API key, project and workspace names in your application.conf file, or as an environment variable.
Use of the following methods to do this:
- Using default application.conf (this file should be saved in the classpath) add
cometkey:comet { url = "https://www.comet.com" maxAuthRetries = 4 apiKey = "XXXX" project = "java-sdk" workspace = "my-team" } Overriding with your own
comet.conf:ExperimentBuilder.OnlineExperiment().withConfigOverride(new File("comet.conf")).build()Using environment variables:
COMET_API_KEY COMET_PROJECT_NAME COMET_WORKSPACE_NAME COMET_BASE_URL COMET_MAX_AUTH_RETRIESCreating configured instance of the Comet Experiment using
ExperimentBuilder: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();
Also, OnlineExperiment can be used with a try-with-resources statement that automatically handles calls to the experiment.end().
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();
}
Example¶
See the complete Comet Java SDK in our GitHub repository.
Here is an end-to-end example showing the Java SDK in action. This file is saved in comet-examples/src/main/java/ml/comet/examples/OnlineExperimentExample.java:
package ml.comet.examples;
import ml.comet.experiment.ExperimentBuilder;
import ml.comet.experiment.OnlineExperiment;
import ml.comet.experiment.context.ExperimentContext;
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;
import static ml.comet.examples.Utils.getResourceFile;
import static ml.comet.examples.Utils.readResourceToString;
/**
* Provides variety of example logging using OnlineExperiment.
*
* <p>To run from command line execute the following at the root of this module:
* <pre>
* COMET_API_KEY=your_api_key \
* COMET_WORKSPACE_NAME=your_workspace \
* COMET_PROJECT_NAME=your_project_name \
* mvn exec:java -Dexec.mainClass="ml.comet.examples.OnlineExperimentExample"
* </pre>
* Make sure to provide correct values above.
*/
public class OnlineExperimentExample {
private static final String CHART_IMAGE_FILE = "chart.png";
private static final String MODEL_FILE = "model.hd5";
private static final String HTML_REPORT_FILE = "report.html";
private static final String GRAPH_JSON_FILE = "graph.json";
private static final String CODE_FILE = "code_sample.py";
/**
* The main entry point to the example.
*
* @param args the command line arguments if any.
*/
public static void main(String[] args) {
//this will take configs from /comet-java-sdk/comet-examples/src/main/resources/application.conf
//be sure you have set up apiKey, project, workspace in defaults.conf before you start!
OnlineExperiment experiment = ExperimentBuilder
.OnlineExperiment()
.interceptStdout()
.build();
//you can use a default builder or just inject params
//OnlineExperiment experiment = ExperimentBuilder.OnlineExperiment().builder();
try {
OnlineExperimentExample.run(experiment);
} catch (Throwable e) {
e.printStackTrace();
} finally {
experiment.end();
}
}
private static void run(OnlineExperiment experiment) throws Exception {
experiment.setExperimentName("Java-SDK 2.0.2");
experiment.nextStep();
//metric can be a number, string , or double
experiment.logMetric("strMetric", "123");
experiment.logMetric("numMetric", 123, 123, 4);
experiment.nextEpoch();
experiment.logMetric("doubleMetric", 123.5d);
experiment.setEpoch(3);
generateCharts(experiment);
experiment.setStep(1234);
experiment.logHtml(generateCustomHtmlReport(), false);
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 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");
System.out.println("- loss: 0.7858 - acc: 0.7759 - val_loss: 0.3416 - val_acc: 0.9026");
experiment.logGraph(readResourceToString(GRAPH_JSON_FILE));
experiment.logCode(getResourceFile(CODE_FILE),
ExperimentContext.builder().withContext("test").build());
System.out.println("===== Experiment completed ====");
// will close connection, if not called connection will close on jvm exit
experiment.end();
// remove tmp directory
PathUtils.deleteDirectory(assetDir);
}
private static void generateCharts(OnlineExperiment experiment) {
long currentStep = experiment.getStep();
for (int i = 1; i < 15; i++) {
experiment.logMetric("numMetric", 123 + i, currentStep + i, getUpdatedEpochValue(experiment));
}
for (int i = 1; i < 15; i++) {
experiment.logMetric("strMetric", "123" + i, currentStep + i, getUpdatedEpochValue(experiment));
}
for (int i = 1; i < 15; i++) {
experiment.logMetric("doubleMetric", 123.12d + i, currentStep + i, getUpdatedEpochValue(experiment));
}
}
private static String generateCustomHtmlReport() throws IOException {
return readResourceToString("report.html");
}
private static long getUpdatedEpochValue(OnlineExperiment experiment) {
return experiment.getEpoch() + experiment.getStep() / 5;
}
private static Path copyResourcesToTmpDir() throws IOException {
Path root = Files.createTempDirectory("onlineExperimentExample");
PathUtils.copyFileToDirectory(
Objects.requireNonNull(getResourceFile(CHART_IMAGE_FILE)).toPath(), root);
PathUtils.copyFileToDirectory(
Objects.requireNonNull(getResourceFile(MODEL_FILE)).toPath(), root);
Files.createTempFile(root, "empty_file", ".txt");
Path subDir = Files.createTempDirectory(root, "subDir");
PathUtils.copyFileToDirectory(
Objects.requireNonNull(getResourceFile(HTML_REPORT_FILE)).toPath(), subDir);
PathUtils.copyFileToDirectory(
Objects.requireNonNull(getResourceFile(GRAPH_JSON_FILE)).toPath(), subDir);
return root;
}
}