This repository contains the files for the Sternum Java SDK, a versatile and flexible tool for adding observability and traceability to Java applications.

Compatibility

Operating System:

Linux
Windows

Java version:

8.0 and higher

Setup

Integrate Sternum Java SDK into your project

To integrate the Sternum Java SDK, you need to include the Sternum-Java-SDK-*.jar file in your project. Move the Sternum-Java-SDK-*.jar to the libs directory in your application's structure and configure your build system to link with the SDK library.

Gradle

If you are using Gradle, add the Sternum SDK as a dependency in build.gradle:

dependencies {
    implementation files('libs/Sternum-Java-SDK-1.3.5.jar')
}

Maven

If you are using Maven, you need to install the Sternum SDK JAR file into your local Maven repository. This allows you to manage it as a standard Maven dependency.

Install the Sternum SDK JAR into Your Local Maven Repository

Use the following Maven command from your target application project directory to perform the installation:

mvn install:install-file \
  -Dfile=/path/to/Sternum-Java-SDK-<VERSION>.jar \
  -DgroupId=com.sternum.cloud \
  -DartifactId=sternum-java-sdk \
  -Dversion=<VERSION> \
  -Dpackaging=jar

Replace -Dfile=/path/to/Sternum-Java-SDK-<VERSION>.jar with actual path to SDK JAR file and -Dversion=<VERSION> with version number.

Update Your pom.xml File

Once the JAR is installed in your local Maven repository, add it as a regular dependency in your pom.xml file. Update your pom.xml with the following dependency configuration:

<dependency>
    <groupId>com.sternum.cloud</groupId>
    <artifactId>sternum-java-sdk</artifactId>
    <version>1.3.5</version> <!-- Replace with your VERSION -->
</dependency>

Run or Package Your Application

After including the SDK as a dependency, you have two options to ensure that the SDK is available at runtime:

Run with Classpath: When running your application, specify the classpath to include the Sternum SDK JAR, for example:
java -cp target/hello-world-1.0-SNAPSHOT.jar:/path/to/Sternum-Java-SDK-1.3.5.jar HelloWorld
Use the Maven Shade Plugin: To bundle the SDK and all other dependencies into a single executable JAR, use the Maven Shade Plugin. This avoids the need to manually specify the classpath at runtime.

Using the API

Add generated Trace Definitions files to target project

Refer to Sternum SDK Getting Started to learn how to create the Trace Definitions file. Store the Trace Definitions files (ArgumentRoleType.java, TraceEventType.java) in chosen location of your application structure. It can be for example com/sternum/cloud/user location.

Import necessary classes

import com.sternum.cloud.SternumSDK;
import com.sternum.cloud.SternumSettings;
import com.sternum.cloud.user.TraceEventType;
import com.sternum.cloud.user.ArgumentRoleType;
import com.sternum.cloud.protocol.tracing.Argument;
import java.math.BigInteger;

Initialize Sternum SDK

You must initialize Sternum SDK before using it.

Transmission initialization:

com.sternum.cloud.SternumSettings::sternumURL - The designated endpoint provided by Sternum, serving as the destination for transmitting traces.
com.sternum.cloud.SternumSettings::accessToken - Identifier for the product to which traces will be transmitted.

For more information about the initialization structure, refer to the documentation of com.sternum.cloud.SternumSettings .

Below is an example of how to initialize the SDK:

SternumSettings settings = new SternumSettings();
settings.sternumURL = "gateway.sternum.cloud";
settings.firmwareVersion = "FW_1.0.0";
settings.accessToken = new BigInteger("12345678");
settings.deviceID = new BigInteger("1234");
settings.isProduction = false;
 
SternumSDK sternumSDK = SternumSDK.getInstance();
sternumSDK.initialize(settings);

Thread safety

The SDK library is thread-safe.

Sending traces

sternumSDK.trace(TraceEventType.TRACE_BOOT, new Argument(ArgumentRoleType.ARG_ROLE_NAME, "Example Application"));

Flushing traces

sternumSDK.flush();

Closing the Sternum SDK

sternumSDK.close();

Contents