Java / Kotlin SDK

JVM SDK for JustAnalytics distributed tracing and error tracking.

Installation#

The JustAnalytics Java SDK is distributed via GitHub Packages. This requires a GitHub personal access token with read:packages scope. We plan to migrate to Maven Central in the future.

Setup (one-time)#

Create a GitHub personal access token at github.com/settings/tokens with read:packages scope

Add to your ~/.gradle/gradle.properties:

gpr.user=YOUR_GITHUB_USERNAME
gpr.key=YOUR_GITHUB_TOKEN

Gradle (Kotlin DSL)#

// build.gradle.kts
repositories {
    mavenCentral()
    maven {
        url = uri("https://maven.pkg.github.com/specifiedcodes/justanalyticstech")
        credentials {
            username = project.findProperty("gpr.user") as String? ?: System.getenv("GITHUB_USERNAME")
            password = project.findProperty("gpr.key") as String? ?: System.getenv("GITHUB_TOKEN")
        }
    }
}

dependencies {
    implementation("app.justanalytics:justanalytics-core:0.1.1")
}

Gradle (Groovy)#

// build.gradle
repositories {
    mavenCentral()
    maven {
        url = uri("https://maven.pkg.github.com/specifiedcodes/justanalyticstech")
        credentials {
            username = project.findProperty("gpr.user") ?: System.getenv("GITHUB_USERNAME")
            password = project.findProperty("gpr.key") ?: System.getenv("GITHUB_TOKEN")
        }
    }
}

dependencies {
    implementation 'app.justanalytics:justanalytics-core:0.1.1'
}

Maven#

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/specifiedcodes/justanalyticstech</url>
    </repository>
</repositories>

<dependency>
    <groupId>app.justanalytics</groupId>
    <artifactId>justanalytics-core</artifactId>
    <version>0.1.1</version>
</dependency>

For Maven, add your GitHub credentials to ~/.m2/settings.xml:

<servers>
    <server>
        <id>github</id>
        <username>YOUR_GITHUB_USERNAME</username>
        <password>YOUR_GITHUB_TOKEN</password>
    </server>
</servers>

Why GitHub Packages?

The JustAnalytics Java and Android SDKs are currently distributed via GitHub Packages rather than Maven Central. This gives us faster release cycles and simpler CI/CD automation. We plan to publish to Maven Central in the future for convenience.

Quick Start (Kotlin)#

import com.justanalytics.JustAnalytics

fun main() {
    JustAnalytics.init(
        siteId = System.getenv("JUSTANALYTICS_SITE_ID"),
        apiKey = System.getenv("JUSTANALYTICS_API_KEY"),
        serviceName = "kotlin-api",
        environment = "production"
    )
}

Quick Start (Java)#

import com.justanalytics.JustAnalytics;

public class Application {
    public static void main(String[] args) {
        JustAnalytics.init(JustAnalytics.Options.builder()
            .siteId(System.getenv("JUSTANALYTICS_SITE_ID"))
            .apiKey(System.getenv("JUSTANALYTICS_API_KEY"))
            .serviceName("java-api")
            .environment("production")
            .build());
    }
}

Tracing (Kotlin)#

val result = JustAnalytics.startSpan("process-order") { span ->
    span.setAttribute("order.id", orderId)

    val user = JustAnalytics.startSpan("fetch-user") {
        userRepository.findById(userId)
    }

    ProcessResult(success = true, user = user)
}

Tracing (Java)#

var result = JustAnalytics.startSpan("process-order", span -> {
    span.setAttribute("order.id", orderId);

    var user = JustAnalytics.startSpan("fetch-user", s -> {
        return userRepository.findById(userId);
    });

    return new ProcessResult(true, user);
});

Error Tracking#

try {
    riskyOperation()
} catch (e: Exception) {
    JustAnalytics.captureException(e, mapOf("module" to "payments"))
}

Spring Boot Integration#

// application.yml
justanalytics:
  site-id: ${JUSTANALYTICS_SITE_ID}
  api-key: ${JUSTANALYTICS_API_KEY}
  service-name: spring-boot-app

// Auto-instruments:
// - Spring MVC / WebFlux requests
// - JDBC queries
// - Spring Data repositories
// - RestTemplate / WebClient HTTP calls
// - Scheduled tasks

Custom Metrics#

JustAnalytics.recordMetric("custom.queue_size", 42.0, mapOf("queue" to "emails"))

Requirements#

Java 17+ / Kotlin 1.8+
Spring Boot 3.0+ (for Spring integration)