Install on Java · Sankofa Docs

The Sankofa Java SDK targets server-side JVM workloads. The artifact is dev.sankofa:sankofa-catch on Maven Central and ships error capture, transactions, vitals, and a drop-in Servlet filter.

Requirements

JDK 11+ (we test 11, 17, 21)
Gradle 8+ or Maven 3.9+

1. Add the dependency

Kotlinbuild.gradle.kts

dependencies {
  implementation("dev.sankofa:sankofa-catch:0.1.0")
}

groovybuild.gradle

dependencies {
  implementation 'dev.sankofa:sankofa-catch:0.1.0'
}

xmlpom.xml

<dependency>
  <groupId>dev.sankofa</groupId>
  <artifactId>sankofa-catch</artifactId>
  <version>0.1.0</version>
</dependency>

Make sure Maven Central is in your repositories (default for new projects).

2. Initialize the SDK

JavaApp.java

import dev.sankofa.sankofacatch.SankofaCatch;
import dev.sankofa.sankofacatch.Options;

public class App {
  public static void main(String[] args) {
      SankofaCatch.init(Options.builder()
          .apiKey(System.getenv("SANKOFA_KEY"))
          .endpoint("https://api.sankofa.dev")
          .environment(System.getenv().getOrDefault("ENV", "production"))
          .release(System.getenv("RELEASE_SHA"))
          .build());

      Runtime.getRuntime().addShutdownHook(new Thread(() ->
          SankofaCatch.flush(2000)
      ));

      // ... start the server
  }
}

For a Servlet container, register dev.sankofa.sankofacatch.servlet.SankofaCatchFilter in web.xml or via a ServletContextListener:

JavaWebInit.java

import dev.sankofa.sankofacatch.servlet.SankofaCatchFilter;
import jakarta.servlet.ServletContextEvent;
import jakarta.servlet.ServletContextListener;

public class WebInit implements ServletContextListener {
  @Override
  public void contextInitialized(ServletContextEvent sce) {
      SankofaCatch.init(/* ... */);
      sce.getServletContext()
          .addFilter("sankofa", SankofaCatchFilter.class)
          .addMappingForUrlPatterns(null, true, "/*");
  }
}

Common config options

apiKeyStringRequired

Your project's server-side API key.

endpointStringRequired

Server base URL.

releaseString

Commit SHA or version tag — used by Catch for source-map matching.

environmentStringdefault production

Free-form label (development, staging, production).

appVersionString

Your app's user-facing version string.

tracesSampleRatedoubledefault 0.1

Distributed-tracing sample rate (0.0–1.0).

3. Verify the install

Java

SankofaCatch.captureMessage("install_check");

Build and run, then open app.sankofa.dev → Live events. The message should appear within seconds with a java source label and the JVM version captured under default properties.

What's next

Send your first event

Multi-platform first-event walkthrough.

Reference

Java SDK reference

Capture, breadcrumbs, transactions, and the Servlet filter.

Catch

Catch product

Server-side error tracking, breadcrumbs, source-map upload.