irontelemetry-java/README.md

# 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.

[![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)

## Installation

### Maven

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

### Gradle

```groovy
implementation 'com.ironservices:telemetry:0.1.0'
```

## Quick Start

### Basic Exception Capture

```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;
            }
        }
    }
}
```

### Journey Tracking

Track user journeys to understand the context of errors:

```java
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

```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;
    });

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

```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<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

```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<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

```java
// 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

```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

## License

MIT License - see [LICENSE](LICENSE) for details.