irontelemetry-go/README.md

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.

Installation

go get github.com/IronServices/irontelemetry-go

Quick Start

Basic Exception Capture

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:

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:

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

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

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

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

irontelemetry.SeverityDebug
irontelemetry.SeverityInfo
irontelemetry.SeverityWarning
irontelemetry.SeverityError
irontelemetry.SeverityFatal

User Context

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

// 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:

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

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
• Dashboard

License

MIT License - see LICENSE for details.