bugstack

README

bugstack-go

Official Go SDK for BugStack — capture, report, and auto-fix production errors.

Installation

go get github.com/MasonBachmann7/bugstack-go

Quick Start

package main

import (
    "errors"
    bugstack "github.com/MasonBachmann7/bugstack-go"
)

func main() {
    bugstack.Init(bugstack.Config{
        APIKey: "bs_live_...",
    })
    defer bugstack.Flush()

    err := riskyOperation()
    if err != nil {
        bugstack.CaptureError(err)
    }
}

Panic Recovery

func handler() {
    defer bugstack.Recover()
    // ... code that might panic
}

HTTP Middleware

net/http

import "github.com/MasonBachmann7/bugstack-go/middleware"

mux := http.NewServeMux()
mux.HandleFunc("/", handler)
http.ListenAndServe(":8080", middleware.NetHTTP(mux))

Gin

import "github.com/MasonBachmann7/bugstack-go/middleware"

r := gin.Default()
r.Use(gin.HandlerFunc(middleware.GinRecovery()))

Echo

import "github.com/MasonBachmann7/bugstack-go/middleware"

e := echo.New()
e.Use(echo.MiddlewareFunc(middleware.EchoRecover()))

Configuration

bugstack.Init(bugstack.Config{
    APIKey:              "bs_live_...",       // Required
    Environment:         "production",       // Default: "production"
    AutoFix:             true,               // Enable AI-powered auto-fix
    Debug:               false,              // Log SDK activity
    DryRun:              false,              // Log without sending
    Enabled:             true,               // Kill switch
    DeduplicationWindow: 300,                // Seconds (default: 5 min)
    Timeout:             5.0,                // HTTP timeout in seconds
    MaxRetries:          3,                  // Retry attempts
    IgnoredErrors:       []string{           // Error substrings to skip
        "context canceled",
    },
    BeforeSend: func(e *bugstack.Event) *bugstack.Event {
        // Return nil to drop, modify and return to keep
        return e
    },
})

Data Transparency

BeforeSend Hook

Inspect, modify, or drop any event before it leaves your application:

bugstack.Init(bugstack.Config{
    APIKey: "bs_live_...",
    BeforeSend: func(e *bugstack.Event) *bugstack.Event {
        if e.Request != nil && e.Request.Route == "/health" {
            return nil // Drop health check errors
        }
        delete(e.Metadata, "secret")
        return e
    },
})

DryRun Mode

See exactly what would be sent without network requests:

bugstack.Init(bugstack.Config{
    APIKey: "bs_live_...",
    DryRun: true,
})
// Prints: [BugStack DryRun] Would send: { ... }

What Gets Sent

{
  "apiKey": "bs_live_...",
  "error": {
    "message": "runtime error: index out of range",
    "stackTrace": "goroutine 1 [running]: ...",
    "file": "main.go",
    "function": "main.handler",
    "fingerprint": "a1b2c3d4e5f6g7h8"
  },
  "environment": {
    "language": "go",
    "languageVersion": "go1.22.0",
    "os": "linux",
    "sdkVersion": "1.0.0"
  },
  "timestamp": "2026-01-15T08:30:00Z"
}

Zero external dependencies. No cookies, IP addresses, or user data collected.

License

MIT — see LICENSE.

Documentation

Overview

Package bugstack provides the official Go SDK for BugStack — capture, report, and auto-fix production errors.

Usage:

import "github.com/MasonBachmann7/bugstack-go"

func main() {
    bugstack.Init(bugstack.Config{
        APIKey: "bs_live_...",
    })
    defer bugstack.Flush()

    // errors are captured automatically via middleware,
    // or manually:
    err := riskyOperation()
    if err != nil {
        bugstack.CaptureError(err)
    }
}

Index

• Constants
• func Bool(v bool) *bool
• func CaptureError(err error, opts ...CaptureOption) bool
• func CaptureMessage(msg string, opts ...CaptureOption) bool
• func Flush()
• func Init(cfg Config)
• func Recover(opts ...CaptureOption)
• type CaptureOption
  • func WithMetadata(meta map[string]any) CaptureOption
  • func WithRequest(req *RequestContext) CaptureOption
• type Client
  • func GetClient() *Client
  • func NewClient(cfg Config) *Client
  • func (c *Client) CaptureError(err error, opts ...CaptureOption) bool
  • func (c *Client) CaptureMessage(msg string, opts ...CaptureOption) bool
  • func (c *Client) RecoverPanic(r any, opts ...CaptureOption)
  • func (c *Client) Shutdown()
• type Config
• type EnvironmentInfo
• type Event
• type RequestContext

Constants

const Version = "1.1.0"

Version is the SDK version.

Functions

func Bool

func Bool(v bool) *bool

Bool returns a pointer to a bool value. Convenience helper for Config.Enabled.

func CaptureError

func CaptureError(err error, opts ...CaptureOption) bool

CaptureError captures an error and sends it to BugStack. Returns true if the error was accepted (not filtered/deduplicated).

func CaptureMessage

func CaptureMessage(msg string, opts ...CaptureOption) bool

CaptureMessage captures a message string as an event.

func Flush

func Flush()

Flush flushes pending events and shuts down the transport. Call this before application exit.

func Init

func Init(cfg Config)

Init initializes the global BugStack client. Call this once at application startup.

func Recover

func Recover(opts ...CaptureOption)

Recover captures a panic value. Call this in a deferred function.

defer bugstack.Recover()

Types

type CaptureOption

type CaptureOption func(*captureOptions)

CaptureOption is a functional option for CaptureError/CaptureMessage.

func WithMetadata

func WithMetadata(meta map[string]any) CaptureOption

WithMetadata attaches arbitrary key-value metadata to the event.

func WithRequest

func WithRequest(req *RequestContext) CaptureOption

WithRequest attaches HTTP request context to the error event.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the core BugStack client. It handles capturing errors, deduplication, filtering, and transport.

func GetClient

func GetClient() *Client

GetClient returns the global client instance, or nil if not initialized.

func NewClient

func NewClient(cfg Config) *Client

NewClient creates a new BugStack client with the given configuration.

func (*Client) CaptureError

func (c *Client) CaptureError(err error, opts ...CaptureOption) bool

CaptureError captures an error and sends it to BugStack. Returns true if the error was accepted.

func (*Client) CaptureMessage

func (c *Client) CaptureMessage(msg string, opts ...CaptureOption) bool

CaptureMessage captures a message string as an event.

func (*Client) RecoverPanic

func (c *Client) RecoverPanic(r any, opts ...CaptureOption)

RecoverPanic captures a panic value. Used internally by Recover().

func (*Client) Shutdown

func (c *Client) Shutdown()

Shutdown flushes pending events and stops the transport.

type Config

type Config struct {
	// APIKey is your BugStack API key (required).
	APIKey string

	// Endpoint is the BugStack API endpoint.
	// Default: "https://api.bugstack.dev/api/capture"
	Endpoint string

	// ProjectID is an optional project identifier.
	ProjectID string

	// Environment is the deployment environment name.
	// Default: "production"
	Environment string

	// AutoFix enables AI-powered autonomous error fixing.
	AutoFix bool

	// Enabled is a kill switch. Set to false to disable all capture.
	// Default: true (when nil or unset)
	Enabled *bool

	// Debug enables verbose SDK logging to stderr.
	Debug bool

	// DryRun logs events to stderr instead of sending them.
	DryRun bool

	// DeduplicationWindow is how long (in seconds) to suppress
	// duplicate errors. Default: 300 (5 minutes).
	DeduplicationWindow float64

	// Timeout is the HTTP timeout in seconds. Default: 5.
	Timeout float64

	// MaxRetries is the max number of retry attempts. Default: 3.
	MaxRetries int

	// IgnoredErrors is a list of error message substrings to ignore.
	IgnoredErrors []string

	// BeforeSend is a hook that can inspect, modify, or drop events.
	// Return nil to drop the event.
	BeforeSend func(*Event) *Event
}

Config holds the configuration for the BugStack SDK.

type EnvironmentInfo

type EnvironmentInfo struct {
	Language         string `json:"language"`
	LanguageVersion  string `json:"languageVersion"`
	Framework        string `json:"framework,omitempty"`
	FrameworkVersion string `json:"frameworkVersion,omitempty"`
	OS               string `json:"os"`
	SDKVersion       string `json:"sdkVersion"`
}

EnvironmentInfo holds runtime environment details.

type Event

type Event struct {
	Message       string          `json:"message"`
	StackTrace    string          `json:"stackTrace"`
	File          string          `json:"file"`
	Function      string          `json:"function"`
	Fingerprint   string          `json:"fingerprint"`
	ExceptionType string          `json:"exceptionType"`
	Request       *RequestContext `json:"request,omitempty"`
	Environment   EnvironmentInfo `json:"environment"`
	Timestamp     time.Time       `json:"timestamp"`
	Metadata      map[string]any  `json:"metadata,omitempty"`
}

Event represents an error event to be sent to BugStack.

type RequestContext

type RequestContext struct {
	Route       string            `json:"route"`
	Method      string            `json:"method"`
	QueryParams map[string]string `json:"queryParams,omitempty"`
}

RequestContext holds HTTP request information.