scarf-java

A Java client for sending telemetry events to Scarf.

Installation

This library targets Java 11+ and has no runtime dependencies.

• Maven (example, version subject to change). Add to your pom.xml, making sure to use the latest version:

<dependency>
<groupId>sh.scarf</groupId>
<artifactId>scarf-sdk</artifactId>
<version>0.1.4</version>
</dependency>

• Gradle (example):

implementation "sh.scarf:scarf-sdk:0.1.4"

Usage

Import and initialize with the required endpoint URL:

importsh.scarf.ScarfEventLogger;
importjava.util.*;
ScarfEventLoggerlogger = newScarfEventLogger(
"https://your-scarf-endpoint.com",
5.0// Optional: default timeout seconds (default: 3.0)
);
// Send an event with properties (String keys; values are stringified)Map<String, Object> props = newLinkedHashMap<>();
props.put("event", "package_download");
props.put("package", "scarf");
props.put("version", "1.0.0");
booleansuccess = logger.logEvent(props);
// Send an event with a custom timeoutsuccess = logger.logEvent(Map.of("event", "custom_event"), 1.0);
// Empty properties are allowedsuccess = logger.logEvent(Collections.emptyMap());

Configuration

The client can be configured through environment variables:

• DO_NOT_TRACK=1: Disable analytics
• SCARF_NO_ANALYTICS=1: Disable analytics (alternative)
• SCARF_VERBOSE=1: Enable verbose logging

Features

• Simple API for sending telemetry events
• Environment variable configuration
• Configurable timeouts (default: 3 seconds)
• Respects user Do Not Track settings
• Verbose logging mode for debugging
• 100% dependency free at runtime

Notes

• Properties must be a Map<String, ?>. Values are converted to strings via toString() (null becomes JSON null).
• User-Agent version:
  • When running from classes (java -cp target/classes ...) the version shows as dev.
  • When packaged as a JAR, the version is taken from the JAR manifest (Implementation-Version = ${project.version}), e.g. 0.1.0 or 0.1.0-SNAPSHOT.

Development

Clone the repository and run tests with Maven:

mvn -q -DskipTests=false test

Using Nix (optional)

This repo provides a Nix shell for a zero-setup environment. It prefers Temurin 17 when available in your nixpkgs, and falls back to OpenJDK 17.

# Drop into a shell with JDK + Maven
nix-shell
# Run tests
mvn -q test

Runnable example

Sends two events to the public endpoint https://scarf.gateway.scarf.sh/scarf-java.

# Ensure analytics are not disabledunset DO_NOT_TRACK SCARF_NO_ANALYTICS
# Option A: compile then run classes
mvn -q -DskipTests package
java -cp target/classes sh.scarf.examples.LiveExampleBasic
# Option B: run directly from classes without packaging
mvn -q -DskipTests compile
java -cp target/classes sh.scarf.examples.LiveExampleBasic
# With Nix
nix-shell --run "mvn -q -DskipTests compile && java -cp target/classes sh.scarf.examples.LiveExampleBasic"

Publishing

Publishing uses Git tags and GitHub Actions to deploy to Maven Central via Sonatype Central (modern flow).

Release

• Create and push a version tag. The workflow derives the version from the tag (strip the leading v).

git tag v0.1.0
git push origin v0.1.0

The Release workflow will:

• Set the Maven project version to 0.1.0
• Build, sign, and publish to Maven Central via Sonatype Central tokens

License

Apache 2.0