From 386720bfe207e452d81f8e16fa51c51820ddd45d Mon Sep 17 00:00:00 2001 From: David Friedel Date: Sat, 27 Dec 2025 10:40:21 +0000 Subject: [PATCH] Update README with branded header and documentation links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add centered logo and title with product branding - Add links to product website and documentation - Add badges for package manager and license - Add Other SDKs table with cross-references - Add Support section with dev@ironservices.io email - Update repository links to git.marketally.com 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- README.md | 304 +++++++++++++++++------------------------------------- 1 file changed, 94 insertions(+), 210 deletions(-) diff --git a/README.md b/README.md index 9140a73..4cf5bcc 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,39 @@ -# IronTelemetry SDK for Java +

+ + IronTelemetry + +

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

IronTelemetry SDK for Java

-[![Maven Central](https://img.shields.io/maven-central/v/com.ironservices/telemetry.svg)](https://search.maven.org/artifact/com.ironservices/telemetry) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +

+ Error monitoring and crash reporting for Java applications +

+ +

+ Maven Central + License: MIT +

+ +

+ Website • + Documentation • + Java Guide • + Git +

+ +--- + +**IronTelemetry** helps you capture exceptions, track user journeys, and get actionable insights to fix issues faster. Built for developers who want simple, powerful error monitoring without the complexity. + +## Features + +- **Exception Capture** - Automatically capture exceptions with full stack traces +- **Journey Tracking** - Understand what users did before an error occurred +- **Breadcrumbs** - Add context with custom breadcrumbs and metadata +- **Async Support** - CompletableFuture support for async operations +- **Thread-Safe** - All operations are safe for concurrent use +- **Spring Integration** - Easy integration with Spring Boot ## Installation @@ -25,63 +55,66 @@ implementation 'com.ironservices:telemetry:0.1.0' ## Quick Start -### Basic Exception Capture +### Initialize the SDK ```java 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; - } - } - } +TelemetryClient client = new TelemetryClient("https://pk_live_xxx@irontelemetry.com"); +``` + +### Capture Exceptions + +```java +try { + doSomething(); +} catch (Exception e) { + client.captureException(e); + throw e; } ``` -### Journey Tracking - -Track user journeys to understand the context of errors: +### Track User Journeys ```java -import com.ironservices.telemetry.*; +Journey journey = client.startJourney("Checkout Flow"); +journey.setUser("user-123", "user@example.com", "John Doe"); -public class CheckoutService { - private final TelemetryClient client; +try { + journey.runStep("Validate Cart", BreadcrumbCategory.BUSINESS, () -> { + validateCart(); + }); - public CheckoutService(TelemetryClient client) { - this.client = client; - } + journey.runStep("Process Payment", BreadcrumbCategory.BUSINESS, () -> { + processPayment(); + }); - public void processCheckout() { - Journey journey = client.startJourney("Checkout Flow"); - journey.setUser("user-123", "user@example.com", "John Doe"); + journey.complete(); +} catch (Exception e) { + journey.fail(e); + client.captureException(e); + throw e; +} +``` - try { - journey.runStep("Validate Cart", BreadcrumbCategory.BUSINESS, () -> { - validateCart(); - }); +### Add Breadcrumbs - journey.runStep("Process Payment", BreadcrumbCategory.BUSINESS, () -> { - processPayment(); - }); +```java +client.addBreadcrumb("User clicked checkout button", BreadcrumbCategory.UI); +client.addBreadcrumb("Payment API called", BreadcrumbCategory.HTTP); +``` - journey.runStep("Send Confirmation", BreadcrumbCategory.NOTIFICATION, () -> { - sendConfirmationEmail(); - }); +## Spring Integration - journey.complete(); - } catch (Exception e) { - journey.fail(e); - client.captureException(e); - throw e; - } +```java +@ControllerAdvice +public class GlobalExceptionHandler { + private final TelemetryClient telemetryClient; + + @ExceptionHandler(Exception.class) + public ResponseEntity handleException(Exception e) { + telemetryClient.captureException(e); + return ResponseEntity.status(500).body("Internal Server Error"); } } ``` @@ -89,183 +122,34 @@ public class CheckoutService { ## Configuration ```java -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; - }); + .setSampleRate(1.0) + .setDebug(false); TelemetryClient client = new TelemetryClient(options); ``` -### Configuration Options +## Documentation -| 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 | +For complete documentation, visit [irontelemetry.com/docs](https://irontelemetry.com/docs). -## Features +## Other SDKs -- **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 +| Platform | Package | +|----------|---------| +| JavaScript/TypeScript | [@ironservices/telemetry](https://git.marketally.com/ironservices/irontelemetry-js) | +| .NET | [IronTelemetry.Client](https://git.marketally.com/ironservices/irontelemetry-dotnet) | +| Python | [irontelemetry](https://git.marketally.com/ironservices/irontelemetry-python) | +| Go | [irontelemetry-go](https://git.marketally.com/ironservices/irontelemetry-go) | +| Rust | [irontelemetry](https://git.marketally.com/ironservices/irontelemetry-rust) | -## Breadcrumbs +## Support -```java -// 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 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 - -```java -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 - -```java -SeverityLevel.DEBUG -SeverityLevel.INFO -SeverityLevel.WARNING -SeverityLevel.ERROR -SeverityLevel.FATAL -``` - -## User Context - -```java -// 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 - -```java -// Set individual tags -client.setTag("release", "v1.2.3"); -client.setTag("server", "prod-1"); - -// Set multiple tags -Map 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 extras = new HashMap<>(); -extras.put("request_id", "abc-123"); -extras.put("user_agent", "Mozilla/5.0..."); -client.setExtras(extras); -``` - -## Async Operations - -```java -// Async exception capture -CompletableFuture 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 - -```java -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 +- **Documentation**: [irontelemetry.com/docs](https://irontelemetry.com/docs) +- **Email**: dev@ironservices.io +- **Issues**: [git.marketally.com/ironservices/irontelemetry-java/issues](https://git.marketally.com/ironservices/irontelemetry-java/issues) ## License