🚀 Try Statly for free →
SDKs
Go
API Reference

API Reference

Full reference for all exported functions in the statly package.

Initialization

Init(options)

Initialize the SDK. Call once at application startup.

func Init(options Options) error

Parameters:

Returns: Error if already initialized or DSN is invalid.

Example:

import statly "github.com/KodyDennon/statly-go"
 
err := statly.Init(statly.Options{
    DSN:         "https://[email protected]/your-org",
    Environment: "production",
})
if err != nil {
    log.Fatal(err)
}

Capturing Events

CaptureException(err)

Capture an error.

func CaptureException(err error) string

Returns: Event ID (UUID string)

Example:

_, err := riskyOperation()
if err != nil {
    eventID := statly.CaptureException(err)
    log.Printf("Captured event: %s", eventID)
}

CaptureExceptionWithContext(err, ctx)

Capture an error with additional context.

func CaptureExceptionWithContext(err error, ctx map[string]interface{}) string

Example:

_, err := processOrder(orderID)
if err != nil {
    statly.CaptureExceptionWithContext(err, map[string]interface{}{
        "order_id": orderID,
        "user_id":  userID,
    })
}

CaptureMessage(message, level)

Capture a message event.

func CaptureMessage(message string, level Level) string

Levels:

  • statly.LevelDebug
  • statly.LevelInfo
  • statly.LevelWarning
  • statly.LevelError
  • statly.LevelFatal

Example:

statly.CaptureMessage("Server started", statly.LevelInfo)
statly.CaptureMessage("High memory usage", statly.LevelWarning)

CaptureMessageWithContext(message, level, ctx)

Capture a message with additional context.

func CaptureMessageWithContext(message string, level Level, ctx map[string]interface{}) string

Panic Recovery

Recover()

Recover from panics in the current goroutine. Use with defer.

func Recover()

Behavior:

  1. Recovers the panic
  2. Captures it as an event with stack trace
  3. Flushes pending events
  4. Re-panics

Example:

func main() {
    statly.Init(statly.Options{DSN: "..."})
    defer statly.Close()
    defer statly.Recover()
 
    panic("something went wrong")
}

RecoverWithContext(ctx)

Recover with additional context.

func RecoverWithContext(ctx map[string]interface{})

Example:

func handleRequest(userID string) {
    defer statly.RecoverWithContext(map[string]interface{}{
        "user_id": userID,
        "handler": "handleRequest",
    })
 
    // Code that might panic
}

Context Management

SetUser(user)

Set user context for all future events.

func SetUser(user User)
 
type User struct {
    ID       string
    Email    string
    Username string
    IPAddr   string
    Data     map[string]interface{} // Custom fields
}

Example:

statly.SetUser(statly.User{
    ID:       "user_123",
    Email:    "[email protected]",
    Username: "johndoe",
    Data: map[string]interface{}{
        "plan": "enterprise",
    },
})

SetTag(key, value)

Set a single tag.

func SetTag(key, value string)

SetTags(tags)

Set multiple tags at once.

func SetTags(tags map[string]string)

SetExtra(key, value)

Set extra context data.

func SetExtra(key string, value interface{})

Breadcrumbs

AddBreadcrumb(crumb)

Add a breadcrumb to the trail.

func AddBreadcrumb(crumb Breadcrumb)
 
type Breadcrumb struct {
    Message   string
    Category  string
    Level     Level
    Type      string
    Data      map[string]interface{}
    Timestamp time.Time // Auto-set if zero
}

Example:

statly.AddBreadcrumb(statly.Breadcrumb{
    Message:  "User logged in",
    Category: "auth",
    Level:    statly.LevelInfo,
})
 
statly.AddBreadcrumb(statly.Breadcrumb{
    Message:  "GET /api/orders",
    Category: "http",
    Level:    statly.LevelInfo,
    Data: map[string]interface{}{
        "status": 200,
        "duration_ms": 45,
    },
})

Scope Management

CurrentScope()

Get a clone of the current scope.

func CurrentScope() *Scope

WithScope(fn)

Execute function with a temporary scope.

func WithScope(fn func(*Scope))
⚠️

Note: In the current implementation, modifications to the scope inside WithScope are not persisted after the function returns.

Example:

statly.WithScope(func(scope *statly.Scope) {
    scope.SetTag("request_id", requestID)
    scope.SetUser(statly.User{ID: userID})
    // These are local to this scope
})

Lifecycle

Flush()

Wait for all pending events to be sent.

func Flush()

Example:

statly.CaptureMessage("Shutting down", statly.LevelInfo)
statly.Flush() // Block until event is sent

Close()

Flush and shut down the SDK.

func Close()

Example:

func main() {
    statly.Init(statly.Options{DSN: "..."})
    defer statly.Close()
 
    // Application code
}

GetClient()

Get the SDK client instance.

func GetClient() *Client

Types

Options

type Options struct {
    DSN            string
    Environment    string
    Release        string
    Debug          bool
    SampleRate     float64
    MaxBreadcrumbs int
    BeforeSend     func(*Event) *Event
    Transport      Transport
    ServerName     string
    FlushTimeout   time.Duration
}

Event

type Event struct {
    EventID     string
    Timestamp   time.Time
    Level       Level
    Platform    string // "go"
    Message     string
    Exception   []ExceptionValue
    Contexts    map[string]interface{}
    Tags        map[string]string
    Extra       map[string]interface{}
    User        *EventUser
    Breadcrumbs []BreadcrumbValue
    SDK         SDKInfo
    Environment string
    Release     string
    ServerName  string
    Request     *RequestInfo
}

Level

type Level string
 
const (
    LevelDebug   Level = "debug"
    LevelInfo    Level = "info"
    LevelWarning Level = "warning"
    LevelError   Level = "error"
    LevelFatal   Level = "fatal"
)
ConfigurationGin