mclogs-java

A java library used to list and share log files to the mclo.gs API. This library is used in the mclogs plugin and mods.

Features

• Full API coverage including:
  • Uploading log files
  • Analysing log files without uploading them
  • Fetching log contents and information
  • Attaching metadata to log uploads
  • Deleting logs
  • Getting log insights
  • Fetching storage limits
• Remove IPv4 and IPv6 addresses before uploading the log
• Automatically trim logs and shorten them to the instance's limits before uploading
• Compresses uploaded logs with GZIP to reduce upload size

Usage

This project is available from Maven Central, so you just need to add the dependency to your project:

Gradle

dependencies {
    implementation 'gs.mclo:api:6.0.0'
}

Maven

<dependency>
  <groupId>gs.mclo</groupId>
  <artifactId>api</artifactId>
  <version>6.0.0</version>
</dependency>

Upload a log file

Obtaining a log file:

// by path
var log = new Log(Paths.get("./logs/latest.log"));
// or by raw content
log = new Log("example content");

Creating a client:

// Create a client with a project name and version
var client = new MclogsClient("mclogs-java-example", "1.0.0");
// optionally with a minecraft version
client = new MclogsClient("mclogs-java-example", "1.0.0", "1.12.2");
// or with a custom user agent
client = new MclogsClient("mclogs-java-example/1.0.0");

Project names are used as the source field when uploading logs unless they're already set in the Log object passed to the API client.

Sharing the log file:

// share the log file
CompletableFuture<UploadLogResponse> future = client.uploadLog(log);
UploadLogResponse response = future.get();
System.out.println(response.getUrl());

There are also shortcuts for posting raw content or a path:

// share a log file by path
CompletableFuture<UploadLogResponse> future = client.uploadLog(Paths.get("./logs/latest.log"));
// share a log file by raw content
future = client.uploadLog("example content");

If you want to provide additional metadata, you can set it in the Log object:

log.setSource("mclogs-client-example")
    .addMetadata(new Metadata<>("example-key", "example-value", "Example Label", true))
    .addMetadata(new Metadata<>("other-example", 5548));

Get log information

var logInfo = client.getLog("HpAwPry").get();
System.out.println("Log source: " + logInfo.getSource());
System.out.println("Uploaded at: " + logInfo.getCreated());

This method also allows you to fetch the content of the log in three different variants:

• raw: The raw log content as a string
• parsed: The parsed log as a list of entries with additional information
• insights: The log insights generated by the mclogs analysis engine

You can request the variants you want by using the LogField enum:

var logInfo = client.getLog("HpAwPry", LogField.RAW, LogField.PARSED, LogField.INSIGHTS).get();
System.out.println(logInfo.getContent().getRaw());
System.out.println("Parsed entries: " + logInfo.getContent().getParsed().length);
System.out.println("Detected problems: " + logInfo.getContent().getInsights().getAnalysis().getProblems().length);

Deleting a log you uploaded

var uploadedLog = client.uploadLog(log).get();
uploadedLog.delete();

// or store the id and token somewhere and delete later
String logId = uploadedLog.getId();
String deleteToken = uploadedLog.getToken();

client.deleteLog(logId, deleteToken).get();

Fetch a log file's raw contents

If you only want the raw content without the other log information you can use the getRawLogContent method:

String rawLog = client.getRawLogContent("HpAwPry").get();

Fetch a log file's insights

If you only want the insights without the other log information you can use the getInsights method:

var insights = client.getInsights("HpAwPry").get();

Analysing a log file without uploading it

var log = new Log(Paths.get("./logs/latest.log"));
var analysisResult = client.analyseLog(log).get();
System.out.println("Detected problems: " + analysisResult.getAnalysis().getProblems().length);

Using a self-hosted instance of mclogs

client.setInstance(new Instance("https://api.logs.example.com"));

Checking the storage limits of the current instance

var limits = client.getLimits().get();
System.out.println("Max log size: " + limits.getMaxLength());
System.out.println("Storage duration: " + limits.getStorageDuration());

Calls to this method are cached.