Go SDK — AuditRails Context-Aware Audit Log Client

The AuditRails Go SDK is a zero-dependency client built entirely on the standard library (net/http). It is designed to be idiomatic Go: context-aware, safe for concurrent use from multiple goroutines, and properly closeable via defer client.Close(). Events are buffered and flushed in a background goroutine so your hot paths are never blocked by network I/O.

Installation

go get github.com/auditrails/auditrails-go

Requires Go 1.21 or later.

Initialization

Create a client with auditrails.New(). The first argument is your API key; the second is an optional *Options struct. Always pair client creation with defer client.Close() to ensure buffered events are flushed when your application exits.

package main

import (
    "os"

    auditrails "github.com/auditrails/auditrails-go"
)

func main() {
    client, err := auditrails.New(os.Getenv("AUDITRAILS_API_KEY"), nil)
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // Your application logic here
}

Pass nil as the second argument to use all defaults, or supply an *Options struct to customise behaviour:

client, err := auditrails.New(os.Getenv("AUDITRAILS_API_KEY"), &auditrails.Options{
    BatchSize:     50,
    FlushInterval: 500 * time.Millisecond,
    MaxRetries:    5,
    Logger:        slog.Default(),
})

Configuration options

Field	Type	Default	Description
`BaseURL`	`string`	`https://api.auditrails.io`	Override the API endpoint.
`BatchSize`	`int`	`100`	Maximum events per HTTP request.
`FlushInterval`	`time.Duration`	`1s`	How often the buffer is flushed.
`MaxRetries`	`int`	`3`	Retry attempts on `5xx` responses.
`Timeout`	`time.Duration`	`10s`	Per-request HTTP timeout.
`Logger`	`*slog.Logger`	`nil` (silent)	Structured logger for internal diagnostics.
`HTTPClient`	`*http.Client`	(default)	Provide a custom `http.Client` (e.g. with a transport proxy).

Logging events

Buffered logging (recommended)

client.Log() appends an Event to the in-memory buffer and returns immediately. The buffer is flushed in the background on FlushInterval. This method never returns an error — failures are logged internally if a Logger is configured.

client.Log(auditrails.Event{
    Action:   "user.login",
    ActorID:  "user_123",
    Resource: "session/sess_abc",
    Metadata: map[string]any{
        "ip":     "203.0.113.1",
        "method": "oauth2",
    },
})

Context-aware buffered logging

client.LogWithContext() behaves identically to Log() but respects context cancellation. If the context is already done when the call is made, the event is silently dropped. Use this in request handlers where you want cancellation to propagate.

func viewDocumentHandler(w http.ResponseWriter, r *http.Request) {
    docID := chi.URLParam(r, "id")
    userID := r.Header.Get("X-User-ID")

    doc, err := fetchDocument(r.Context(), docID)
    if err != nil {
        http.Error(w, "not found", http.StatusNotFound)
        return
    }

    client.LogWithContext(r.Context(), auditrails.Event{
        Action:   "document.viewed",
        ActorID:  userID,
        Resource: fmt.Sprintf("document/%s", docID),
    })

    json.NewEncoder(w).Encode(doc)
}

Direct (immediate) logging

client.LogDirect() sends the event immediately and returns the API response. It returns an error on failure.

resp, err := client.LogDirect(ctx, auditrails.Event{
    Action:  "document.deleted",
    ActorID: "user_456",
    Resource: "document/doc-789",
})
if err != nil {
    log.Printf("audit log failed: %v", err)
    return
}
fmt.Println(resp.LogID) // "01HXYZ..."

Direct batch logging

Send multiple events in one HTTP request, bypassing the buffer.

_, err := client.LogBatchDirect(ctx, []auditrails.Event{
    {Action: "document.created", ActorID: "user_123", Resource: "document/doc-001"},
    {Action: "document.shared",  ActorID: "user_123", Resource: "document/doc-001"},
})

Manual flush

client.Flush()

Framework integration

Standard `net/http` middleware

Wrap any http.Handler with a middleware function to automatically audit every request that passes through it.

package main

import (
    "net/http"

    auditrails "github.com/auditrails/auditrails-go"
)

func auditMiddleware(client *auditrails.Client, action string) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            next.ServeHTTP(w, r)
            client.LogWithContext(r.Context(), auditrails.Event{
                Action:   action,
                ActorID:  r.Header.Get("X-User-ID"),
                Resource: r.Method + " " + r.URL.Path,
            })
        })
    }
}

func main() {
    client, _ := auditrails.New(os.Getenv("AUDITRAILS_API_KEY"), nil)
    defer client.Close()

    mux := http.NewServeMux()
    mux.Handle("DELETE /documents/{id}", auditMiddleware(client, "document.deleted")(deleteHandler))

    http.ListenAndServe(":8080", mux)
}

This pattern composes cleanly with any router that follows the standard http.Handler interface (Chi, Gorilla Mux, etc.).

Error handling

Log() and LogWithContext() never return errors. For LogDirect() and LogBatchDirect(), use errors.As to unwrap an *auditrails.APIError and inspect the structured fields.

import "errors"

resp, err := client.LogDirect(ctx, auditrails.Event{
    Action:  "user.login",
    ActorID: "user_123",
})
if err != nil {
    var apiErr *auditrails.APIError
    if errors.As(err, &apiErr) {
        fmt.Println(apiErr.StatusCode)  // e.g. 401
        fmt.Println(apiErr.Code)        // e.g. "INVALID_API_KEY"
        fmt.Println(apiErr.RequestID)   // AuditRails request ID for support
        fmt.Println(apiErr.DocURL)      // Link to relevant documentation
        fmt.Println(apiErr.Retryable()) // true/false
    } else {
        // Network-level error (timeout, DNS failure, etc.)
        fmt.Println("network error:", err)
    }
}

Graceful shutdown

Calling client.Close() flushes all buffered events and stops the background goroutine. Always use defer client.Close() immediately after creating a client so shutdown is guaranteed even if your main function returns early.

client, err := auditrails.New(os.Getenv("AUDITRAILS_API_KEY"), nil)
if err != nil {
    log.Fatal(err)
}
defer client.Close() // Always paired with New()

For long-running services that handle OS signals, you can wire client.Close() into your signal handler as well:

quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
<-quit

client.Close() // Flush before exiting

client.Close() is safe to call multiple times. Subsequent calls after the first are no-ops.

​Installation

​Initialization

​Configuration options

​Logging events

​Buffered logging (recommended)

​Context-aware buffered logging

​Direct (immediate) logging

​Direct batch logging

​Manual flush

​Framework integration

​Standard net/http middleware

​Error handling

​Graceful shutdown

Installation

Initialization

Configuration options

Logging events

Buffered logging (recommended)

Context-aware buffered logging

Direct (immediate) logging

Direct batch logging

Manual flush

Framework integration

Standard `net/http` middleware

Error handling

Graceful shutdown