Update README with branded header and documentation links
- 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 <noreply@anthropic.com>
This commit is contained in:
David Friedel
parent
78d2364149
commit
386720bfe2
304
README.md
304
README.md
|
|
@ -1,9 +1,39 @@
|
||||||
# IronTelemetry SDK for Java
|
<p align="center">
|
||||||
|
<a href="https://irontelemetry.com">
|
||||||
|
<img src="https://irontelemetry.com/logo.png" alt="IronTelemetry" width="120" />
|
||||||
|
</a>
|
||||||
|
</p>
|
||||||
|
|
||||||
Error monitoring and crash reporting SDK for Java applications. Capture exceptions, track user journeys, and get insights to fix issues faster.
|
<h1 align="center">IronTelemetry SDK for Java</h1>
|
||||||
|
|
||||||
[](https://search.maven.org/artifact/com.ironservices/telemetry)
|
<p align="center">
|
||||||
[](https://opensource.org/licenses/MIT)
|
<strong>Error monitoring and crash reporting for Java applications</strong>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<a href="https://search.maven.org/artifact/com.ironservices/telemetry"><img src="https://img.shields.io/maven-central/v/com.ironservices/telemetry.svg" alt="Maven Central"></a>
|
||||||
|
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<a href="https://irontelemetry.com">Website</a> •
|
||||||
|
<a href="https://irontelemetry.com/docs">Documentation</a> •
|
||||||
|
<a href="https://irontelemetry.com/docs/java">Java Guide</a> •
|
||||||
|
<a href="https://git.marketally.com/ironservices">Git</a>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**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
|
## Installation
|
||||||
|
|
||||||
|
|
@ -25,63 +55,66 @@ implementation 'com.ironservices:telemetry:0.1.0'
|
||||||
|
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
### Basic Exception Capture
|
### Initialize the SDK
|
||||||
|
|
||||||
```java
|
```java
|
||||||
import com.ironservices.telemetry.TelemetryClient;
|
import com.ironservices.telemetry.TelemetryClient;
|
||||||
|
|
||||||
public class Main {
|
TelemetryClient client = new TelemetryClient("https://pk_live_xxx@irontelemetry.com");
|
||||||
public static void main(String[] args) {
|
```
|
||||||
// Initialize with your DSN
|
|
||||||
try (TelemetryClient client = new TelemetryClient("https://pk_live_xxx@irontelemetry.com")) {
|
### Capture Exceptions
|
||||||
try {
|
|
||||||
doSomething();
|
```java
|
||||||
} catch (Exception e) {
|
try {
|
||||||
client.captureException(e);
|
doSomething();
|
||||||
throw e;
|
} catch (Exception e) {
|
||||||
}
|
client.captureException(e);
|
||||||
}
|
throw e;
|
||||||
}
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Journey Tracking
|
### Track User Journeys
|
||||||
|
|
||||||
Track user journeys to understand the context of errors:
|
|
||||||
|
|
||||||
```java
|
```java
|
||||||
import com.ironservices.telemetry.*;
|
Journey journey = client.startJourney("Checkout Flow");
|
||||||
|
journey.setUser("user-123", "user@example.com", "John Doe");
|
||||||
|
|
||||||
public class CheckoutService {
|
try {
|
||||||
private final TelemetryClient client;
|
journey.runStep("Validate Cart", BreadcrumbCategory.BUSINESS, () -> {
|
||||||
|
validateCart();
|
||||||
|
});
|
||||||
|
|
||||||
public CheckoutService(TelemetryClient client) {
|
journey.runStep("Process Payment", BreadcrumbCategory.BUSINESS, () -> {
|
||||||
this.client = client;
|
processPayment();
|
||||||
}
|
});
|
||||||
|
|
||||||
public void processCheckout() {
|
journey.complete();
|
||||||
Journey journey = client.startJourney("Checkout Flow");
|
} catch (Exception e) {
|
||||||
journey.setUser("user-123", "user@example.com", "John Doe");
|
journey.fail(e);
|
||||||
|
client.captureException(e);
|
||||||
|
throw e;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
try {
|
### Add Breadcrumbs
|
||||||
journey.runStep("Validate Cart", BreadcrumbCategory.BUSINESS, () -> {
|
|
||||||
validateCart();
|
|
||||||
});
|
|
||||||
|
|
||||||
journey.runStep("Process Payment", BreadcrumbCategory.BUSINESS, () -> {
|
```java
|
||||||
processPayment();
|
client.addBreadcrumb("User clicked checkout button", BreadcrumbCategory.UI);
|
||||||
});
|
client.addBreadcrumb("Payment API called", BreadcrumbCategory.HTTP);
|
||||||
|
```
|
||||||
|
|
||||||
journey.runStep("Send Confirmation", BreadcrumbCategory.NOTIFICATION, () -> {
|
## Spring Integration
|
||||||
sendConfirmationEmail();
|
|
||||||
});
|
|
||||||
|
|
||||||
journey.complete();
|
```java
|
||||||
} catch (Exception e) {
|
@ControllerAdvice
|
||||||
journey.fail(e);
|
public class GlobalExceptionHandler {
|
||||||
client.captureException(e);
|
private final TelemetryClient telemetryClient;
|
||||||
throw e;
|
|
||||||
}
|
@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
|
## Configuration
|
||||||
|
|
||||||
```java
|
```java
|
||||||
import com.ironservices.telemetry.TelemetryClient;
|
|
||||||
import com.ironservices.telemetry.TelemetryOptions;
|
|
||||||
|
|
||||||
TelemetryOptions options = new TelemetryOptions("https://pk_live_xxx@irontelemetry.com")
|
TelemetryOptions options = new TelemetryOptions("https://pk_live_xxx@irontelemetry.com")
|
||||||
.setEnvironment("production")
|
.setEnvironment("production")
|
||||||
.setAppVersion("1.2.3")
|
.setAppVersion("1.2.3")
|
||||||
.setSampleRate(1.0) // 100% of events
|
.setSampleRate(1.0)
|
||||||
.setDebug(false)
|
.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);
|
TelemetryClient client = new TelemetryClient(options);
|
||||||
```
|
```
|
||||||
|
|
||||||
### Configuration Options
|
## Documentation
|
||||||
|
|
||||||
| Option | Type | Default | Description |
|
For complete documentation, visit [irontelemetry.com/docs](https://irontelemetry.com/docs).
|
||||||
|--------|------|---------|-------------|
|
|
||||||
| `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
|
## Other SDKs
|
||||||
|
|
||||||
- **Automatic Stack Traces**: Full stack traces captured with every exception
|
| Platform | Package |
|
||||||
- **Journey Tracking**: Track user flows and correlate errors with context
|
|----------|---------|
|
||||||
- **Breadcrumbs**: Leave a trail of events leading up to an error
|
| JavaScript/TypeScript | [@ironservices/telemetry](https://git.marketally.com/ironservices/irontelemetry-js) |
|
||||||
- **User Context**: Associate errors with specific users
|
| .NET | [IronTelemetry.Client](https://git.marketally.com/ironservices/irontelemetry-dotnet) |
|
||||||
- **Tags & Extras**: Add custom metadata to your events
|
| Python | [irontelemetry](https://git.marketally.com/ironservices/irontelemetry-python) |
|
||||||
- **Async Support**: CompletableFuture support for async operations
|
| Go | [irontelemetry-go](https://git.marketally.com/ironservices/irontelemetry-go) |
|
||||||
- **Thread-Safe**: All operations are safe for concurrent use
|
| Rust | [irontelemetry](https://git.marketally.com/ironservices/irontelemetry-rust) |
|
||||||
|
|
||||||
## Breadcrumbs
|
## Support
|
||||||
|
|
||||||
```java
|
- **Documentation**: [irontelemetry.com/docs](https://irontelemetry.com/docs)
|
||||||
// Add simple breadcrumbs
|
- **Email**: dev@ironservices.io
|
||||||
client.addBreadcrumb("User clicked checkout button", BreadcrumbCategory.UI);
|
- **Issues**: [git.marketally.com/ironservices/irontelemetry-java/issues](https://git.marketally.com/ironservices/irontelemetry-java/issues)
|
||||||
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
|
## License
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue