309 lines
7.6 KiB
Markdown
309 lines
7.6 KiB
Markdown
# IronTelemetry SDK for Go
|
|
|
|
Error monitoring and crash reporting SDK for Go applications. Capture exceptions, track user journeys, and get insights to fix issues faster.
|
|
|
|
[](https://pkg.go.dev/github.com/IronServices/irontelemetry-go)
|
|
[](https://goreportcard.com/report/github.com/IronServices/irontelemetry-go)
|
|
[](https://opensource.org/licenses/MIT)
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
go get github.com/IronServices/irontelemetry-go
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### Basic Exception Capture
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"errors"
|
|
"log"
|
|
|
|
irontelemetry "github.com/IronServices/irontelemetry-go"
|
|
)
|
|
|
|
func main() {
|
|
// Initialize with your DSN
|
|
client, err := irontelemetry.New(irontelemetry.Options{
|
|
DSN: "https://pk_live_xxx@irontelemetry.com",
|
|
})
|
|
if err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
defer client.Close()
|
|
|
|
// Capture exceptions
|
|
if err := doSomething(); err != nil {
|
|
client.CaptureException(err)
|
|
}
|
|
}
|
|
|
|
func doSomething() error {
|
|
return errors.New("something went wrong")
|
|
}
|
|
```
|
|
|
|
### Journey Tracking
|
|
|
|
Track user journeys to understand the context of errors:
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
irontelemetry "github.com/IronServices/irontelemetry-go"
|
|
)
|
|
|
|
func main() {
|
|
client, _ := irontelemetry.New(irontelemetry.Options{
|
|
DSN: "https://pk_live_xxx@irontelemetry.com",
|
|
})
|
|
defer client.Close()
|
|
|
|
// Start a journey
|
|
journey := client.StartJourney("Checkout Flow")
|
|
journey.SetUser("user-123", "user@example.com", "John Doe")
|
|
|
|
// Track steps
|
|
step := journey.StartStep("Validate Cart", irontelemetry.CategoryBusiness)
|
|
if err := validateCart(); err != nil {
|
|
step.Fail(err)
|
|
journey.Fail(err)
|
|
client.CaptureException(err)
|
|
return
|
|
}
|
|
step.Complete()
|
|
|
|
step = journey.StartStep("Process Payment", irontelemetry.CategoryBusiness)
|
|
if err := processPayment(); err != nil {
|
|
step.Fail(err)
|
|
journey.Fail(err)
|
|
client.CaptureException(err)
|
|
return
|
|
}
|
|
step.Complete()
|
|
|
|
journey.Complete()
|
|
}
|
|
```
|
|
|
|
Or use the helper method:
|
|
|
|
```go
|
|
journey := client.StartJourney("Checkout Flow")
|
|
|
|
err := journey.RunStep("Validate Cart", irontelemetry.CategoryBusiness, func() error {
|
|
return validateCart()
|
|
})
|
|
if err != nil {
|
|
journey.Fail(err)
|
|
client.CaptureException(err)
|
|
return
|
|
}
|
|
|
|
err = journey.RunStep("Process Payment", irontelemetry.CategoryBusiness, func() error {
|
|
return processPayment()
|
|
})
|
|
if err != nil {
|
|
journey.Fail(err)
|
|
client.CaptureException(err)
|
|
return
|
|
}
|
|
|
|
journey.Complete()
|
|
```
|
|
|
|
## Configuration
|
|
|
|
```go
|
|
client, err := irontelemetry.New(irontelemetry.Options{
|
|
DSN: "https://pk_live_xxx@irontelemetry.com",
|
|
Environment: "production",
|
|
AppVersion: "1.2.3",
|
|
SampleRate: 1.0, // 100% of events
|
|
Debug: false,
|
|
BeforeSend: func(event *irontelemetry.TelemetryEvent) *irontelemetry.TelemetryEvent {
|
|
// Filter or modify events
|
|
if strings.Contains(event.Message, "expected") {
|
|
return nil // Drop the event
|
|
}
|
|
return event
|
|
},
|
|
})
|
|
```
|
|
|
|
### 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` | float64 | 1.0 | Sample rate (0.0 to 1.0) |
|
|
| `MaxBreadcrumbs` | int | 100 | Max breadcrumbs to keep |
|
|
| `Debug` | bool | false | Enable debug logging |
|
|
| `BeforeSend` | func | nil | Hook to filter/modify events |
|
|
| `EnableOfflineQueue` | bool | 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
|
|
- **Context Support**: Full context.Context support for cancellation
|
|
- **Thread-Safe**: All operations are safe for concurrent use
|
|
|
|
## Breadcrumbs
|
|
|
|
```go
|
|
// Add simple breadcrumbs
|
|
client.AddBreadcrumb("User clicked checkout button", irontelemetry.CategoryUI)
|
|
client.AddBreadcrumb("Payment API called", irontelemetry.CategoryHTTP)
|
|
|
|
// With level
|
|
client.AddBreadcrumbWithLevel(
|
|
"User logged in",
|
|
irontelemetry.CategoryAuth,
|
|
irontelemetry.SeverityInfo,
|
|
)
|
|
|
|
// With data
|
|
client.AddBreadcrumbWithData(
|
|
"API request completed",
|
|
irontelemetry.CategoryHTTP,
|
|
irontelemetry.SeverityInfo,
|
|
map[string]any{
|
|
"url": "/api/checkout",
|
|
"statusCode": 200,
|
|
"duration": 150,
|
|
},
|
|
)
|
|
```
|
|
|
|
### Breadcrumb Categories
|
|
|
|
```go
|
|
irontelemetry.CategoryUI // User interface interactions
|
|
irontelemetry.CategoryHTTP // HTTP requests
|
|
irontelemetry.CategoryNavigation // Page/route navigation
|
|
irontelemetry.CategoryConsole // Console output
|
|
irontelemetry.CategoryAuth // Authentication events
|
|
irontelemetry.CategoryBusiness // Business logic events
|
|
irontelemetry.CategoryNotification // Notification events
|
|
irontelemetry.CategoryCustom // Custom events
|
|
```
|
|
|
|
## Severity Levels
|
|
|
|
```go
|
|
irontelemetry.SeverityDebug
|
|
irontelemetry.SeverityInfo
|
|
irontelemetry.SeverityWarning
|
|
irontelemetry.SeverityError
|
|
irontelemetry.SeverityFatal
|
|
```
|
|
|
|
## User Context
|
|
|
|
```go
|
|
// Simple user ID
|
|
client.SetUserByID("user-123")
|
|
|
|
// With email
|
|
client.SetUserWithEmail("user-123", "user@example.com")
|
|
|
|
// Full user object
|
|
client.SetUser(&irontelemetry.User{
|
|
ID: "user-123",
|
|
Email: "user@example.com",
|
|
Name: "John Doe",
|
|
Data: map[string]any{
|
|
"plan": "premium",
|
|
},
|
|
})
|
|
```
|
|
|
|
## Tags and Extra Data
|
|
|
|
```go
|
|
// Set individual tags
|
|
client.SetTag("release", "v1.2.3")
|
|
client.SetTag("server", "prod-1")
|
|
|
|
// Set multiple tags
|
|
client.SetTags(map[string]string{
|
|
"release": "v1.2.3",
|
|
"server": "prod-1",
|
|
})
|
|
|
|
// Set extra data
|
|
client.SetExtra("request_id", "abc-123")
|
|
client.SetExtras(map[string]any{
|
|
"request_id": "abc-123",
|
|
"user_agent": "Mozilla/5.0...",
|
|
})
|
|
```
|
|
|
|
## Context Support
|
|
|
|
All capture methods support context for cancellation:
|
|
|
|
```go
|
|
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
|
|
defer cancel()
|
|
|
|
result := client.CaptureExceptionWithContext(ctx, err)
|
|
if !result.Success {
|
|
log.Printf("Failed to send event: %s", result.Error)
|
|
}
|
|
```
|
|
|
|
## HTTP Middleware Example
|
|
|
|
```go
|
|
func TelemetryMiddleware(client *irontelemetry.Client) func(http.Handler) http.Handler {
|
|
return func(next http.Handler) http.Handler {
|
|
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
|
client.AddBreadcrumbWithData(
|
|
"HTTP Request",
|
|
irontelemetry.CategoryHTTP,
|
|
irontelemetry.SeverityInfo,
|
|
map[string]any{
|
|
"method": r.Method,
|
|
"url": r.URL.String(),
|
|
},
|
|
)
|
|
|
|
defer func() {
|
|
if err := recover(); err != nil {
|
|
client.CaptureException(fmt.Errorf("panic: %v", err))
|
|
panic(err) // Re-panic
|
|
}
|
|
}()
|
|
|
|
next.ServeHTTP(w, r)
|
|
})
|
|
}
|
|
}
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- Go 1.21+
|
|
|
|
## Links
|
|
|
|
- [Documentation](https://www.irontelemetry.com/docs)
|
|
- [Dashboard](https://www.irontelemetry.com)
|
|
|
|
## License
|
|
|
|
MIT License - see [LICENSE](LICENSE) for details.
|