IronTelemetry SDK for Java

Error monitoring and crash reporting SDK for Java applications. Capture exceptions, track user journeys, and get insights to fix issues faster.

Installation

Maven

<dependency>
    <groupId>com.ironservices</groupId>
    <artifactId>telemetry</artifactId>
    <version>0.1.0</version>
</dependency>

Gradle

implementation 'com.ironservices:telemetry:0.1.0'

Quick Start

Basic Exception Capture

import com.ironservices.telemetry.TelemetryClient;

public class Main {
    public static void main(String[] args) {
        // Initialize with your DSN
        try (TelemetryClient client = new TelemetryClient("https://pk_live_xxx@irontelemetry.com")) {
            try {
                doSomething();
            } catch (Exception e) {
                client.captureException(e);
                throw e;
            }
        }
    }
}

Journey Tracking

Track user journeys to understand the context of errors:

import com.ironservices.telemetry.*;

public class CheckoutService {
    private final TelemetryClient client;

    public CheckoutService(TelemetryClient client) {
        this.client = client;
    }

    public void processCheckout() {
        Journey journey = client.startJourney("Checkout Flow");
        journey.setUser("user-123", "user@example.com", "John Doe");

        try {
            journey.runStep("Validate Cart", BreadcrumbCategory.BUSINESS, () -> {
                validateCart();
            });

            journey.runStep("Process Payment", BreadcrumbCategory.BUSINESS, () -> {
                processPayment();
            });

            journey.runStep("Send Confirmation", BreadcrumbCategory.NOTIFICATION, () -> {
                sendConfirmationEmail();
            });

            journey.complete();
        } catch (Exception e) {
            journey.fail(e);
            client.captureException(e);
            throw e;
        }
    }
}

Configuration

import com.ironservices.telemetry.TelemetryClient;
import com.ironservices.telemetry.TelemetryOptions;

TelemetryOptions options = new TelemetryOptions("https://pk_live_xxx@irontelemetry.com")
    .setEnvironment("production")
    .setAppVersion("1.2.3")
    .setSampleRate(1.0)  // 100% of events
    .setDebug(false)
    .setBeforeSend(event -> {
        // Filter or modify events
        if (event.getMessage() != null && event.getMessage().contains("expected")) {
            return null;  // Drop the event
        }
        return event;
    });

TelemetryClient client = new TelemetryClient(options);

Configuration Options

Option	Type	Default	Description
dsn	String	required	Your Data Source Name
environment	String	"production"	Environment name
appVersion	String	"0.0.0"	Application version
sampleRate	double	1.0	Sample rate (0.0 to 1.0)
maxBreadcrumbs	int	100	Max breadcrumbs to keep
debug	boolean	false	Enable debug logging
beforeSend	Function	null	Hook to filter/modify events
enableOfflineQueue	boolean	true	Enable offline queue
maxOfflineQueueSize	int	500	Max offline queue size

Features

• Automatic Stack Traces: Full stack traces captured with every exception
• Journey Tracking: Track user flows and correlate errors with context
• Breadcrumbs: Leave a trail of events leading up to an error
• User Context: Associate errors with specific users
• Tags & Extras: Add custom metadata to your events
• Async Support: CompletableFuture support for async operations
• Thread-Safe: All operations are safe for concurrent use

Breadcrumbs

// Add simple breadcrumbs
client.addBreadcrumb("User clicked checkout button", BreadcrumbCategory.UI);
client.addBreadcrumb("Payment API called", BreadcrumbCategory.HTTP);

// With level
client.addBreadcrumb("User logged in", BreadcrumbCategory.AUTH, SeverityLevel.INFO);

// With data
Map<String, Object> data = new HashMap<>();
data.put("url", "/api/checkout");
data.put("statusCode", 200);
data.put("duration", 150);
client.addBreadcrumb("API request completed", BreadcrumbCategory.HTTP, SeverityLevel.INFO, data);

// Using builder
client.addBreadcrumb(Breadcrumb.builder("Payment processed", BreadcrumbCategory.BUSINESS)
    .level(SeverityLevel.INFO)
    .addData("amount", 99.99)
    .addData("currency", "USD")
    .build());

Breadcrumb Categories

BreadcrumbCategory.UI           // User interface interactions
BreadcrumbCategory.HTTP         // HTTP requests
BreadcrumbCategory.NAVIGATION   // Page/route navigation
BreadcrumbCategory.CONSOLE      // Console output
BreadcrumbCategory.AUTH         // Authentication events
BreadcrumbCategory.BUSINESS     // Business logic events
BreadcrumbCategory.NOTIFICATION // Notification events
BreadcrumbCategory.CUSTOM       // Custom events

Severity Levels

SeverityLevel.DEBUG
SeverityLevel.INFO
SeverityLevel.WARNING
SeverityLevel.ERROR
SeverityLevel.FATAL

User Context

// Simple user ID
client.setUser("user-123");

// With email
client.setUser("user-123", "user@example.com");

// Full user object
client.setUser(User.builder("user-123")
    .email("user@example.com")
    .name("John Doe")
    .addData("plan", "premium")
    .build());

Tags and Extra Data

// Set individual tags
client.setTag("release", "v1.2.3");
client.setTag("server", "prod-1");

// Set multiple tags
Map<String, String> tags = new HashMap<>();
tags.put("release", "v1.2.3");
tags.put("server", "prod-1");
client.setTags(tags);

// Set extra data
client.setExtra("request_id", "abc-123");

Map<String, Object> extras = new HashMap<>();
extras.put("request_id", "abc-123");
extras.put("user_agent", "Mozilla/5.0...");
client.setExtras(extras);

Async Operations

// Async exception capture
CompletableFuture<SendResult> future = client.captureExceptionAsync(exception);
future.thenAccept(result -> {
    if (result.isSuccess()) {
        System.out.println("Event sent: " + result.getEventId());
    }
});

// Async message capture
client.captureMessageAsync("Something happened", SeverityLevel.WARNING)
    .thenAccept(result -> System.out.println("Sent: " + result.isSuccess()));

Spring Integration Example

import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;

@ControllerAdvice
public class GlobalExceptionHandler {
    private final TelemetryClient telemetryClient;

    public GlobalExceptionHandler(TelemetryClient telemetryClient) {
        this.telemetryClient = telemetryClient;
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<?> handleException(Exception e, HttpServletRequest request) {
        telemetryClient.addBreadcrumb(
            "HTTP Request: " + request.getMethod() + " " + request.getRequestURI(),
            BreadcrumbCategory.HTTP
        );
        telemetryClient.captureException(e);
        return ResponseEntity.status(500).body("Internal Server Error");
    }
}

Requirements

• Java 11+
• OkHttp 4.x
• Gson 2.x

License

MIT License - see LICENSE for details.