https://github.com/aternosorg/mclogs-java
Java library for mclogs
https://github.com/aternosorg/mclogs-java
Last synced: 4 months ago
JSON representation
Java library for mclogs
- Host: GitHub
- URL: https://github.com/aternosorg/mclogs-java
- Owner: aternosorg
- License: mit
- Created: 2021-01-30T16:48:00.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2026-01-28T12:22:15.000Z (4 months ago)
- Last Synced: 2026-01-29T04:45:11.216Z (4 months ago)
- Language: Java
- Size: 205 KB
- Stars: 11
- Watchers: 4
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# mclogs-java
A java library used to list and share log files to the [mclo.gs](https://mclo.gs) API.
This library is used in the [mclogs plugin and mods](https://github.com/aternosorg/mclogs-integration).
### 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
```gradle
dependencies {
implementation 'gs.mclo:api:6.0.0'
}
```
#### Maven
```xml
gs.mclo
api
6.0.0
```
### Upload a log file
Obtaining a log file:
```java
// by path
var log = new Log(Paths.get("./logs/latest.log"));
// or by raw content
log = new Log("example content");
```
Creating a client:
```java
// 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:
```java
// share the log file
CompletableFuture future = client.uploadLog(log);
UploadLogResponse response = future.get();
System.out.println(response.getUrl());
```
There are also shortcuts for posting raw content or a path:
```java
// share a log file by path
CompletableFuture 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:
```java
log.setSource("mclogs-client-example")
.addMetadata(new Metadata<>("example-key", "example-value", "Example Label", true))
.addMetadata(new Metadata<>("other-example", 5548));
```
### Get log information
```java
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:
```java
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
```java
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:
```java
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:
```java
var insights = client.getInsights("HpAwPry").get();
```
### Analysing a log file without uploading it
```java
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
```java
client.setInstance(new Instance("https://api.logs.example.com"));
```
### Checking the storage limits of the current instance
```java
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.