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
272
README.md
272
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)
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
<p align="center">
|
||||
<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
|
||||
|
||||
|
|
@ -25,41 +55,28 @@ 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")) {
|
||||
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.*;
|
||||
|
||||
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");
|
||||
|
||||
|
|
@ -72,16 +89,32 @@ public class CheckoutService {
|
|||
processPayment();
|
||||
});
|
||||
|
||||
journey.runStep("Send Confirmation", BreadcrumbCategory.NOTIFICATION, () -> {
|
||||
sendConfirmationEmail();
|
||||
});
|
||||
|
||||
journey.complete();
|
||||
} catch (Exception e) {
|
||||
journey.fail(e);
|
||||
client.captureException(e);
|
||||
throw e;
|
||||
}
|
||||
```
|
||||
|
||||
### Add Breadcrumbs
|
||||
|
||||
```java
|
||||
client.addBreadcrumb("User clicked checkout button", BreadcrumbCategory.UI);
|
||||
client.addBreadcrumb("Payment API called", BreadcrumbCategory.HTTP);
|
||||
```
|
||||
|
||||
## Spring Integration
|
||||
|
||||
```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<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
|
||||
- **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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue