Introducing the All-New Treblle Go SDK: A Rewrite to Support Treblle V3

We’re releasing a new version of the Treblle Go SDK, rewritten to support Treblle V3 and to better fit the needs of Go developers.

Overview

The SDK is designed for easy integration with both the Go standard library and popular frameworks, such as Gorilla Mux. It uses Go 1.21.

It provides middleware, automatic data masking, async support, and straightforward configuration.

Breaking Changes in v2

Version 2 of the Treblle Go SDK introduces breaking changes compared to previous versions. If you are upgrading from v1, you will need to update your configuration, middleware usage, and possibly some integration points.

Please review the new setup and example code before upgrading.

Configuration

You can configure the SDK using both an SDK token and an API key. Additional options are available for debug mode, masking extra fields, and enabling async processing.

treblle.Configure(treblle.Configuration{
    SDK_TOKEN: "your-sdk-token",
    API_KEY:   "your-api-key",
    Debug:     true,
    AdditionalFieldsToMask: []string{"bank_account", "ssn", "credit_card"},
    AsyncProcessingEnabled: true,
})

Middleware and Routing

• Standard Library: Use treblle.HandleFunc for route patterns and wrap with treblle.Middleware.
• Gorilla Mux: Add treblle.Middleware to your router with r.Use(treblle.Middleware).

The SDK normalizes route patterns for consistent analytics, regardless of the router.

Data Masking

Sensitive fields (passwords, API keys, credit card numbers, etc.) are masked automatically in requests and responses. You can add custom fields to the mask list at configuration.

Async Support

Monitoring and data transmission to Treblle run asynchronously by default. You can control concurrency and timeouts. There is also a graceful shutdown mechanism to ensure all data is sent before the application exits.

Error Handling

The SDK collects errors from your handlers, including panics, and reports them to Treblle. Batch error collection is supported, and errors are included in the analytics data.

CLI and Debugging

A CLI tool is available for inspecting the SDK configuration and debugging. It supports environment variables and shows masked API keys and tokens.

treblle-go -debug

Environment Awareness

You can specify environments where Treblle should not track requests (e.g., dev or test) using configuration or environment variables.

Tracking Customers and Trace IDs

You can associate requests with specific customers and trace IDs by setting custom headers before Treblle processes the request. This is useful for user tracking, correlation, and debugging across distributed systems.

Here’s how you can do it with a custom middleware:

func addTreblleHeadersMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Example: Extract user ID from your authentication/session logic
        userID := r.Header.Get("X-User-ID")
        if userID != "" {
            // Set Treblle user ID header
            r.Header.Set("treblle-user-id", userID)

            // Set Treblle trace ID header (from request or generate one)
            traceID := r.Header.Get("X-Trace-ID")
            if traceID != "" {
                r.Header.Set("treblle-tag-id", traceID)
            } else {
                r.Header.Set("treblle-tag-id", "trace-" + strconv.Itoa(int(time.Now().UnixNano())))
            }
        }
        next.ServeHTTP(w, r)
    })
}

Apply your custom middleware before the Treblle middleware:

api.Use(addTreblleHeadersMiddleware)
api.Use(treblle.Middleware)

Now, any request with X-User-ID and optionally X-Trace-ID headers will be tracked in Treblle with customer and trace information.

Concurrency and Performance

The Treblle Go SDK is designed to work seamlessly with Go’s concurrency model.

If you want to understand Concurrency in Go, check out our latest blog on the same.

All monitoring and data transmission to Treblle are handled asynchronously, so API handlers are never blocked or slowed down by network calls or processing overhead.

How It Works

• The SDK uses an internal async processor that runs in the background, relying on goroutines and a weighted semaphore (from golang.org/x/sync/semaphore) to control concurrency.
• Each request is processed in a separate goroutine. The SDK enforces a configurable limit on the number of concurrent operations (default: 10), ensuring that Treblle’s processing does not overwhelm your server or introduce backpressure.
• If the concurrency limit is reached, new monitoring jobs are dropped rather than blocking your API, so your endpoints always remain responsive.
• All async processing is managed via a sync.WaitGroup and context timeouts, ensuring clean shutdowns and no resource leaks.

Because all Treblle operations are offloaded to background goroutines, the SDK adds virtually no overhead to your request/response cycle. Your API endpoints return responses as fast as they would without Treblle, and monitoring is handled independently.

You can adjust concurrency settings in the configuration:

treblle.Configure(treblle.Configuration{
    // ...
    AsyncProcessingEnabled: true,
    MaxConcurrentProcessing: 20, // Increase or decrease as needed
})

By default, async processing is enabled and tuned for typical production workloads.

Examples

The repository includes practical examples for both the standard library and Gorilla Mux:

• Standard Example
• Gorilla Example

Key Features

• Configuration setup updated with SDK token instead of ProjectID to match the V3 platform updates
• Middleware for the standard library and Gorilla Mux
• Automatic and configurable data masking
• Asynchronous processing with no API performance impact
• Graceful shutdown and batch error collection
• CLI for configuration and debugging
• Environment-based logging control
• Customer and trace ID tracking

Getting Started

You can install the SDK using
go get github.com/treblle/treblle-go

Configure it, add the middleware, and you’re ready to use Treblle V3 features in your Go API.

For more information, see the README.