Go API Project Guide

Use this guide for Go APIs where low latency and predictable resource usage are important.

Architecture Scope

• HTTP middleware and handlers.
• Service/domain packages.
• DB and outbound client boundaries.

Setup

Initialize the SDK and wrap your handler with the provided middleware:

package main
 
import (
	"context"
	"net/http"
	"os"
 
	ob "github.com/obtraceai/obtrace-sdk-go/pkg/obtrace"
	mw "github.com/obtraceai/obtrace-sdk-go/middleware/nethttp"
)
 
func main() {
	client := ob.NewClient(ob.Config{
		APIKey:        os.Getenv("OBTRACE_API_KEY"),
		ServiceName:   "checkout-api",
		Env:           os.Getenv("OBTRACE_ENV"),
	})
	defer client.Shutdown(context.Background())
 
	mux := http.NewServeMux()
	mux.HandleFunc("/checkout", handleCheckout)
 
	http.ListenAndServe(":8080", mw.Middleware(client, mux))
}
 
func handleCheckout(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusOK)
	w.Write([]byte(`{"ok":true}`))
}

The middleware emits one span (http.server METHOD) and one log per request with method, route, status, and duration. Stdlib log.* calls are also captured automatically.

Gin and Echo middleware are available under middleware/gin and middleware/echo.

Environment Variables

OBTRACE_API_KEY=obt_...
OBTRACE_ENV=production

Validation Checklist

• Synthetic load emits stable telemetry
• Slow handlers appear clearly in spans
• Shutdown path flushes final queue
• log.Println() calls appear as structured logs

Production Hardening

1. Keep queues bounded to avoid memory pressure.
2. Monitor ingest errors and retries.
3. Validate instrumentation after router/middleware changes.

Troubleshooting

• Missing data under load: tune buffering/retry and inspect backpressure.
• Missing spans: ensure mw.Middleware wraps the outermost handler.
• Inconsistent tags: enforce shared middleware decorators.