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

[![Go Reference](https://pkg.go.dev/badge/github.com/IronServices/irontelemetry-go.svg)](https://pkg.go.dev/github.com/IronServices/irontelemetry-go)
[![Go Report Card](https://goreportcard.com/badge/github.com/IronServices/irontelemetry-go)](https://goreportcard.com/report/github.com/IronServices/irontelemetry-go)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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.